Documentation Culture (WIP)
- Drew Karriker (Unlicensed)
- Mikah Pinegar
Incorrect documentation is often worse than no documentation.
-- Bertrand Meyer
Documentation should be folded into everything we do like a leatherman.
It should make onboarding as easy as “read our confluence”.
How do we document in a meaningful way that doesn’t kill productivity or frustrate all of the Devs?
There are different approaches to this but it is my humble opinion that documentation should be kept as close to the code base as possible in readme's where generalized, design documentation and educational content should be used at the confluence level. Confluence should then be linked to more up-to-date documentation at the Readme.md level.
I think confluence needs more education materials and links to code.
Confluence is not a great tool for searchability!
A simple cultural shift is to add documentation as a part of our code review process as well as add bullets on our tasks to include updating documentation. It won’t happen overnight but we can make an honest effort to do better moving forwards.
TL;DR:
On new stories, put acceptance criteria to update readme or confluence as applicable.
Don’t approve PR’s (unless urgent) that haven’t updated the readme (at least the “Last modified date”).
Document as if we are an enterprise and need new hires up to speed quickly.
FAQs
Example Readme format
Confluence guidelines
/rant.