The phrase, “Can you give me some documentation on that?” is a common refrain among colleagues seeking information about projects, deployments, or various detailed matters. Unfortunately, it’s also common to encounter documentation that’s either outdated, deprecated, or scattered across unwieldy documents, making it less than helpful to the reader. In some cases, valuable information is hidden amidst a sea of data.
The purpose of this post is to offer insights into creating documentation that genuinely aids others and is easy to comprehend. Our focus will be on technical documentation aimed at development teams, sharing ideas on how to make it accessible and valuable.
Let me start with some common questions that probably need to be answered before beginning to generate any kind of documentation:
What is the purpose of the documentation?
– Any kind of document needs an objective. Before doing something, it is necessary to understand what is wanted to explain.
Who needs to read it?
– There are several actors in a company. Technical documentation for a teammate may be different from a functional explanation or an end-user documentation.
Is it technical documentation?
– The structure, the content, the size and many other characteristics can vary depending on this.
Is it possible to use specific terms?
– It is common for areas, projects or teams to use several words that have a special meaning. The meaning is not necessarily known for all people in the company or for new members. As these kinds of words can be a communication barrier, they should be considered.
What update rate will be needed to maintain it?
– If a document needs to be manually updated with a high frequency, it is likely that it will be abandoned or remain outdated in the future.
There are a lot of other questions that we can ask ourselves at this point, but these can affect the scope and the way of writing it. From now on, all examples will be based on technical documentation for developers.
Imagine that you have already asked yourself about these points, and you want to start to write. No matter the kind of document an important part that sometimes seems to be underestimated is the objective section. When a reader opens a file, the first thing that needs to be really clear is what will be explained in the document and its scope.
Suggestions for any kind of document writing
Assume that:
- the reader does not have any previous knowledge about the topic to explain.
- the terms always need to be explained.
- the reader has an objective linked to reading your document. Your document will be useful only if it can fulfill that objective.
Try to:
- always include a table of contents to provide direct access to independent zones of your document and show the list of all the topics to treat too.
- write short sections and paragraphs. Big groups of text can be uncomfortable to follow.
- include tables, graphics and any kind of helper to facilitate the reading.
- use different font sizes and colors to emphasize and highlight important parts of your document.
- redirect to other documents only if those documents treat an independent topic or if they have a different scope of the current explanation.
Suggestions based on the purpose of the document to generate
Document purpose: Explain a software design
- Start with a general introduction of the software. It is common to see a lot of UML diagrams in these kinds of documents, but they do not replace a functional explanation.
- Using links can be helpful but they can distract the readers, too. It is preferable to control where y when relate documentation with external files.
- UML diagrams are a good way to communicate design decisions but, in big systems, they can produce a rejection feeling from a reader. Try to start with general and high level diagrams. If a particular part of the design includes a big UML diagram, try to split it based on the ideas to show.
- Try to maintain the same detail level in all the documents or at least, to include the minimal required level of detail to explain a topic. If there is a topic with a lot of detail and others with insufficient explanations, it will affect the quality of your document.
- Be careful with the details of UML diagrams. Low-level diagrams are good for developing features, but the update rate of these diagrams can be high for new software.
- Diagrams do not replace explanations, notes and references. Specific terms either. The most important thing about a document is that it can be helpful to others. If a document has hundreds of diagrams with no readable size and hundreds of pages with explanations and many specific terms without any clue of their meaning… that document probably will be ignored by the readers.
Document purpose: local environment installation
Try to include:
- A brief recap of what the software does.
- The repositories’ locations and if they have any special rule or configuration.
- Local configurations (all of them).
- A detailed step-by-step of how to install/run the software.
Document purpose: release/deployment of components
Try to include:
- A brief recap of what the software does.
- The repositories locations and if they have any special rule or configuration.
- A detailed step-by-step of how to do the task.
- All special considerations to take into account based on previous problems.
Now, someone can argue that we can put all these points in the same document. That is true, but depending on the size of each section, that document will increase in size, and it will probably be challenging to navigate in it. They were examples from some basic kinds of documents.
There are a lot of papers, tutorials, checklists, readme files, etc., that can be created and spread as technical documentation between the members of a team. No matter the format, the important thing to understand is that these files need to be useful for others. If you write documentation and you need help understanding it one or two weeks later, a user who never saw it before probably will never be able to use it in a performing way. So, be clear and concise when the situation allows you to do that and detailed when you know the topic requires it.
