Evaggelos Balaskas - System Engineer

[Original Published at Linkedin on October 28, 2018]

The curse of knowledge is a cognitive bias that occurs when an individual, communicating with other individuals, unknowingly assumes that the others have the background to understand.

Let’s talk about documentation

This is the one big elephant in every team’s room.

TLDR; Increment: Documentation

Documentation empowers users and technical teams to function more effectively, and can promote approachability, accessibility, efficiency, innovation, and more stable development.

Bad technical guides can cause frustration, confusion, and distrust in your software, support channels, and even your brand—and they can hinder progress and productivity internally

so to avoid situations like these:

xkcd - wisdom_of_the_ancients

or/and

Optipess - TitsMcGee4782

documentation must exist!

Myths

• Self-documenting code
• No time to write documentation
• There are code examples, what else you need?
• There is a wiki page (or 300.000 pages).
• I’m not a professional writer
• No one reads the manual

Problems

• Maintaining the documentation (up2date)
• Incomplete or Confusing documentation
• Documentation is platform/version oriented
• Engineers who may not be fluent in English (or dont speak your language)
• Too long
• Too short
• Documentation structure

Types of documentation

• Technical Manual (system)
• Tutorial (mini tutorials)
• HowTo (mini howto)
• Library/API documentation (reference)
• Customer Documentation (end user)
• Operations manual
• User manual (support)
• Team documentation
• Project/Software documentation
• Notes
• FAQ

Why Documentation Is Important

Communication is a key to success. Documentation is part of the communication process. We either try to communicate or collaborate with our customers or even within our own team. We use our documentation to inform customers of new feautures and how to use them, to train our internal team (colleagues), collaborate with them, reach-out, help-out, connect, communicate our work with others.

When writing code, documentation should be the “One-Truth” instead of the code repository. I love working with projects that they will not deploy a new feature before updating the documentation first. For example I read the ‘Release Notes for Red Hat’ and the ChangeLog instead of reading myriads of code repositories.

Know Your Audience

Try to answer these questions:

• Who is reading this documentation ?
• Is it for internal or external users/customers ?
• Do they have a dev background ?
• Arey they non-technical people ?

Use personas to create diferrent material. Try to remember this one gold rule:

Audidence should get value from documentation (learning or something).

Guidelines

Here are some guidelines:

• Tell a story
• Use a narative voice
• Try to solve a problem
• Simplify - KISS philosophy
• Focus on approachability and usability

Even on a technical document try to:

• Write documentation agnostic - Independent Platform
• Reproducibility
• Not writing in acronyms and technical jargon (explain)
• Step Approach
• Towards goal achievement
• Routines

UX

A picture is worth a thousand words

so remember to:

• visual representation of the information architecture
• use code examples
• screencasts
• CLI –help output
• usage
• clear error messages

Customers and Users do want to write nothing.
Reducing user input, your project will be more fault tolerant.

Instead of providing a procedure for a deploy pipeline, give them a deploy bot, a next-next-install Gui/Web User-Interface and focus your documentation around that.

Content

So what to include in the documentation.

• How technical should be or not ?
• Use cases ?
• General-Purpose ?
• Article size (small pages are more manageable set to maintain).
• Minimum Viable Content Vs Too much detail
• Help them to understand

imagine your documentation as microservices instead of a huge monolith project.

Usally a well defined structure, looks like this:

• Table of Contents (toc)
• Introduction
• Short Description
• Sections / Modules / Chapters
• Conclusion / Summary
• Glossary
• Index
• References

Tools

I prefer wiki pages instead of a word-document, because of the below features:

• Version
• History
• Portability
• Convertibility
• Accountability

btw if you are using Confluence, there is a Markdown plugin.

Measurements & Feedback

To understand if your documentation is good or not, you need feedback. But first there is an evaluation process of Review. It is the same thing as writing code, you cant review your own code! The first feedback should come within your team.

Use analytics to measure if people reads your documentation, from ‘Hits per page’ to more advance analytics as Matomo (formerly Piwik). Profiling helps you understand your audience. What they like in documentation?

Customer satisfaction (CSat) are important in documentation metrics.

• Was this page helpful? Yes/No
• Allowing customers to submit comments.
• Upvote/Downvote / Like
• or even let them to contribute in your documentation

make it easy for people to share their feedbak and find a way to include their comments in it.

FAQ

Frequently Asked Questions should answering questions in the style of:

• What would customers ask ?
• What if
• How to

FAQ or QA should be really straight forward, short and simple as it can be. You are writing a FAQ because you are here to help customers to learn how to use this specific feature not the entire software. Use links for more detail info, that direct them to your main documentation.

Conclusion

Sharing knowledge & shaping the culture of your team/end users. Your documentation should reflect your customers needs. Everything you do in your business is to satisfy your customers. Documentation is one way to communicate this.

So here are some final points on documentation:

• User Oriented
• Readability
• Comprehensive
• Keep it up to date