How to write documentation like your life depended on it

Part of saying goodbye to a bunch of great people is learning to let go, and preparing those who come after you as best as you can.

Let's go back 8 years, when I first made the fun decision to ask for more responsibility. The next day, a hard drive arrived on my desk. Source code and installers from a team that was recently let go. Oh, and by the way, we have a critical issue that a customer has in their production deployment that needs fixing yesterday.

What do you think happened?

Hero time. Late nights. Swearing. Lots and lots of swearing.

How did we get to this place? Those devs were nice people, and certainly didn't seem lazy. Some of them even took the time to write solid unit tests. Now granted, they didn't owe anyone anything after being let go, but why didn't they do a better job along the way?

We get busy. People get shouty. We cut corners. We can't feel the future value right now, so it often gets neglected.

How do we do better? We must build an environment where documentation is present, used, and easy to contribute to. We want documentation that belongs to the team, not to the the poor guy who had to write it.

Don't document processes. Automate them.

Need dependencies on your build machine? Just write a script. There really isn't an excuse anymore. Windows has had chocolatey for years, and it works well. Linux... well.. they've been showing us how since ages ago That said:

• Comments are your friends. Remember to comment why that dependency is installed, and what version you installed at the time - I've come to appreciate scripts that install the latest and greatest by default, but sometimes that doesn't always work so it's always good to know what version works.

• Make sure your script is idempotent, because eventually someone is going to update it and you will want to rerun it, without it taking ages.

• Ensure your process automation lives alongside in repositories like code. It's very nice to be able to click on menus and drag and drop things, but I find those approaches don't really scale.

But it's 2020. You already know this.

Organize to make it easy to document things that matter

It should be obvious where to find stuff, and where to add new content.

I'm used to using confluence. In the teams I've been in, I've found success by getting together a group of people in the team that represented the various functions (eg senior devs, QA, product owners, scrum masters). We determined a structure that worked for us, then I got those people to move things that were out of date into an archive bucket. They were merciless. I had to fish things out of archive sometimes, but in all cases, no information was better than old anti-information.

One thing that also worked quite well was to put content into time-bound buckets (ie Investigations Q3 2020). Time has a weird way of deciding the things that belong together.

The other thing that worked quite well was a getting started page, pitched at new developers to tour them through the wiki. We didn't have any new developers join, but some of the existing developers found it a useful guide as to where to put things.

Document by example

Someone has to go first, and if you're still reading, it will probably be you. Set some time aside, and set the level of documentation you feel is necessary by writing the first example for the next developer to emulate.

Be concise. Use diagrams. Use tables and bullet points. We're developers, not novelists. Long wordy explanations are hard to maintain. Avoid.

Your code is self documenting, right? Probably, but it's still a lot to take in all at once. Decide what you would have to tell someone just starting, and write it down so that you don't have to.

Get a mermaid to help you draw

Pictures are worth 1000 words. Flow charts are nice, but sequence diagrams really help you coordinate a team when you have parallelised work. It gives people a high level view of how the pieces fit together at a glance.

Allow me to introduce you to my secret weapon in the art of communication.

Mermaid.js. Create diagrams like you would write code.

Back in the day, we had to use powerpoint or word (or visio if you were flash) to draw lines between boxes and then somehow fit the text inside the squares... you guys get the drift. With Mermaid, you describe the relationships, and it does the arranging for you.

It's not perfect. But in most cases, it gets the point across. It's even useful as a remote whiteboard -- you can do this stuff in real time.

Use the live editor to put your diagram together. Then embed it into..

Confluence: Mermaid Plugin for Confluence -- free!

Markdown (using VS Code to preview): Markdown Preview Mermaid Support

Github. Bitbucket. If you're listening -- please render mermaid markdown!!

Which leads me to my final wish.

I wish I could keep the documentation with the source code.

I've got beef with confluence. I want to make writing documentation just like writing code, mainly so it's easier for developers to contribute as part of their definition-of-done.

My theory is that putting the documentation with the source code means that the documentation and the code can be updated via the same pull request mechanisms developers are used to. This in turn means hopefully means it stays up-to-date.

But it's too much effort doing it this way.

1. Everything is manual. Linking to pages in to provide cohesion in documentation is a pain.
2. Search doesn't exist.
3. The authoring experience sucks. I hate doing tables in markdown. ASCII art is not an efficient use of my time.

I noticed gitdocs the other day. Wonder if it's any good?

And so the cycle repeats itself...

It's now 8 years later, and now I'm the one handing over the hard drive. I have a lot of documentation to do still, because onboarding isn't the same thing as handover. The guys following me are going to have a hard enough time as it is, and I don't want that to be my story to be theirs.

Looking back, I wish I had done some of this stuff earlier, but I'm glad I set up what I did when I did. I'm just so glad I had the automation set up. That one thing is going to make it so much easier to move on.