How I write documentation at Pieces

Documentation is principally User Experience (UX), not a digest of facts. At least, that’s the way I look at it. 

As developers, we’re wired to want proof because we’re inherently untrusting. We don’t just want something to ‘work’, we want to make sure we’re comfortable with the input and output and the exact process that makes something work.

So when a user lands in our documentation, that’s our moment.  That’s our shot to prove not just that the tool is real, but that the people behind it actually care about whether users succeed, and that should be evident in the documentation itself.

From my perspective, documentation is one of the most visible indicators of product quality. 

As users, if we read out-of-date documentation that doesn’t line up with what we’re experiencing in the application or using the service, it just leaves a bad taste.

Specifically, it tells users how well the product is architected, how often it changes, and how much internal alignment there is between engineering and experience. It tells them if the product is legit or if the only goal was to ship something that looked legit. 

I think about this every time I write a new guide or restructure a piece of documentation at Pieces. The docs themselves are just as much a product as the product itself. It sells, it informs, it provides examples, it gives insight, and it’s important. 

Docs are infrastructure 

Let’s stop pretending that documentation is “supporting content” or that it’s just a fancy user manual with a few nice-looking pieces of embedded media. 

Nope, documentation is infrastructure. 

It’s an interface for how users navigate complexity. It’s the bridge between user intent and system behavior, and if there’s something off about the product, the user reads documentation to understand it – if the documentation doesn’t line up with what a product really is or what it can do, it sends a clear signal that more work and care is needed. 

In that way, the relationship between the product and the documentation that supports it is very symbiotic. 

At Pieces, I try to treat user-facing documentation the same way our engineers and developers  treat system modules – with a ‘docs as code’ approach:

• It’s versioned

• It has a surface area

• It has dependencies

• It can break

• It can decay

• And it has to scale

So when I build documentation, whether it’s a deployment guide for LLMs or a setup flow for MCP, the questions I ask aren’t:

• “How do I explain this?”

• “What are the right words?”

Okay, let’s be honest. Sometimes I have to ask those questions.

But seriously, I have to consider: 

• “How does this fit into the product's mental model?”

• “What problem is the user trying to solve at this moment?”

• “What decisions did engineering make that users will now need to understand?”

• “Is the flow from this feature to the next an intuitive one?

Docs as infrastructure means we treat them like code: it’s modular, maintainable, and system-aware.

Docs-as-Code isn’t a workflow. It’s a mindset

It’s easy to talk about docs as code like it’s a CI script and some markdown, but it’s a lot more than that!

It means documentation lives in the same repo (or at least the same rhythm) as the codebase. 

It’s written, reviewed, merged, versioned, and deployed just like features are. It needs to be timed. 

It means collaboration with growth members for new graphics, clarification, and meetings from developers on specific technical details, or 1:1 (and plenty of solo) testing from a user perspective to hash out micro-copy. 

At Pieces, that means:

• Every new feature requires documentation

• New documentation  is reviewed by product and engineering, not just the writer(s)

• Net new docs are staged, tested, and previewed before merge

• Documentation updates are often gated to the same flag as the feature release

Why does this matter?

Because it makes sure that user-facing documentation isn’t lagging behind product changes. 

There’s no six-week follow-up with “finalized guides” because, in an ideal world, the documentation ships with the feature.  This means there’s no guessing what’s live vs. what’s in dev. 

You can't ship a feature if you can't explain it!

Here’s exactly how I write docs (and where I use AI)

Let me be clear: It’s just not realistic, at least at this stage, to use basic AI tools to generate technical documentation, at least directly. 

It takes way too much effort to fact-check its output, make sure it’s not hallucinating egregiously, get it to actually generate copyable markdown (that’s a topic for another day…), and more. 

It is quite literally less time effective due to the complexity and the contextual knowledge required to generate AI documentation than it is to just write it myself.  

But I use AI at several ‘checkpoints’ through the writing process. Here’s what that looks like: 

Voice → text

I talk through the problem into a transcription tool. Not with perfect phrasing, just ideas, angles, structure, maybe analogies, maybe “what the user needs to understand here.” 

Sometimes I’ll describe an actual UI element or an entire view, as well as my take on how I navigated from one button to another and what different bits of microcopy meant to me before I understood how to use it perfectly. This context is absolutely crucial. 

Breakdown with an LLM

I paste the transcript into a fresh chat and ask it to organize a markdown-style structure. 

