The Document Document

Intro

Clients frequently ask for help with their documentation. Here are speaking notes for this 45-minute presentation on our philosophy and guidance.

[public] The Document DocumentGoogle Slides

Introduction

“Documentation” means lots of things to lots of people. Differences of opinion. Here’s mine.

Important Considerations: [5-10 minutes]

Factors to consider as you think about your documentation strategy:

1. Culture – signals level of directness, transparency, collaboration, rigor, speed
2. Purpose – for how many people, and what is its reason?
   1. e.g. differences between: assess progress, clarify thoughts, coordinate team efforts, defend in a lawsuit
3. Lifespan (“ephemerality”) – how long do you expect this particular document to live?
4. Rituals – when and how and why will it be referenced? Who initiates the ritual?
5. Less is more – aim for least amount needed, and no less
6. Tooling matters (but emphasis is on fit and usage, not which tool)

You know you are doing it well when:

1. Docs are relatively recent E.g. were the majority of docs you see at quick glance updated within last six months?
2. Do people reference them? E.g. when you ask how or why about a feature, does someone explain it to you or send you a link to a doc?
3. Is training included in onboarding process? And is it re-upped regularly? E.g. does onboarding include where and how to find info, and practices on how to contribute?

Personal Reflection - GitLab & DoubleGDP: [15 minutes]

How do their company and product docs fit?

1. Culture – developer tools / open core software; direct and transparent; rigorous and fast; low levels of shame. “Everyone can contribute”
2. Purpose – 2700 team members across 65 countries. 4000 open source contributors. High reliance on asynchronous work.
3. Lifespan – segmented by ephemerality. Google Docs → Issues / Stories → Epics → Handbook (living document, “handbook first”)
4. Rituals – everyone sends handbook links to answer questions. Make suggestions / proposals via MRs; “source code metaphor.”
   1. MRs forced suggestions to be incremental, specific, and actionable. If approved, it’s in effect. Rollout / training done via an issue – that’s ephemeral content.
5. Less is more – Huge handbook, but improved via minimum viable changes
6. Tooling matters – Docs for meetings, GitLab for everything else.

Examples and Tips: [10-15 minutes]

Examples are difficult to find!

1. Strategy
   1. 5 questions to answer, per Roger Martin
   2. Amazon Strategy Guidance, not their strategy document, but shows how AWS approaches strategy documents.
   3. GitLab Strategy Process also not their document, but their guidance on process
2. Goals
   1. Scorecard example illustrates product-level goal tracking
3. Product Briefs (PRD) - Lenny published a bunch of templates; work reviewing, though I prefer examples. Rose Marsh also has guidance and templates.
   1. Define Duo Scope has pretty good brief on what they’re aiming for
   2. AI Taskforce has good “WIP Table”, link back to handbook, and epic board
4. Epics -
   1. Work item status – clear top-line, problem statement
   2. Production readiness – “collection” epic that references handbook for definition and provides tracking for discussion that happened in team sync
   3. Discover / fix deficiencies –
5. Stories / issues - typically 2-4 weeks to live. Keep small, and in issue tracker. Close when complete.
   1. Parabol – clean, simple. Typical to need some bullets, but keep it light – aim for “reminders of things discussed” rather than “specs”.
   2. Add test review step - a problem-solving type issue. Clear goals, thoughts on solutions.
6. Meeting Notes - most ephemeral – usually valuable just to capture takeaways to do right away or to put in a better tracker

Closing Thought: [5 mins]

1. Documentation is an investment – takes real thought, time and energy, reinforcement. Not just a by-product. Pays off in faster decisions, less re-work, fewer meetings.

Talking Points Best Practices [Skip. Only if asked]

Compiled practical guidelines / rules of thumb from SV tech companies. Adapt as you see fit.

1. Strategy - V2MOM framework, used by Salesforce is clear and concise. Friend has had good experience in multiple companies using it. Suggest: revise quarterly. (Examples in link)
2. Goals - Cascade methods, ideally one per team, from V2MOM. OKRs are another popular framework, require a bit more enforcement.
3. Briefs - start with one sentence explaining to a non-engineer why it’s worth the expected investment of time. Use as output of discovery phase. 1-6 pages. 4-18 month time horizon. Sufficient detail that design, eng, quality can build plans. Ritual: team review at kick-off completion of project.
4. Epics - start with a single sentence that an exec can understand what it is. Link to Brief for why. 1-2 paragraphs of explanation. Less than 1Q of work. Ritual: discussed in sprint planning.
5. Stories - start with single sentence that engineer can understand what a customer / user is trying to accomplish. More detail / context if necessary.

Miscellaneous

1. Documentation is an investment – takes real thought, time and energy, reinforcement. Not just a by-product. Pays off in faster decisions, less re-work, fewer meetings.
2. Move incrementally – an incomplete documentation improvement initiative only makes things worse!
3. Diagnostic questions of good vs poor documentation culture:
   1. Are docs relatively recent? E.g. were the majority of docs you see at quick glance updated within last six months?
   2. Do people reference them? E.g. when you ask how or why about a feature, does someone explain it to you or send you a link to a doc?
   3. Is training included in onboarding process? And is it re-upped regularly? E.g. does onboarding include where and how to find info, and practices on how to contribute?
4. Writing guide
5. Don’t bury the lede – bring the most important point out first
6. Grow incrementally – always aim for “a little better”
7. Avoid templates – examples work much better