OscoA documentation culture is a team habit, not a tool. It exists when writing things down is the normal way work finishes, and not a chore that happens when someone has spare time.
Key takeaways
- Docs fail when they are separate from delivery. Attach them to the work.
- Put documentation in the definition of done.
- Review docs the way you review code.
- Make the reader's question the unit of writing, not the system's structure.
Why documentation decays
Most teams do not lack good intentions. They lack a moment in the workflow where a doc gets written or corrected. The code merges, the ticket closes and the doc, if one exists, drifts away from reality. Six months later nobody trusts it, so nobody updates it, so it gets worse.
The fix is to add that moment to the workflow.
Five habits that stick
1. Add docs to the definition of done
A task that changes behaviour is not done until the relevant doc is updated or a new one is linked. Write this as a line in your acceptance criteria so it is checked, not remembered.
2. Keep docs next to tasks and code
People update what they can see. When a doc is linked from the task that changes it, the author sees it at the right moment. Standalone wikis rely on memory.
3. Review docs like code
A short review catches wrong steps and missing context. It also spreads knowledge, since a reviewer learns the system while reading.
4. Write for questions
Instead of documenting every module, list the questions people actually ask: how do I run this locally, why did we pick this database, what happens when a payment fails. Those pages get read, and read pages get corrected.
5. Make ownership visible
Every doc should have someone who is responsible for keeping it accurate. Without an owner, a doc has no one to notice when it is wrong.
Measure the right thing
Do not count pages. Watch for signals like fewer repeated questions in chat, shorter onboarding time and fewer "where is this documented?" replies. Those tell you the culture is working.
Conclusion
Documentation culture grows when writing is the easiest way to finish a task and the docs are close enough to the work to stay true. Start with the definition of done, and add the other habits as the team gets comfortable.