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.

Organize to make it easy to document things that matter

It should be obvious where to go to find stuff.

I'm used to using confluence, so we just point people there. Structurally I've found success by assembling representatives of the team to determine a structure. Those same people were then tasked to move obsolete pages into an archive bucket. They were merciless. I had to fish things out of archive sometimes, but generally no information was better than old anti-information.

Time bound buckets like "Investigations Q3 2020" work well. Time has a weird way of deciding which things belong together.

A 'getting started' page for the team is essential. Though it's pitched at new developers as a tour de wiki, existing developers will appreciate a description of what you intend to go where.

Document by example

Someone has to go first, and if you're still reading, it will probably be you. Just do it, so that you can set an example for the rest of the team to emulate. Specifically:

• Be concise.
• Use diagrams.
• Use tables and bullet points.

We're developers, not novelists. Long wordy explanations are hard to maintain. Avoid.

Be selective around what you document

• Document things you would tell a person joining the team.
• Documentation that require a lot of detail and are likely to change should be automated. OpenAPI 3.0, for example, can be used to generate markdown or HTML, with the right tooling.

Get a mermaid to help you draw

Pictures are worth 1000 words. 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.