Building Team Documentation Habits

The book contains the ideas I've seen work to build a whole team's documentation habit.

There's no magic bullet here: you'll need to do some work. I'm not here to BS you, but to give you a plan that works.

It also contains an overview of the kinds of documentation tools that exist on the market, and their relative strengths and weaknesses. Some of you don't need that; some of you don't know what tools to pick.

Excerpt

I'm a very pragmatic person. This is reflected in the book.

Here's an example of the kinds of advice and ideas in the book:

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.

Interested? Submit your email address and get the pdf in the nice form below: