Software engineering is a craft. It depends on many more dimensions than just writing code. And as a craft, you need to practice every dimension to get better at it. One fundamental part of software engineering is knowledge sharing. Everyone is new to a concept at one point in time. If you want to learn about something new, it is best to have structured information about the thing you want to learn. Hence it is important to have a good documentation. It can be documentation about a framework, about a tool the team is using or about the processes which happen in your organization.
Written documentation scales very well. You write it once and hundreds of people can read it. Especially people who are new to a team or topic can learn on their own pace. They can come back to the documentation if needed and can even improve it with their fresh perspective. Additionally, most software systems and all their moving parts do not fit into the mind of just one person. The cognitive load is too high. As a result, you will benefit from your own documentation as well. You can reduce your cognitive load.
Document for Humans
Therefore, we document for humans. Carolyn Stransky has a great talk on this topic. She starts by asking about the target group of the documentation. Since we want to write documentation for humans, it is quite helpful to narrow down the range of potential users of our documentation.
After having decided on a target audience, we should focus on the use cases we want to support with our written documentation. For example, when looking at a new framework, you want to read about the different use cases you can use this framework for, and not about how the internal code is formatted – you simply don’t care. You want the focus on the important parts for this specific user group, not on something else.
The two main points Carolyn makes in her talk are:
-
Be specific about the target group
-
Be specific about the boundaries / focus
She summarizes with the statement: People don´t mind reading docs, as long as they are helpful! So, make your documentation helpful!
Tips for a helpful documentation
Talk about the why
Good documentation complements the how with the why. It is important to describe the how. What can be done which way? But it is also important to explain the why. Why was this decision favored and not the other one? It helps understanding the background and history of the current state of the system and its documentation.
Simple and short sentences are better than complex ones
Short sentences are faster to read and easier to understand. Especially if the documentation you´re reading is written in a foreign language. Thus, use short sentences and skip those half sentences.
Do not use problematic terms
Using terms like master/slave is problematic. Even still used widely, there are better alternatives like primary/secondary. These terms carry less problematic meaning and there are even easier to understand for people who are new to this topic. There are several more examples of problematic language, try to find better terms for the things you want to say.
Do not say it is easy
Sometimes documentation starts with saying something is easy or obvious. Do not do this. It might be easy for you, but more junior colleagues might think the opposite. Instead, try to be specific and absolute. For example, say this task takes around five minutes. This is more helpful than saying it is easy and fast. Remember the target group of your documentation? The specific time stated before should take them into consideration.
Address common problems
You can help the reader by listing common problems. Maybe there are known problems with certain combinations. Or there is one thing everybody misses in the beginning. Document that! It really helps people to move forward with your documentation. Otherwise, they might get stuck and lose interest early on.
Code snippets shouldn´t be images
Code snippets are helpful to clarify a point you are making in your documentation. Keep in mind that some people want to copy the snippet directly into their editor. Do not let them type the whole thing because you provided an image instead of the actual code. It also really helps people who are visually impaired.
Use meaningful variables
Talking about code: you often use certain variable names in these snippets. Please be more creative than foo/bar. These variable names carry no meaning and are therefore not very helpful. Try to think of a variable name that has a meaning in the context of your code snippet.
Meaningful structure
The structure of your documentation is essential. Users want to find the relevant information for their problem quite fast. Documentation that follows an intuitive structure helps them find the content they are looking for.
Depending on the context of the documentation several standards might exist. Architectural documentation for example might follow the arc42 guidelines. These best practices can help you structuring your documentation. But keep the human being in mind. Adapt the structure of a template to fit your needs and the target audience. It really does not help to have an arc42 templated documentation when every second page is empty.
Content must be searchable and findable. Depending on your tooling and the form of documentation, think about how the user could find the information when skipping the navigation entirely. Maybe you can label the content to help the search engine finding it?
In general, it is good practice to document information once and offer several ways to access it. One way might be the navigation and structure of the documentation. Another way the search option and a third one a tag cloud of the most used labels.
Mentioning the tag cloud and labeling: it is best to stick to the common terms for the concepts you are describing. There is no need to invent new words for already established concepts. Try to agree on a certain set of labels you want to use in your team or project. It helps keeping everyone on the same page.
Encourage
Actively encourage to participate in the documentation creation and editing process. Taking all the beforementioned aspects into consideration, one can write a good documentation, but a whole team can create an awesome documentation!
An easy and fast to use tooling is vital in achieving the goal of awesome documentation. Invite everybody to join you editing the documentation and give short introductions in how to use the tool. The goal here should be enabling others to self-organize and improve the documentation on their own.
Edits should be visible to others, for example in a change feed on the first pages of the documentation. This also helps the primary maintainers of the documentation to stay up to date. It can be quite beneficial to have a core group of maintainers. They can skim through the recent edits and adjust minor faux pas like the usage of a wrong label or the wrong structure of a certain page in the documentation.
This group of core maintainers should not work upfront and make strict rules about everything. This would harm the creativity and interest of the other editors. Instead, let people change first and then watch what happens. Guide them where necessary but always gently, not harsh. Think of it as a gardener who fosters the growth of plants (and check out Maggie Appleton´s thoughts about knowledge gardening). The result will be a great and eventual consistent documentation. Meaning that changes will become consistent and helpful over time. There simply cannot be any point in time where everything is perfect. But you can strive for it.
That being said: delete old stuff. No one wants to read several pages of documentation to find out that there are not relevant anymore. It also helps people to navigate, since there is less fluff, they must sail around.
And finally: talk about it! People only feel invited and encouraged if you mention the efforts for a great documentation. Highlight good examples and learn from the bad ones.
Community Management
Citing Carolyn once more: the overall goal is to be honest, helpful and human when creating documentation. Think about the target audience and the use cases you want to describe.
Take care about documentation, the process and the people reading it. Be a community manager through documentation.
