Incorrect documentation is often worse than no documentation.
-- Bertrand Meyer
This may come off as scathing or rude. Not my intention. Read this confluence page with “Drew has the best intentions”, please.
Ok, so we like documentation right? Nah, most people don’t.
Documentation should be folded into everything we do like a leatherman. It should make onboarding as easy as “read our confluence”. Unfortunately, the confluence is rarely maintained or looked at from a macro perspective. Even if confluence documentation is maintained, it’s unsearchable.
The aim is to make it as painless as possible to create/update/maintain documentation for our applications. So how do we get there?
One simple approach would just be to update confluence, right? Right?!
This is great but there are no approvals/reviews. You can make documentation, like this page for example, that may go unread or updated ever.
That’s cool if you want documentation just for the sake of documentation. I don’t. I want meaningful explanations of the code/application I am working with and something that I can leverage in a pinch.
I don’t want to be called for every issue that comes up, just saying. I do however want to make documentation that is verbose enough to help my team so they can self-serve when I am AFK
It is, therefore my aim to make documentation a part of our culture.
Let’s assume that Confluence is a great tool (it’s not), and let’s assume we have no good documentation in README.md (we don’t currently). 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.
Now, I hear you are grumbling and saying “well our readme.mds aren’t up to date but confluence is”. I’d argue that it’s not the case as of today. I think confluence needs more education materials and links to code. I haven’t seen an onboard doc - that may be due to permissions or some space that is not obvious to me. Confluence is not a great tool for searchability! We are a growing organization so this is totally understandable. Not meant as a critique to anyone.
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.
Add Comment