Building Team Documentation Habits

This is a free, short e-book I wrote because you are willing to work on your team's problems, you just need a realistic plan.

There's no magic bullet here: you'll need to do work. I want you to have a plan that gets you delivering your goal, and that plan involves effort.

The book also contains an overview of the kinds of documentation tools that exist on the market, and their relative strengths and weaknesses.

This e-book is free, delivered to your inbox:

Excerpt

The Docs Need To Be Where People Will Look

I had a colleague who called me into a meeting.

He said he had called a meeting because he wanted to look at metrics, but didn't know how I had set up grafana or how to get access.

"I wrote it down. It's all documented."

"Where?!? If nobody can find them, they're not useful."

"Have you looked?"

It's surprising how often people will ask you a question before they look to see if they can find an answer themselves. You have to be okay with guiding them.

I remember he started with our github organization's search, and he found the docs.

He did something next that you'll see on your own team. He tried to cover up being a little embarrassed by trying to catch me out. He said, "Github isn't where we should store docs, what if I'd started on the wiki?"

He searched the wiki and found a page I'd written there that contained a link back to the docs on github. I put backlinks in every documentation system I could think of, so the docs were discoverable anywhere people might think to look.

Docs need to be discoverable everywhere, to keep the barrier to entry as low as possible.

It's not an enormous burden but it's annoying and at times it's tiring. You can normally script the process of adding links into several systems, which makes it easier.

Once your team has a habit of knowing where docs are, you can start only putting them in the right place, but that isn't the right way to start.