I Built a Project Documentation Gem — Here's What It Actually Does

Keywords: project documentation, runbook writing, technical documentation, Gemini Gem, architecture docs, handoff documentation, infrastructure documentation

Reading time: ~8 minutes

Project documentation is one of those tasks that everyone agrees is important and almost no one enjoys writing. I've built and maintained infrastructure for 25 years and I've seen what happens when documentation is missing, outdated, or written for the person who built the system rather than the person who has to maintain it at 2am. The cost is always paid later, by someone who didn't write the docs.

Documentation work involves two different kinds of effort. The first is technical: knowing what the system does and how it works. The second is writing: translating that knowledge into something another person can follow without the author present. I'm fine at the first. The second is where I wanted help — the consistent, structured, formatting-heavy work that takes longer than the actual content suggests.

My Project Documentation Gem doesn't write the documentation for me — the technical content has to come from me. But it handles the structure, formatting, and the completeness check that catches what's missing before the doc goes out.

The Problem I Was Trying to Solve

Three specific problems kept showing up in documentation work:

First, inconsistent structure across docs. I'd write a runbook one way for one system, a different way for another. New engineers had to learn the structure of each document separately rather than the content. The Gem gave me a consistent template that I could populate — readers know what to expect, and I don't have to remember where each section goes.

Second, missing sections I forgot to include. Every project needs an architecture overview, a deployment procedure, a rollback procedure, a troubleshooting section. I'd write most of them but consistently forget at least one. The Gem's completeness check catches the gaps before the doc ships.

Third, time spent on formatting instead of content. The mechanical work of getting headings consistent, code blocks formatted right, tables aligned — that was eating time I wanted to spend on the actual technical content. The Gem handles the formatting overhead.

I wanted a tool that would let me focus on the technical content and let the tool handle the structure and completeness.

