How to Write Awesome Internal Documentation

Ray Slater Berry
Ray Slater Berry • Aug 30th, 2020

This guide is to help you introduce internal documentation processes to your business. Whether you’re looking to start internal documentation for the first time or have a ton of knowledge but docs scattered all over the place, this guide can help you ace the internal documentation project. 

In this short article, we’ll help you build a business case to get the internal documentation project approved and walk you through how to structure the project with your own company.

 

What is Internal Documentation, and why is it so important? 

Internal documentation is essentially a process of getting all of your company knowledge in one place. It is the build of an open-source knowledge base as a reference point for all company processes and procedures. 

To build this knowledge base, you no longer need tools that document from source code or software engineering skills. It’s something that an office manager or project manager can take on. 

It’s worth noting that this is different from external documentation. External documentation builds a knowledge base for contractors or other external stakeholders; it’s more sensitive with information and is more customer-facing with its language. 

Your internal documentation is written and designed for your staff workforce, strictly for internal use. It’s essential to thread your brand mission and tone throughout your internal docs to ensure a sense of unity, even in an operational tool.

Source

Different types of internal documentation: 

There are different internal documentation types that you need to be aware of before getting started. Firstly, you need to ask yourself which bracket this knowledge base falls under— before you begin your technical writing. 

  • Team documentation. This type will revolve around important topics like team goals, style guides, talent, schedules, meetings, and timelines. It’s specific to certain areas of the company, and not everyone needs access to every team’s knowledge base.
  • Onboarding documentation. This type of “readme” documentation needs to be threaded into every employee onboarding when getting started and should be a constant reference point for current employees. Onboarding and user documentation should include HR processes and company-wide policies for new team members. It’s also a good idea to give an overview of company structure and people. 
  • Project documentation. This will probably be the most used knowledge-base in your business and one that needs to be continuously updated. This technical documentation area consists of projects, past, present, and future— it will be a reference point throughout any project and historical documentation.

How to manage internal documentation

1. Measure current internal documentation

First thing’s first, what do you currently have? Do you already have some sort of internal documentation in place, or are you starting from scratch? 

If starting from scratch 

If this is the case, then you need to identify whose head knowledge is currently sitting. This knowledge may not always be with the dinosaurs of the company. Perhaps fresh heads have come in, been placed with a process, and optimized for greater efficiency. 

Who is in charge of significant processes or pieces of knowledge? Identify those employees rather than people that have simply been in your organization longest. 

If you have basic internal documentation already

Don’t underestimate what you already have. If a business doesn’t have regulated, open-source internal documentation software, people tend to create their own to ensure they keep knowledge somewhere. 

You could have a collection of google docs attached to personal accounts. You could have Microsoft word documents on email chains or passwords and sensitive info stored in various people’s notes. Perhaps you have random information stored in javadocs. 

Whatever you’ve got at the moment, collect it all. This process will help you understand who has an overview of what and get inline with how people think information should be stored.

2. Layout discovery with an index

Something to help people navigate your internal documentation library when it’s finished and structure the information you need, an index. Your index should be logically constructed and can massively help in getting started. It’s often best to launch this part of the project with a diverse focus group from within your company. 

Indexing at the starting point in the process will also help guide your keyword search process that you’ll apply in the “how to use this company wiki” at the end of the process. 

3. Build architecture and templates

The next step in your company wiki building process is to create the knowledge base architecture and templates. Despite writing documentation no longer needing product development and source code, it should still be treated as a software project with a software engineering frame of mind. Think of how you want employees to engage with the knowledge base, how they will navigate between documents, and consider what makes the most sense to group together. 

If someone is looking for a particular piece of information, what other information will they find useful? It’s all part of the UX architecture. 

Next up is the UI architecture. How can you create visually appealing templates that are as engaging and joyful to read as they are knowledgeable? You can’t expect teams to power through great chunks of text, or unformatted copy. 

Build templates that are conscious of the visual design and aesthetic appeal of your knowledge base. What’s you’ve got these templates lined up, you’re ready to move on to the next step.

  

Source

4. Assign Creators

Internal documentation is a big lift and one that you can’t possibly expect to go at alone. One person in a large business can’t know the ins and outs of every department and process. 

Assign your knowledge base creators and call a structured meeting to onboard them to the authoring tool and launch the project. By “outsourcing” your knowledge base, you’ll ensure a more in-depth overview of the process and give yourself a holistic overview of the project status. 

Don’t worry about bringing so many people in at this stage. If you’ve followed the previous steps, everyone should know where their knowledge fits within the knowledge base. Your templates will also ensure that the knowledge you receive back is unified and structured— giving you minimal editing work. 

At this point, it may be worth clearing up with your contributors who will have access to their part of the knowledge base. Company wikis do not need to be accessed by everyone and can be harmful if they are. Give your contributors the peace of mind that certain people will only access their area. 

5. Review submissions to your company wiki

If you really want to ace your internal documentation, then it’s essential to thread in ample time to review knowledge submissions and for rounds of edits. People write differently; they have different use cases for team-specific words and may not have a writing style that matches the brand’s tone. 

Allow for this. Don’t think you need to take on the workload because of this, and it just means you need to edit the knowledge you receive to make sure it’s unified in brand voice and accuracy. 

6. Map operational use

While your stakeholders are creating their outlines and filling out your wiki templates, it’s time to compose the company wiki’s runbook. This “how-to” will be at the forefront of your onboarding campaign— it needs to be as clear as possible. 

These user guides should include example use cases, a guide for getting started and future use, and any faqs you think may come up along the way. 

Source

7. Get feedback and allow for updates

Once your internal documentation process and company knowledge base are released, try to hold a focus group or allow feedback as part of the development process. Allow people to @tag you and comment on their questions, concerns, or provide useful feedback. This way is especially useful for a distributed team working across different time zones. 

However, you can also consider hosting a feedback focus session after a couple of weeks of use. Collect a handful of users from the company and learn how they’re interacting with the tool. When you’re so hands-on in building a knowledge base, it can be hard to understand how other people interact with it. Give them an open opportunity to build the wiki with you. 

8. Assign owners by field and total project 

Last but not least, is looking after the lifespan of your internal documentation. Look at these documents as living sources of information. People will refer to them often and in times of need. 

It’s so vital that you keep this knowledge up to date. There’s nothing worse than someone using your knowledge base only to find outdated information and have to email around asking for the info they need. 

Thread updating the knowledge base into every contributor’s workflow, as well as your own.

Source

Wrapping up acing internal documentation

Internal documentation certainly isn’t easy. It takes time and dedication from not only the project manager but contributors as well. However, that doesn’t mean it’s altogether impossible. Use this guide as your go-to resource when implementing your internal documentation process. 

Remember, if you want to keep your employees engaged and trusting the information you provide, then you need to keep your documents up to date. Changes to processes or procedures need to be implemented in your knowledge base before communicated to the team. 

Look at good documentation as an opportunity to unite your workforce. It will give teams a greater understanding of each other and their work. It also has the power to amplify your business’s mission and vision with language and layout. Build the process slowly and carefully, you’re building a lifelong resource for your business, and it needs strong foundations to last.

Try it live 👇

Manage Internal Documentation with Slite

Hopefully, you’ve got some clear steps from this guide and can begin documenting internally with more confidence and a solid game plan in place. There's a lot to do and this process is ongoing, however, the largest part of the project is taking the first few steps. After that, it's just a matter of keeping things updated. You've got this.

Start your internal documentation with Slite