Documentation

Writing high-quality code following strict conventions is great. But it’s also crucial to have technical documentation written down. It keeps track of all technical aspects of the application during the development process. It is also effective for knowledge transfer to other developers or third parties. Successful documentation will make information easily accessible for the squad members and help the new hires learn quickly, saving time, energy, and support costs.

General Best Practices

• Being concise and precise: use short, simple, clear sentences. A long and complex document can easily have important information be glossed over when quickly reading. If you find yourself using awkward or complicated sentences, try paraphrasing or even getting a second opinion.

• Keep the target audience in mind: most readers would not know the application as much as you do, so explaining while keeping the audience’s knowledge level in mind is better than making the reader assume.

• Use consistent format and structure: even though the content of each document is different, prefer to format them by following a similar template and structure. It’s easier for the audience to predict the content structure and find the information they need.

• Don’t underestimate the power of visuals: a picture is worth a thousand words. Whenever possible, visualize what you are saying rather than try to explain it. An infrastructure chart is usually easier to understand than a long paragraph of text.

• Pay attention to the organization: duplicated content, unorganized structures can kill technical documentation. If the information is difficult to find then it eliminates the purpose of knowledge transfer.

• Keep the information up-to-date: there is no point in giving inaccurate or dated information. Documentation acts as a source of truth, so it should always be current.

• Recheck your work: always recheck the documentation once it is completed to avoid mistakes, e.g. using an English syntax checker to check for grammar errors.