The tech-writer’s journal #9 — All you need to know about Internal Documentation

Artwork by Justina Stasyk: justynastasik.com

Welcome to yet another post on the Tech Writer’s Journal. In this blog, we will discuss Internal Documentation.

First things first — What is internal documentation?

Internal documentation is the process of maintaining a knowledge base of all your company’s internal processes and operations. It develops to become a single source of truth to all your employees.

The difference between internal and external documentation

1. Target audience
   The target audiences of the external documentation are contractors, external stakeholders, and customers, while the internal documentation is designed and built for your workforce.
2. Language
   The content in the external documents is much more sensitive than the one in internal documents. In the external documents, the documentarians must consider various aspects such as inclusivity and accessibility. The rules are not quite stringent when it comes to internal documents.
3. Accessibility
   The external documentation is sharper in factors such as accessibility, discoverability, and so on.
4. Tone and voice
   It is essential to maintain a uniform voice and tone throughout your external documents that unanimously represent your brand. In contrast, the only goal of your internal documents is to educate your workforce. The accuracy of the content becomes the top priority.

Why have internal documentation?

1. Save time and effort
   The newbies in your team can always turn to internal documentation than setting up meetings with seniors or working their way through them with a ton of guesswork.
2. Reduce dependency on a team member
   Your team’s internal documentation is you to your future team members (both new and old). Say a person who has been on your team for about a decade decides to leave. It would make more sense to rely on and share internal documents than to sit through countless hours of KT sessions.

Factors to consider when you start building internal documentation

1. Who are your end-users?
   Defining your end-users is quite a generic step in every documentation. For internal documents, the target audiences are the employees of your team or your organization. But you need to consider the amount of knowledge that the different sets of employees might have. The internal document might be referred by a newbie or a manager with decades of experience in the industry.
2. Easy to follow
   Having easy-to-understand language is yet another rule of thumb when it comes to technical documentation. It is always good to avoid jargon, acronyms, or complex language. Ensure that you make your document skimmable.
3. Engaging
   Yes, you are building internal documents, and making it engaging is probably the last thing in your mind. But then, remember that nobody’s going to look at your documentation if they feel that it is draining. Ensure that you do not rely solely on text. You may add examples, images, videos, GIFs and make it as engaging as possible (with corresponding alternate texts).
4. Accessible
   There is no point in creating documents that are not accessible. Irrespective of the type of documentation, the information presented must be accessible to everyone.
5. Easy to contribute
   Internal documentation is a task that is too huge to be taken up by a single team member. Allow your team members to download their brain onto a page. After all, they are the ones who are most familiar with those tasks.
6. Easy to update
   Documentation is never something that is set in stone. In contrast, it is a living, breathing thing that is evolving along with your product. The last thing you want to do when there is a process change is to manually update the entire internal document. Ensure that the process of updating documents is as easy as accessing them.

Maintaining internal documentation

1. Get feedback
   Get regular feedback from your colleagues. The easiest way to do this would be to have a comment section on each page where the developers can have a healthy discussion.
2. Assign owners and follow up
   As stated earlier, internal documentation is too big of a task to be created and maintained by a single employee. It is vital to keep the content up-to-date. The easiest way to do this is to assign owners to each process/procedure and give them access to update the document.

Taking up the task of creating and maintaining internal documents can be daunting. However, with a clear pipeline, usecases, and execution strategy in mind, you can always succeed. Consider internal documentation as an opportunity to unite all your team members to build a lifelong resource for your business and product.

References

How to Write Awesome Internal Documentation: A Complete Guide | Slite

How to ace internal documentation | Team Central

Why Internal Technical Documentation is Hard

Why it's worth it to invest in internal docs - Increment: Documentation

Why You Shouldn't Ignore Internal API Documentation | Stoplight API Intersection

How 5 Companies Use Internal Documentation To Scale More Efficiently | Tettra