I prompt it to give me a page outline with a header hierarchy: just the basics, no need to worry about the actual markdown implementation (components, frontmatter, etc.) yet. 

Now, I have a hierarchy and a proposed structure to start refining that is already infiltrated with my real-world, experiential context. 

Manual writing

I go through line by line and actually write the sections. 

I’ll transform bulleted concepts into full sentences and ‘leap-frog’ as I write–i.e., I’ll start each new section by leaving the bullet point until after the paragraph is written. 

Sometimes I’ll stop and check:

"Does this explanation follow from the premise?”

I paste in the H2, the paragraph, and ask the LLM to review it for logic or clarity, not tone (as a part of prompt evaluation). 

We all know AI is terrible when it comes to actually understanding natural, human tone–so avoid trying to use LLMs to improve the ‘sound’, the ‘feel’, or the ‘flavor’ of your writing. 

Hint: One of the key words I use when prompting is “chronological”, specifically when determining the flow and cohesiveness of a piece of documentation. Use “chronological” to guide the LLM to check the header structure and the content of the roughly-written (but manually-written!) paragraphs and sections follow from each other, and that nothing is out of place. 

Final pass

At the end, I paste the entire piece alongside the original transcript–this is perhaps the most important step. 

Why?

It will tell me if the final product actually followed the original train of thought, answered the questions I had as a user, accomplished the goal, logically makes sense, and fits into the bigger picture (if I had provided additional context). I’ll ask:

And I get flagged. And I fix them – only then do I call it a ‘draft!’ 

LLMs don’t write for me. They challenge my structure, spot my blind spots, and catch me when I’m straying into over-detail or over-explanation. 

That's how they’re useful.

When Pieces is my OS

There are a few different styles or ‘moods’ of writing for me. 

Calm writing, iterative drafting, and complete and utter chaos. 

1. Calm writing: Looks like I’ll need to update the installation instructions for this one section. Let me make sure I update that in this other place, too. 

2. Iterative drafting: Okay, this section was pretty complex, but now that I’ve got these 3 pages together, let me make sure they all follow the same structural conventions. Looks like I forgot to use a callout here. Let me put that in.

3. Utter chaos: I need to rewrite the entire Pieces Desktop app documentation. There are 3 new features, 2 changed references that need to be made on 8 different independent sets of documentation, and I haven’t even thought about the media…

When I hit #3, I use Pieces to help me navigate to-do lists, meeting notes, and general context.

Not to write but to remember (and long-term memory is everything in our product).

When we migrated our entire documentation stack, I had:

• Snippets

• CLI flags

• Internal links

• Deprecated branches

• GitHub permalinks

• Notes from 4 conversations

• TODOs from 3 DMs

• Visual references from a Figma redesign

I wasn’t going to sort that manually. I didn’t have the mental capacity to write in chaos-mode, build a new platform, and remember every single note, request, or requirement from every engineer.

So I saved whatever I could to Pieces, periodically and consistently, so I didn’t have to!

And that gave me local, real-time, contextual breadcrumbs for everything I needed to write and wire without having to flip through chats, open up 5 Google docs, or re-read transcripts from a meeting last week that was buried in my email. 

Pieces is like my memory layer, I can stay locked in on writing documentation, then reference my Long-Term Memories when I need to. 

Since Pieces is actively capturing new workflow memories in addition to keeping whatever I store intentionally, it can ‘self update’ itself and give me whatever’s most relevant, right when I need it that’s what it’s good at.

If I need to bounce between tools, or resurface a decision from last week’s dev meeting, or remember how a config flag was expressed in beta–that’s where Pieces re-enters the flow.

For developers, it’s perfect for capturing intermediate work, like code you’re testing, results you want to keep, and logs you don’t want to forget.

Building documentation as a Product

Every header in your docs is like a modal in your UI. Every paragraph is a function signature for understanding. 

Every list is an abstraction boundary; every piece of copy is just as important as the most critical microcopy in your application. Documentation is a reflection of the product behind the flashy marketing site–and so on…

.. but if it’s broken, users bounce. If it’s good, they trust you. 

That’s why myself , and the documentation team here at Pieces design documentation, which is certainly different than just putting out release notes or updating a changelog (btw, here is ours to keep an eye on). 

The difference here is felt when a user lands on our documentation site, reads a setup guide or a Get Started section, runs the installation script, and says, “Hey, that actually worked. And this was an aesthetically pleasing piece of documentation to look at, too. Let me click around…”

That’s where trust is built for the product, and that’s what I build for.