The Document Trifecta

I wanted to make a series of posts to start that was a bit of a step-by-step journey through getting this thing going, but I realize that would probably be pretty boring at least in the earlier stages. In the interest of keeping things at least somewhat interesting, and for the sake of not having each post being so dense and dry it puts holiday fruit cake to shame, I’ll do my best to keep things brief for the general set up. Especially because many folks will read these first few posts and think, “So - you actually planned a project and it was some kind of big revelation?” I mean - kinda. I don’t think it’s uncommon for engineers working on personal projects to fall into a trap of winging it a bit compared to the systems used in their professional work. Some of that is cost and scale - I personally don’t need something like JIRA to track the work for my personal site. Some is attitude: “Eh, I don’t need all that structure and tracking. I Know What I Want.” Well, for me, that obviously didn’t work out. The MVP wasn’t well defined, the scope ended up seeming much bigger than it needed to be to get to first launch, and I was starting without any design or information architecture artifacts. Combined with neurospicy tendencies, it was a setup that was doomed from the start. This time around, I wanted to do my best to treat this like a proper project instead of a science experiment, despite it being a little bit of both. I decided to lean more into planning and documenting before I began. It was a bit difficult at first; I definitely had to ignore the voice in my head saying, “Do we really need this?” a non-zero amount of times. And, sure - it’s likely three full documents might be a little bit overkill. But having these decisions documented has made the process feel significantly smoother. With less friction to make progress, it has been easier to keep motivated. Let’s take a look at the Document Trifecta: a project brief (quick “who/what/where/when/why/how”), Foundations (the soft decisions: voice, purpose, positioning), Architecture (as it says on the tin: architectural decisions), and a bonus TODO list that helped keep the wheels turning.

Triforce

Project Brief (Like saying Macbeth in a Theatre)

I know. Those two words in that particular order can raise the hair on the back of your neck. There are some things I did the same this time around. I started a conversation in a ChatGPT project and gave it the following instructions:

You are a seasoned software engineer and engineering manager. Your background is SaaS software, but you have experience in web development as well. You are comfortable in the full stack. You are up to date on current trends in the software engineering world, including using AI tools. You are familiar with the current popular languages, patterns, and frameworks.

When responding, rely on your industry and technical knowledge.
Suggest topics, languages, or frameworks to look into based on your knowledge and the use case.
Responses should consider trends and be up to date, and consider the direction trends are moving.
Be a collaborator. Don't just agree with every input, use your knowledge and outside resources to discuss options and help find the best solution.

This is similar to how I began the last iteration of this project, but this time I wanted to take a more organized approach to the planning phase. I have always found the conversational interface for working with ChatGPT made evolving an idea flow more smoothly and quickly than relying exclusively on Google searches. Meaning, it’s easy to start spitballing an idea and evolve it to a project, all in the same conversation. This cuts both directions, at least for me. It is great in that as the idea develops and things pop into my head, I can bring them into the conversation naturally and let the idea become more and more structured as the conversation continues. The downside I often run into is two-fold:

1. I often find branching paths I want to explore in the conversation, but as I explore one path, I forget about other branches as more and more pop up.
2. Eventually the history is dense enough where finding those branching paths/reminding myself where they were is time consuming and steering the conversation back can sometimes be difficult.

What I decided to do this time around was try to break conversations up to keep the context smaller and more focused. Additionally, after hearing about it from colleagues and wanting to be a better note-taker myself, I began exporting relevant conversation summaries as Markdown files and filing them in a project in my Obsidian vault. More on that later.

The first conversation started with this prompt, and was pretty short:

What are some modern tech stacks that are suited for a software engineer's personal site/blog? I have experience with React and Ruby on Rails, but I do not mind learning something new for the sake of the project (it could be a portfolio piece itself).

It compiled a list of a half a dozen options, ranging from the current popular front-end frameworks to rolling my own content management system (Downsides: Overkill for solo projects). It made two recommendations based on my experience according to the prompt I gave originally and other context it gathered from me using it in the past - specifically v1 of this site. Those were Astro or Next.js, Tailwind, and MDX.

