Building Team Documentation Habits

You are willing to work on your team's documentation problems, you just need a realistic plan. Here's a free one I built from years of landing real documentation on real teams and seeing what works.

I don't have magic bullets here, so here it is up-front if you want to see a change, you'll need to do some work. You'll quickly see that a plan that gets you delivering your goal involves putting in effort.

Get it here:

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.