Thoughts on documentation

Here are captured thoughts on business documentation that I want to talk about.

The theme of this collection is thoughts that are philosophical, guiding, and strategic.

I didn’t include principles, methods, tricks and other practicalities. I will write those in separate posts.

What is documentation?

Business documentation is critical for the long term and daily success of the company. In the list of priorities, it sits besides getting actual customers to pay us money.

The company is a programmable system. It is the encoding of the solution to a common problem.

People are more like an inconsistent, chaotic, dream image association making machines. Our personal goals will evolve, our job titles will change. And even if our job stays the same, our memory is unstable.

We use documentation to guide our work when we are in known territory. When we encounter the unknown, our creative exploratory behaviour engages. When we solve a novel problem, we have to “save it to disk” in the company. The company is the documentation. The company is the documentation.

People operate and update the company strategy and its procedures. The people live around and in the documentation, changing it, improving it, adapting it.

This belief is clear to me. I feel a sense of urgency, a group survival instinct, driving me to document what I learn.

Leverage and documentation

Documentation is a pre-requirement for improvement, delegation, automation and training. There is simply no leverage without documentation.

Not only is there no leverage without documentation, but even mere repetition cannot be achieved reliably without documentation.

The cost of neglecting documentation

Don’t skip documentation.

Pros: you reach a short-term goal slightly faster.
Cons: you set someone up for failure at worst, double work at best.

To skip documentation is to have no value as far as team work is concerned.

The operational hierarchy

              /\
             /  \
          Automation
           /______\
          /        \
   Monkeys with documentation
        /____________\
       /              \
      /  Hero monkeys  \
     /__________________\
    /                    \
    Monkeys typing randomly
  /________________________\

Habits and methods before software

Documentation methods and habits in people are more important than the documentation software and its features.

Someone who wants to document will find a way despite sub-optimal systems.

Someone who doesn’t want to document will find a way not to do it despite a superb documentation system integrated to their main work tool.

Make sure documentation skills and habits are a hard requirement for hiring in your team.

Always be replaceable

If you are not replaceable, you are not promoteable.

Always be replaceable.

You do this by being awesome at documentation.

Documentation is how we make ourselves replaceable.

The paradox of teaching

When you set yourself to always help others doing better at their work, you increase the team’s total ability to create value.

An insecure fool thinks this is a losing strategy that will make him less powerful while the rest of the group becomes stronger.

What actually happens is you become more valued, because you have a leverage effect. Your boss likes this more than another talented employee who has no influence on their surroundings.

By teaching frequently, you learn constantly and integrate what you learned. It also guarantees that you are keeping up and have a constant edge.

In my experience, it’s been a great career strategy.

Solution cartography

Writing is the structure and process that persists our thoughts as we move on to think about something else.

Documentation is mapping the way out of a recurring problem.

Problems we solve are almost guaranteed to be recurring problems.

Work output

No task is considered done until documentation was written or updated.

If you didn’t write it, did you even work? It doesn’t matter that you had a thought if you didn’t write it.

Quarterly review

During team quarter review meetings, everybody should tell one customer story. There are three parts:

1. Tell a few words on who the customer was, what was the project about, and what made it challenging.
2. What did you learn as an individual or professional? Did you acquire a new skill? Did you learn to understand something new? Is there a new kind of situation or client category that you learned how to handle?
3. As a team, what can we do now that we didn’t know how to do before dealing with this challenge? What is the reusable value from it? Show us the new playbook/procedure/article in the documentation.

Writing is a skill

There are tricks and methods and principles to help find the balance of detail level, relevance and speed.

It can be learned. To write is to think. I can do this.

In future posts, I will write about what to document and how to do it well. In the meantime, I recommend this fundamental book on business documentation: Work the System by Sam Carpenter. Listen to the interview with the author by Bret McKay.

Feature image credits

Jean Le Tavernier, Public domain, via Wikimedia Commons.