I chose Astro due to the fact that this site will be mostly static. If I wanted to experiment with Next.js down the road, I could then create a new project that would be a better showcase of the technology. I was returned a list of pros and cons and a confirmation that, based on the information already gathered, Astro seems like the ideal fit. This gave me a good tech backbone for getting the project details together.

My next step was to create a document that was a guidebook to help me get things off the ground. I fired up a new chat, and fortunately I was able to leverage some of the context from the v1 project I had already created in ChatGPT:

I am restarting the project for Impaired Programming. The concept is the same. Do you have context for this, or shall I bring some over from the other Blog project?

“Concept” in this case is what was explained above - a personal site/blog that explores working alongside AI agents with a casual “tinkering with a beer in hand” approach. I got a short recap of the context ChatGPT had from the last project, as well as options on how to proceed. I chose keeping the same ideas and approaches, but ditching any design/copy/etc and reconfiguring the tech stack - especially since this was the major hangup on the first go around.

Once we hammered out some of the more specific details on what was sticking around versus what stayed on the cutting room floor, I had the agent generate a high-level document summarizing the decisions we made. This essentially became my project brief - focusing on purpose, core themes, some basic information architecture to get started, success criteria/anti-goals, and some next steps. This was a change from my first attempt - at this stage, the document I had was a phased development approach to building out various features for the site. I didn’t have the intangibles sorted - instead of getting a better understanding of what and why I was building things, the drive was writing code. Well, orchestrating the writing of code, at least.

Foundations

From the conversation that birthed the project brief, I was presented another concept I hadn’t considered the first time around: Give more shape to the information architecture, content primitives, and “brand constraints” - a loose, “feely” description of the site’s design. I plucked out this section of the conversation, and started another to hammer those things down a little more definitively. During this conversation, I was able to suss out things like:

What is the home page trying to do for a first-time visitor? What does the visitor see next? What and how much content is needed to at least get this out in front of people? It’s fine to talk about writing software but let’s see the turkey What does the basic blog post need in terms of metadata, citations vs. links, etc? What is the tone/voice of the site? What am I trying to signal with the content of pages like “About”?

Once we settled everything, I had ChatGPT output a Markdown file called “Foundations” and added it to the Obsidian vault.

Architecture

I knew I wasn’t quite ready to start making engineering decisions yet, so pulled that thread some:

Are there any technical/tooling/architecture decisions that need to be done before we write a "todo list"?

I was a bit surprised at some of the stuff that was considered important at this stage - analytics, SEO and syndication, etc. I hadn’t even gotten Astro initialized! I started to feel a little overwhelmed. So much to do, so much I hadn’t considered, how am I going to get all this done, do I even need all of this? I started skimming instead of poring over the entire response (it was considerable), and once I saw the TL;DR at the end, opted to pick that as a place to start to keep scope minimal. Finding that summary helped defeat the overwhelm and keep momentum:

Minimal decision set to unblock a solid TODO list

If you pick these 5, you can write a high-confidence TODO list immediately:

1. Host (Cloudflare Pages vs Vercel)
2. Content source (Markdown/MDX in repo)
3. Static vs SSR (likely static)
4. URL conventions + taxonomy
5. Tooling baseline (pnpm + prettier + eslint + tsconfig)

So I ran some comparisons between Cloudflare and Vercel, decided on a content management strategy (use a CMS or keep it simple with Markdown-in-repo). Once I worked through these few points, I had the agent create a markdown file called Architecture, and added that to my Obsidian vault as well.

Bonus doc: TODO

Time to get some code going, right? Well… kinda. I was starting to do odds and ends to get things moving (creating the repo in GitHub, getting global engineering tools installed, etc), so before I got too caught up, I figured I would double check what I already knew - what homework did we have to do on the technical side. I started a new conversation, and got some opinions:

I have created a repo in GitHub, and cloned the directory locally. We created a foundations.md and an architecture.md. I have not set up/installed claude yet. Should we make a todo list? I think there are still some things that need to be done before we make a development plan/start making github issues for starting development work.

