Skip to content
All writing ‹ Part 08 of 08 · Docs in the AI Era: Keep It Simple
Engineering · 3 min read

Summary: What to Take Back to Your Team

A summary of the Docs in the AI Era series: each part in one line, the golden circle behind them, and six questions to start your team discussion.

This is the end of the series. Here is what to take back to your team: each part in one line, the idea that ties them together, and the questions to start with.

The series in seven lines

  1. Write Only What Your Reader Cannot Find: An AI agent is a reader too. Write only what your reader cannot easily find.
  2. How a Doc Goes Stale: A doc that is easy to write still goes stale. Design every doc to be easy to change.
  3. Name the Pain Before the Tool: Docs go stale for machine, process, and people reasons. AI fixes only the machine one.
  4. Strict Rules Only Where a Machine Checks: Make a rule strict only when a tool can check it. The rest are habits.
  5. A Good Name Is a Doc You Never Write: Names and small symbols are docs too.
  6. Remember Where, Not What: Remember where to look, not what is inside.
  7. Keep Docs Alive: Three reminders, and changes that flow in one direction.

The golden circle

Put together, the seven parts fit one golden circle.

WHAT HOW WHY
Read it from the center out: why, then how, then what.
  • WHY: A doc that the right person reads and uses has value. Other docs do not.
  • HOW: Keep it simple: fewer rules, direct links, less to remember.
  • WHAT: A doc practice that fixes the real pain, that the whole team agrees on, and that the team actually uses.

Questions to take to your team

I do not give answers here, because each team has different pain. Start your next discussion with these:

  1. One doc for all readers, or one doc for each reader? (part 01)
  2. Which fields must every doc have? (part 04)
  3. How do we name doc titles and IDs? (part 05)
  4. A team tag list, doc type only, or no tags? (part 06)
  5. How fast must we fix a wrong doc? (part 03)
  6. What information must a code-change reminder include? (part 07)

A first step to try: one owner, one product folder, one month. Then review together what worked.

You do not need the “best” tool. You need tools and a process that fit you and bend. If your needs change, the tools and the process change too. First, know your real pain. Then you do not get lost in AI information overload.

References

Related: go back to the series overview: Docs in the AI Era, or start again from part 01.

Tags #docs-in-ai-era #documentation #llm
↑↓ navigate ↵ open esc close