Intro
Clients frequently ask for help with their documentation. Here are speaking notes for this 45-minute presentation on our philosophy and guidance.
https://docs.google.com/presentation/d/1GLwaJzZwuRHo4uMROagS-r5BpX-Jlgml_tATpdAoASk/edit#slide=id.p
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:
- Culture – signals level of directness, transparency, collaboration, rigor, speed
- Purpose – for how many people, and what is its reason?
- e.g. differences between: assess progress, clarify thoughts, coordinate team efforts, defend in a lawsuit
- Lifespan (“ephemerality”) – how long do you expect this particular document to live?
- Rituals – when and how and why will it be referenced? Who initiates the ritual?
- Less is more – aim for least amount needed, and no less
- Tooling matters (but emphasis is on fit and usage, not which tool)
You know you are doing it well when:
- Docs are relatively recent E.g. were the majority of docs you see at quick glance updated within last six months?
- 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?
- 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?