A three-part TODO.md was created:

A. Pre-issue decisions (small, but blocking) B. “Bootstrap” tasks (can become GitHub issues) C. Tooling / AI workflow (optional but helpful)

Section A had some repeats of things that were decided in Architecture and Foundations such as post frontmatter and content strategy, but there were a couple things as simple as choosing and pinning a package manager/version, what kind of styling baseline (Tailwind), and deploy target. I made this a markdown file and stuck it in the repo directory, which was otherwise mostly empty. I tackled a few of those decisions in the conversation window, installed Yarn and the latest version of Node supported by Astro. You’re probably thinking to yourself, “You made changes to package.json… without having initialized the Astro project?” Yep - sure did. I was mostly curious what kind of sequence the LLM would suggest. I can say - it was the non-optimal solution. I ended up having to remake a few of these edits, but fortunately they were small and relatively inconsequential.

After the pre-issue decisions were squared, I updated (regenerated?) the TODO list in the repository and made some modifications to the Architecture file. Now the fun part - setting the stage to put it all into motion.

Time to get our hands dirty

Now, the next couple steps were pretty typical for initializing any modern JavaScript-based project. I followed the Astro documentation to init Astro in my repository and re-made some of the edits to package.json and other config files that were overwritten. After that, I installed Tailwind through Astro, which updated the Astro config automatically, and added the typography plugin.

# Add Tailwind
yarn add astro tailwind

# Add typography plugin
yarn add -D @tailwindcss/typography

The config for Tailwind 4 is pretty light, so I just imported the typography plugin in the global.css file and I was off to the races. At this point, the repo looked something like this:

ImpairedProgramming/
├── src/
│   ├── pages/
│   │   └── index.astro
│   └── styles/
│       └── global.css
├── .editorconfig
├── .gitattributes
├── .gitignore
├── .npmrc
├── .tool-versions
├── .yarnrc.yml
├── astro.config.mjs
├── package.json
├── README.md
├── TODO.md
├── tsconfig.json
└── yarn.lock

Still working in the command line myself, just trying to get the lay of the land. At this point, I committed the boilerplate and decided to init Claude Code.

Hello, Mr. Anderson

Installing Claude Code and running init, it automatically consumed the TODO.md file and made appropriate entries into the CLAUDE.md file. I mentioned the TODO was actually out of date (oops - hadn’t copy/pasted from ChatGPT in a while), and that I had a couple other Markdown files.

I considered making a /docs directory in the repository, until I remembered reading about my pal Damian’s workflow. This taught me I could add my Obsidian vault directory to Claude’s context using /add-dir, making it seamless to access and update the files as things change. Once I did this and gave Claude guidance to use the Impaired Programming directory, it consumed all three documents (Project Overview, Architecture, and Foundations) directly from Obsidian, subsequently updating the CLAUDE.md and even the TODO.md after. And that’s where we find ourselves as of the time of this writing.

The moral of the story that I am hoping will hold throughout the project is that the planning phase is just as important as the building phase. I want to reiterate that I understand this is not particularly shocking to anyone, especially those who have built things either by hand or with code, professionally or as a hobbyist. The struggle I often run into when working on something for myself is riding the sine wave of neurodivergent tendencies. Excitement to get started brings hyperfocus for a period of time, then the frustration sneaks in when you realize in your haste you didn’t set yourself up for success by planning quite enough. The idea of doing all the planning and designing and research is then either boring or overwhelming because all the hyperfocus has caused burnout. Suddenly, the project isn’t fun anymore and it’s impossible to focus on it, eventually leading to it being left to wither and die before it even saw daylight. Rinse and repeat, and there you have a good 1/3 - 1/2 of my private GitHub repositories.

By keeping the scope small and focused, planning more up front/documenting my decisions, and not pressuring myself into a strict schedule for writing, I am hopeful that I will be able to use this platform to gain momentum on some of those long-forgotten corners of ~/Projects. I’d love to have you along for the ride, if you care to join.

See ya in the next one.