The Engineer’s complete guide to writing excellent internal documentation

One of the main benefits is that you avoid data and information silos. For example, only one engineer knows the full details of a specific engineering process. What should you do when this engineer is not available? Having these engineering processes documented solves this problem. 

On top of that, internal documentation improves the onboarding time for new employees because they can learn about all relevant processes by reading the documentation. 

This article covers:

• Why should you invest in internal documentation?
• Best practices when writing internal documentation
• How to get started with internal documentation?

What is internal documentation?

First, let’s define internal documentation. It describes all processes within your organization. In other words, you write documentation for internal users instead of external users like a guide or tutorial.

Internal documentation encompasses documenting the code review process, project information, or engineering team meeting process. In theory, you can document any process.

Why should you invest in internal documentation?

It’s not always clear why companies should invest in internal documentation until a crisis happens (and they realize they lack the knowledge to solve the problem in a timely manner). This crisis situation brings us to one of the most important reasons: efficiency.

Efficiency

Internal documentation provides clear process descriptions, which are extremely useful to solve crises. Imagine a situation where your company’s product crashes, and the person who knows the procedure to restore production services is out of office. Obviously, it’s important to restore those services as quickly as possible. However, without the help of this person, it’s almost impossible to accomplish this task. 

In this case, a clear process description solves the problem and gives every DevOps engineer the correct information to restore production services. 

As a side effect, process documentation makes a job less stressful because you can eliminate guesswork.

Improved onboarding speed

When a company hires a new engineer, you want that engineer to become productive as soon as possible. Having all processes documented makes the life of a new engineer and the onboarding mentor a lot easier because they don’t have to spend precious resources explaining undocumented processes. 

A report by the Human Capital Institute mentions that 20% of employee turnover happens within 45 days. In other words, a positive first impression matters. How would you feel when you join a company lacking processes and structure? The quality of your onboarding documentation directly impacts the productivity and happiness of your employees.

Knowledge sharing

It doesn’t make sense for every engineer on the team to know every area of the codebase at all times. However, you should be able to tap into that specialised knowledge whenever you want. 

That’s where documentation comes in, it allows you to tap into specialised knowledge without taking up other people’s time.

Best practices when writing internal documentation

Here are a couple of pointers to help you write internal documentation.

Make it insanely easy for anyone to do

I’m not joking. The biggest challenge when it comes to writing internal documentation is to actually do it.

The best way to do this is to bring the process into your existing workflow, for engineers and code documentation, this means your IDE.

Code documentation tools like Stepsize allow you document your code with “issues”, directly from your editor. This means that you can create documentation on the fly while you code. It also allows you to link several pieces of code to one issue, which means you won’t have to copy/paste code snippets.

Be precise and detailed

It’s essential to document all steps involved in processes to avoid incomplete documentation. Don’t be afraid to include details. 

For engineering documentation, you can even document the format and style of code comments or how to document features for other developers. Providing a defined format improves quality and eliminates guesswork. Without a defined format, developers might miss crucial details.

It’s also important to describe the different roles and responsibilities, so engineers know who to reach out to in case of problems or questions.

Lightweight and visual

Developers don’t like reading tedious documentation. Why would you create hard-to-read documentation yourself? Make it fun and lightweight to consume internal documentation. 

Two useful tips:

• Include images: Images make it easier to explain processes than text. 
• Split large process documents into smaller processes (or even subprocesses).

Tagging and search

Tagging documents allows users to find the correct information quickly. Again, invest time finding a tool that provides you with searching capabilities. Stepsize allows you to search and find issues across your team or code locations. Another popular tool that lets you tag and search internal documentation is Notion, but it does require context switching from your editor.

To further improve document navigation, cross-link related articles to improve information accessibility.

Regular process testing and maintenance

Lastly, the writing process is only one aspect of building your internal documentation. Don’t forget the maintenance and testing aspects of internal documentation. 

To repeat the production failure situation, you want to frequently test your process documentation to make sure the information is up-to-date. Writing documentation gives organizations a false sense of security. Include process testing and maintenance in your risk management strategy.

How to get started with internal documentation?

When starting with internal documentation, first select a tool that satisfies your needs. Select a tool that allows users to search through documentation to improve process discoverability.

Further, you want to get started with a handful of key processes that hold a lot of value for your engineering team or organization. When you have defined these processes, it’s time to create a template that describes why this process exists, the key stakeholders, and what people need to complete the process. It allows you to get started building your internal documentation quickly.

Again, remember to schedule regular process maintenance and testing meetings! 

‍