What I Tried First (and Why It Wasn't Enough)

My first approach was a Google Docs template with sections pre-filled. The template helped but I still had to remember which sections applied to which project type, and the formatting work remained.

Second was a checklist I kept next to my keyboard while documenting: "Architecture? Deployment? Rollback? Troubleshooting?" The checklist helped with the completeness problem but added friction to the actual writing.

Third was using a general-purpose AI with a long prompt explaining our documentation standards. This worked but the context had to be re-pasted each session, and the AI would sometimes drift into generic documentation advice.

What I wanted was a tool that already knew our documentation patterns and could generate the right structure based on what I told it the project was.

The Project Documentation Gem did exactly that.

The Gem I Use

Here's the core of the instructions I saved into the Gem:

You are my project documentation assistant. You help me produce structured technical documentation: runbooks, architecture overviews, configuration guides, project handoffs.

When I describe a system or project I'm documenting:

  • Generate the appropriate structure based on the doc type (runbook vs architecture vs handoff)
  • Populate sections with my technical content, not invented content — ask if anything critical is missing
  • Flag sections that are commonly forgotten for this doc type
  • Use consistent formatting: code blocks for commands, tables for configuration, numbered lists for procedures
  • Keep language direct — this is documentation for engineers, not marketing

My context: IT infrastructure team. Docs are written for engineers who need to operate, troubleshoot, or modify the system. Most are read at 2am by someone who didn't build it. Clarity over comprehensiveness.

The "ask if anything critical is missing" instruction turned out to be more important than I expected. Without it, the Gem would happily generate a doc with whatever content I'd provided, leaving gaps I hadn't noticed. With it, the Gem surfaces the missing pieces before the doc is finalized.

Two Real Examples — Before and After

These are based on actual documentation projects from the last few months. System names are changed but the documentation patterns are real.

Example 1: New Service Runbook

Situation. We'd deployed a new internal service and needed the runbook before it went into the on-call rotation. I had the technical content in my head and a rough outline in my notes — but converting it into a usable runbook that someone else could follow at 2am was going to take time.

What I asked the Gem:

"Generate a runbook structure for our new internal metrics service. Here's what it does, how it's deployed, and what monitoring exists."

Gem's response (excerpt):

Standard runbook sections for this service type:

  1. Overview — what the service does, who owns it, on-call rotation
  2. Architecture — components, dependencies, key ports/endpoints
  3. Deployment — how to deploy from scratch, how to deploy a change
  4. Rollback — how to revert a bad deploy, time required
  5. Monitoring — what dashboards exist, what alerts fire, what to check first
  6. Common issues — known failure modes and fixes
  7. Escalation — who to contact for what, including out-of-hours

You mentioned deployment and monitoring. You didn't mention rollback procedure or known failure modes. The rollback section is critical for an on-call runbook — if a bad deploy goes out at 2am, the on-call engineer needs explicit rollback steps, not "redeploy the previous version." Want me to draft a rollback section template based on the deployment info you shared?

What the Gem got right. It generated the structure based on doc type (runbook, not architecture overview). It flagged two sections I hadn't thought through — rollback and known failure modes — both of which are critical for an on-call runbook. It didn't fabricate content; it asked for the missing pieces.

What I changed. About 10% — I added the rollback section content the Gem requested, removed one section that didn't apply (escalation was handled at a different level), and reordered slightly for our team's reading patterns. The structure and the completeness check were the Gem's.

Example 2: Legacy System Architecture Documentation

Situation. We had a legacy system that several engineers had worked on over the years but where no current engineer had the full picture. The system was stable but undocumented, and we needed an architecture overview before any new work happened on it. I had partial knowledge and access to people who knew other parts.

What I asked the Gem:

"Generate an architecture overview structure for our legacy monitoring aggregation system. Here's what I know about it: [content]."

Gem's response (excerpt):

Architecture overview structure:

  1. Purpose — what problem this system solves, why it exists
  2. Components — major pieces and their roles
  3. Data flow — how data moves through the system (text or diagram)
  4. Dependencies — what this system relies on (upstream and downstream)
  5. Configuration — where config lives, how it's changed
  6. Known limitations — known weak points, deprecation plans, scaling limits

Based on your input, you've covered purpose, components, and dependencies. Three sections are missing or thin:

  • Data flow — you mentioned input sources but not how data moves between them. A new engineer reading this would not understand the path from source to storage to query.
  • Configuration — you didn't mention where config lives or how to change it. For a legacy system, this is often the riskiest area.
  • Known limitations — if there are any, this section prevents the next engineer from rediscovering them.

Want me to draft these sections as placeholders with the questions a new reader would need answered?

What the Gem got right. It generated the right structure for an architecture overview (different from a runbook). It identified three specific gaps in my input. It offered to draft placeholder content rather than fabricating specifics. The structure matched what I'd write by hand.

What I changed. About 20% — I added the data flow section by interviewing the engineer who knew the data path best. The Gem's draft was the starting point; my colleague's knowledge filled in the actual specifics. Configuration section went through a similar process with another engineer.

Where This Works and Where It Doesn't

After about two years of use, here's an honest assessment.

It works well for:

  • Generating the right structure for the doc type. Runbooks, architecture docs, handoffs — each has a different structure and the Gem knows it.
  • Catching missing sections before publication. The completeness check is the highest-value feature.
  • Formatting consistency across docs. The Gem's formatting rules produce consistent output regardless of who writes the doc.
  • Reducing the time from "I know the content" to "I have a usable doc." The structural work is what takes time when the content is already clear.

It doesn't work well for:

  • Documentation that needs genuine technical investigation. If the content isn't already clear in your head or in conversation with others, the Gem can't extract it.
  • Documentation requiring deep architectural diagrams. Text is fine; complex multi-component diagrams are better done with a proper diagramming tool.
  • Highly specialized documentation patterns. If your team has non-standard documentation conventions, the Gem defaults to common ones and you have to push back.
  • Final review. The Gem produces drafts. A human should always review before the doc ships to production.

How to Set This Up

Five-minute setup:

  1. Create the Gem and paste the instructions from the previous section.
  2. Edit the "My context" paragraph to match your team's actual documentation patterns — what kinds of docs you write, who reads them, your conventions.
  3. Try it on a doc you're currently working on. Use the structure as a starting point and fill in the content.
  4. Refine the instructions after your first three docs. The Gem that matches your team's patterns is more useful than a generic one.
  5. Use it consistently. The value compounds over time as you and the Gem develop shared conventions.

The most common mistake is treating the Gem's output as final documentation. It's a structured draft. The actual technical content — what the system does, how it fails, what to do about it — comes from the engineer who knows. The Gem's job is to make sure that knowledge doesn't stay trapped in one person's head.

A Note on What This Replaces

The Gem doesn't replace the technical knowledge. It doesn't replace the judgment about what to document and what to skip. And it doesn't replace the discipline to keep documentation updated as systems change.

What it replaces is the structural overhead — the consistent formatting, the completeness checks, the right section for each doc type. For me, that's roughly a third of the time spent on any documentation project. The other two-thirds is still the work of figuring out what to say and verifying it's accurate.

The wins are mostly time savings on documentation that I'd have written eventually anyway. For documentation that wouldn't have been written without the lower barrier (legacy systems, handoffs after departures), the wins are bigger — those docs exist now where they wouldn't have before.

Related Reading

Sources

— Justin

📅 First published: 2026-05-08 | 🔄 Last updated: 2026-06-21