What is documentation? 📖 ​
It goes down to its purpose: Sharing knowledge with other people (or our future self).
Lifetime – How long will the knowledge be valid? ​
Paraphrasing folks from living documentation here
A certain knowledge will stay true/valid for a certain time. We can roughly split into big categories:
- Constant knowledge (or almost constant), stays valid for a long time.
- Someone’s birth date never changes.
- Someone’s first name will change very rarely during their life.
- The name of a country, very few changes in history.
- Often-changing knowledge
- Someone’s home
- Someone’s tastes or job
- Presidents in countries holding elections every 5 years
- Ever-changing knowledge
- Someone’s age
- Someone’s income
- The location of a function in the codebase
Target audience – Who is this knowledge for ​
If I take the example of the IT world, it can be other developers and/or business people, let's recap the audience (non exhaustive list):
- Developers
- QA
- Product owners/managers
- Customer success/relationship managers.
- Sales (business people)
- Marketing (business people)
- C-level
How to document? ​
We have to adopt various strategies depending the lifetime and target audience.
| Knowledge Lifetime | For Developers | For Business PM, sales, marketing, … |
|---|---|---|
| Constant Forever true | Any manual documentation tool | |
| Often-changing Valid for 10+ iterations | JSDoc Auto-generated docs | Auto-generated docs |
| Ever-changing Less than 10 iterations | Conversations | |
More on auto-generating documentation based on whether we talk about a library or a full product.
The idea is always the same: find the source of truth, generate documentation from it.