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 piss off all the Devs?
There are different approaches to this but it is my humble opinion that documentation should be kept 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:
# APPLICATION NAME Date Created: 8/14/22 Date Last Modified: 8/14/22 Description: Tell me what the application does? Who does it do it for? How do they benefit? What makes it special? Table of Contents: - [Index item 1](#example1) - [index item 2](#example2) ... ## Tech stack - Single page application made in React.js ## Example 1 - Features ## Example 1 - local installation steps - Do thing 1 - Do thing 2 ## Important notes: > This is a note for new hires ## 🔗 Relevant links - [link1](https://example.com) ## Runbook Symptom: "thing happens" Solution: "Do thing"
Confluence Format
Fair game! Make it full of pictures, screenshots, gifs. Make it readable. But most importantly, if it could be in a readme because it applies to code, link it one way or the other.
/rant.
0 Comments