Internal documentation—the practice of creating and maintaining a record of processes and procedures team members can reference—is essential for knowledge sharing.
Additionally, it helps companies improve onboarding, manage complex projects, scale customer support, innovate, and enhance bottom-line results.
Excessive and improper documentation, however, can have a series of negative consequences, from causing employee burnout to driving development of inferior products.
Excessive internal documentation causes information overload
One of the main dangers of excessive internal documentation is information overload—the exposure to more information than one is able to process.
Information overload is a major source of stress and poor health among workers worldwide. Research shows that it induces error and impairs decision-making.
For example, when companies try to improve more than two processes at once, employees quickly become overwhelmed and make mistakes they wouldn’t normally make. This is largely due to having to process an excessive amount of data.
“Having a number of simultaneous improvement initiatives puts unnecessary information overload on those implementing the programs, because hundreds of pages of training slides or manuals have to be reviewed, understood and acted on for each initiative,” researcher Satya S. Chakravorty wrote.
Alarmingly, information overload starts at the onboarding stage. According to ELMO’s 2019 HR Industry Benchmark Report, it’s one of the biggest challenges businesses have in onboarding new hires.
“Many employers don’t realize that they’re dumping way too much information into new hires’ laps. In the haste to bring people up to speed, they wind up trying to get new employees to learn everything about the company at once,” wrote CEO Anett Grant.
Requiring excessive internal documentation impacts productivity
The excessive focus on documenting work can prevent employees from doing actual work. Here’s what happened to Agile coach Jens Coldewey in his first experience as technical lead in a project:
“I sat down with the team for nearly half a year, sketching object designs on the whiteboard, writing it down in a document, refining it, writing it down, refining it, and so on. In the end we had a 120-page architecture document which was quite sound—but not a single line of code,” he wrote.
Accounting professor Jeanine Kuwik agrees that there is such a thing as too much documentation. She writes that excessive reporting can slow down processing, frustrate employees, and be expensive to maintain.
She also warns that placing too much emphasis on documentation might drive employees to create workarounds or shortcuts, especially if they view requirements as impractical or pointless.
“This may result in an undesirable culture that is increasingly dismissive of all guidelines, not just the less practical ones.”
Excessive internal documentation can lead to inferior products
By now, most software development companies have ditched documentation-driven development processes in favor of working software and “just barely good enough” (JBGE) internal documents.
Product leaders have realized that overly detailed documentation isn’t compatible with the dynamic nature of software development.
Documents go out of date as soon as they’re created. Also, product requirements documents (PRDs)—documents that list the features that need to be built for a product to be deemed complete—are often out of sync with users’ actual needs. This can lead to “feature bloat,” when features get built but not actually used.
“Unless you’re building a nuclear reactor or similar high-risk, capital-intensive product, requirements documents are simply the worst possible way to bridge the gap between the customers’ needs and the team that is trying to build the solution,” product leader Martin Eriksson wrote.
Best practices for internal documentation
Companies that aren’t in software development can still benefit from an Agile approach to documentation, which is based on the four principles below:
- Make it “just barely good enough” (JBGE). When documents are lengthy and overly detailed, employees don’t want to read or maintain them. Keep documentation light, simple, and easy to update.
- Write it “just in time” (JIT). Information can quickly become outdated. Whenever possible, wait until the very end to create project documentation.
- Keep documentation in one place. If documentation isn’t accessible, team members will not use it. Store it where everyone can easily find it.
- Encourage collaboration. Maintaining documentation should be a collaborative effort. Encourage everyone to contribute.
Creating an internal documentation process
In addition to following the principles of Agile documentation, companies can also benefit from setting some ground rules about what gets documented, how, and how it’s distributed—also known as an internal documentation process. Here are the steps to creating one.
Determine what needs to be documented
Rather than attempt to document everything, companies should set criteria for what needs to be documented. Typically, the most used types of internal documentation are:
- Documents pertaining to projects
- How-tos for things team members do repeatedly
- Technical and software documentation for every technical product
Companies can also establish that, if a process occurs an x number of times, then it’s worthy of being documented.
Create templates
To ensure documents stay consistent, it’s helpful to create templates. Atlassian’s guide to internal documentation suggests including the following fields in templates:
- Description of why the process exists
- Identification of key players in this process
- Resources needed to complete the process
Decide where documentation gets stored
Create a folder or a hub where documents can live. Google Drive, Trello, Basecamp, and Confluence are popular options.
Set some time each month for tidying
Even when there are rules for creating, maintaining, and storing internal documents, things inevitably get messy. It’s important to set a little time each month to check documentation and tweak your process.
Create internal documentation that is usable
Internal documentation can help companies onboard new hires, strengthen organizational culture, and equip employees with the information they need to do anything—including tasks they’ve never done before.
But, to keep internal documentation usable, it’s important not to overdo it. Rather than attempt to document everything, companies are better off documenting only what’s essential, and keeping documentation easy to read and to maintain.
Accessibility is also important—documents can only save time if employees don’t have to waste time looking for them.
By following Agile documentation principles, and putting an internal documentation process in place, companies can preserve valuable knowledge without compromising productivity.
For more useful workplace tips, check out:
