Stop Being an Answering Machine: The Power of Documentation

Did you ever feel like human version of jukebox? Human answering machine, answerbox? People keep asking you the same questions over and over, and you find yourself repeating the same answers dozens of times, only to hear those famous (and hopefully not final) words: ‘Can you explain it again? Lucky for humanity, solution is simple:

Document everything and answer every question just with the link to the documentation

I already told you that?!

One of my (many) professional rules is simple: if I’m asked the same question more than once, I will make sure that documentation is written. Otherwise, you risk becoming an answerbox.

What to do when someone asks you something that is not documented? The best, or at least most pragmatic, way is to explain it and then ask this person to document it. Not only will the answer be documented, but you will also get feedback on how well you explained it. But it is on you to review and correct the documentation if needed. It usually is.

Tip 1: Document everything and answer every question just with the link to the documentation

And that’s not all, folks! People will soon realize that documentation makes their lives easier, and the idea will spread like wildfire.

“Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.” by Dick Brandon

Why didn’t you read it?

Now you’re proud of your new documentation, but some people will still ask questions that are already answered in it. Take a deep breath, remember that it’s human nature to be a hunter, not a documentation reader, and respond with a link to the documentation and the following words:

Hey, here’s the link to the documentation. Please read it and let me know if something is missing or unclear.

With this approach, you’ll not only answer the question quickly but also double-check if the documentation is clear and up to date.

Tip 2: Answer with link to the documentation

I don’t understand it.

Sometimes, documentation is just badly written. Confusing, unclear, or simply too long to read. Shitty documentation is better than nothing, but it’s your responsibility to keep it short and simple. Otherwise, people won’t understand it. Or worse, they won’t read it at all.

Tip 3: Keep documentation short and simple

Let’s explain it on concrete example, purposely simplified and not very optimal process of releasing software product:

Documentation: Releasing software product

Goal: Release software product with only minor defects

Note: Team Lead is a lead of specific development teams (let’s assume there are multiple teams)

Process:

1. Project Manager notifies Release Managerthat new version of product should be released
2. Release Manager begin release procedure
   1. Release Manager create Teams channel for easier and transparent communication
      1. Add every involved person
      2. Create Release Status message and pin it to the top of the channel
3. Quality Assurance Team Lead will run automatic tests and publish test results
   1. Link to visualization of test results
4. Team Lead will take care that their team immediate fix the bugs and build new Release Candidate
   1. Team Lead notify Quality Assurance Team Leads to rerun the tests and validate results
   2. Team Lead have possibility to mark bug as minor. Such bugs can be tackled afterwards
5. Team Lead give green light to Release Manager
6. Release Manager validate if every bug, except minor is resolved
7. Release Manager inform Project Manager about new release

Clear and understandable, right? Note how responsible persons are highlighted to make responsibility boundaries clear. Additionally, more detailed information is intentionally left out to maintain simplicity. Detailed information should always be linked to another part of the documentation.

Tip 4: Keep details in another part of the documentation

But there’s always a but—make sure your documentation is always up to date. Otherwise, you could sail into a major shitstorm where discrepancies between documentation and reality become the standard.

“Incorrect documentation is often worse than no documentation.” by Bertrand Meyer

Luckily, where there’s risk, there’s also opportunity. Well-documented processes are easier to understand and, therefore, much easier to update or change.

Changing existing processes is a pain in the ass. Unless they are well-documented. The best approach is to open the documentation during discussions and review which parts need to be updated.

New Process:

1. Project Manager notifies Release Managerthat new version of product should be released
2. Release Manager begin release procedure
   1. Release Manager create Teams channel for easier and transparent communication
      1. Add every involved person
      2. Create Release Status message and pin it to the top of the channel
      3. Note: Tests are run automatically after deploy of release and published in
3. Team Lead follows automatically reported bugs
   1. Link to visualization of test results
4. Team Lead will take care that their team immediate fix the bugs and build new Release Candidate
   1. Team Lead have possibility to mark bug as minor. Such bugs can be tackled afterwards
5. Team Lead give green light to Release Manager
6. Release Manager validate if every bug, except minor is resolved
7. Release Manager inform Project Manager about new release

Tip 5: Keep documentation up to date

Tip 6: Treat process changes as documentation changes

Are there other benefits?

Not only will you save time, but you’ll also build, brick by brick, a well-documented and efficient organization that will undoubtedly boost productivity. Processes will be clearer to everyone, human errors will decrease, responsibility boundaries will be more defined, and onboarding will become easier.

Long story short, build documentation and life will be a little more beautiful.

Summary

Tip 1: Document everything

Tip 2: Answer with link to the documentation and encourage to improve it

Tip 3: If documentation is not simple and short people will not understand it.

Tip 4: Keep details in separated part of documentation

Tip 5: Keep documentation up to date

Tip 6: Treat process changes as documentation changes