The What, Why, and How of Internal Documentation

Documentation: In tech, we spend considerable time producing user-facing documentation including API docs, how-to guides, knowledge bases, tutorials, and user manuals. We do this because user documentation is part of our product's user experience; without docs, people can't use our product.

The same thinking can, and should, be applied to our operations. Internal documentation is key to setting up our teams for success, especially in teams that are highly complex (like engineering organizations) and roles or tasks that are being done by one person. Internal documentation can include standard operating procedures (step-by-step how-tos on processes), one-pagers, briefs, reports, internal newsletters, templates, training videos, and more. These artifacts document a team's projects, processes, tasks, systems, forming the cornerstone of a team's knowledge management system. (In this blog post, "internal documentation" refers to documents intended for a team's own use.)

In this post, you'll learn what knowledge management is and how it benefits growing teams, and the three types of documents every team should create.

What is knowledge management and why is it important?

Knowledge management ensures that collective knowledge and information is captured and shared throughout an organization. It safeguards against "knowledge loss" from normal turnover, facilitates team learning, and helps new team members on board quicker. Knowledge management in the form of internal documentation ensures processes are replicable and protects against single points of failure.

Imagine joining an engineering organization that's comprised of subteams made up of engineers and program managers at different levels. You're on one of the subteams and are asked to join a bunch of meetings. Each meeting serves a different purpose, but the agenda isn't shared beforehand, and everyone on the call seems aware of what they have to answer for and what they have to do next. After the call, you see tickets in your queue but you're not clear on what any of the statuses mean. What do you do next?

You'll probably look for any documentation to help you understand what the meetings are for, how work items are assigned, and what the different states in the work items mean. In the absence of that, you might reach out to a coworker to ask them for guidance. Now, how would you feel if you always had to ask a coworker what to do next? Multiple times per day, every day, for weeks or months?

In teams that have good knowledge management practices, we observe:

• Better onboarding experiences
• More effective time management
• Clearer communication
• Increased morale
• More consistent output

However, teams with poor knowledge management practices have:

• Less clarity and transparency
• Work that varies in quality and consistency
• Conflicting guidance on what to do in specific situations
• Lower morale due to having to chase down answers instead of getting stuff done

I've spent years documenting systems and processes, even when I was the sole person in a function. I've successfully trained new colleagues and transitioned my work smoothly to others with minimal interruption as a result of investing time in knowledge management. Creating internal docs lets your team understand what is expected of them and what they need to focus on. It also lets your team pass on knowledge and train others up more efficiently.

What kinds of internal docs should we create?

Internal docs are meant for a team's own use and should live somewhere that the team can easily access. If possible, set permissions so that only team members can view these docs. Anything that is meant for a wider audience can live in a company Wiki or in a more "public" area on the company shared drive.

At a minimum, here are three documents every team should create:

Project inventory document. The inventory, typically a spreadsheet, lists the individual projects and initiatives the team is responsible for and working on. The inventory indicates timelines, priority level, project owner, dependencies, and supporting processes. A separate "task inventory spreadsheet" can also be created to surface ongoing work that supports team projects. This inventory is a living, breathing document and should be updated regularly (monthly or quarterly) to reflect changing priorities.

Standard operating procedures (SOP). Create an SOP to document any process that is critical to the team's work. The purpose is to document the process step-by-step from start to finish. I've created SOPs around taking new requests, publishing blog posts, creating and sending newsletters, updating a database, and shipping a new change on the website. Be sure to list any dependencies and contingency steps if something unexpected or undesired happens. And use screenshots!

Team onboarding document. This can be a template that is customized for each new hire. The onboarding doc should include:

• The team introduction: who the team is, what it does, where it sits in the organization, and what its goal is
• A list of team members, their titles, and their company email address
• Role description: A short write up of what this individual's role is and what they will do
• Links to the company wiki, intranet, or handbook
• A high-level list of 30, 60, and 90-day goals
• Who's who: the list of teams or individuals that this new person will work closely with, and who they should meet with their first few weeks
• Your team's rhythm of business (ROB) information: a list of team meetings and their descriptions, distribution lists to join, working hours, communications channels (email, Slack, etc), lists of systems and tools the team uses and their purposes

Additionally, each document should include metadata, such as:

• Document title ("Q1 2020 Project Inventory")
• Date created
• Last updated
• Document owners and contributors

Conclusion

Internal documentation is an integral part of any company or team's knowledge management system. Internal docs facilitate knowledge transfer between team members, create better onboarding experiences, and promote consistency and efficiency within an organization.

This post was originally published on my blog.

I'm Stephanie, a Content Strategist and Technical PM. Visit developersguidetocontent.com to learn more about my work!