You are not documenting enough

Documentation is highly valuable since it allows your teammates to find information without interrupting each other. Unfortunately:

  • no one like writing docs
  • when a doc is written, no one refers to it.

Just a little disclaimer: I'm not talking about contractual documentation that you'll write even if this is the last thing you want to do in your life. I'm talking about documentation that should be useful for you and your team. It can be:

  • architecture decisions,
  • how to troubleshoot your app / runbook,
  • internal processes,
  • onboarding documentation (how to install the development environment, how to access the ticket management system, …),
  • server list,
  • typical answers to support questions.
  • Minutes of meeting

How to make people write documentation?

The first roadblock is the documentation system. 15 years ago, I worked on projects where documentation was made of MS Words documents stored on a shared mount point or some sort of Web1.0 like websites. Creating a new version of a document was a huge pain. Managers had to enforce the writing of documentation. Documentation became out of date quickly. Researching information was impossible.

Then we shyly adopted a wiki system. It lowered the friction of writing docs but the wiki syntax or the wysiwyg user interface were far from Word I guess. Then again, the action of documenting had to be enforced.

I work for a client nowadays that has its internal documentation in form of a mkdocs static site. The result is nice, but it demands to:

  • have git,
  • pull the docs,
  • write your doc,
  • update the document structure,
  • attempt to please the linter run in the commit hook,
  • push the repo,
  • wish that the build pipeline will be kind enough to publish your addition.

Who would like to write docs in such a system?

So, the first thing you can do is find a documentation management system with zero friction. What you want is to open a web page, write in it, and share its URL. You have a lot of such systems on the market now, from Google Docs to Notion. I prefer Notion since it's very flexible and you can access every page easily, and I don't know why non-techies would not love it. But personally, I'm fine with any kind of wiki system (am I a nerd?).

Once you have adopted the best documentation system, you should encourage people to write. When starting a meeting, find a volunteer to write the minute. When solving any issue, encourage people to write a postmortem. When testing different ways for your technical architecture, write an architecture decision record.

You can also put in place some sort of code of conduct to reassure people. Make them comfortable to write:

  • it's okay to make typos,
  • it's okay to correct others' typos (directly, without revision marks)
  • provide basic writing guidelines (give advice like: using short sentences or using active voice, for example see this article)

How to make people use documentation?

Nowadays, communication tools are closer to instant messaging and encourage asking questions and answering rather than browsing the documentation. People don't want to take the time to read your nice prose.

When a question is asked twice, it can be answered in some kind of documentation. Then the documentation should be linked in your Slack / Teams / Discord. It will encourage people to browse the docs, even beyond their first need.

When you have written a document that provides information for stakeholders to make a decision, emailing it is not enough. You have to present it: schedule a quick meeting where you'll show your doc and provide a summary and your conclusions.

The last challenge I discussed lately is sharing collective technology watch and best practices. Software development is a field that implies a lot of research, and people often want to stay at the edge of the field. Having a solid documentation culture will help them to share their findings within your company: encourage it and make people present what they learned, even if there is not much to say at first.

But text is for old people, we have videos now

In the (short) video era, sharing videos and screencasts is a very effective way to convey information. By the way, text form still have its benefits for long-term documentation:

  • it needs less storage space and can be effectively losslessly compressed,
  • it is easily searchable
  • you can scan it to quickly extract the information you want. An ability where humans remain stronger than an AI.

Posted on 2023-07-31 at 06:37

Tags: at work, documentation

Previous Back Next