We tend not to know the value of something until it’s gone, and that’s especially true for documentation. But how much does a lack of documentation really cost?

Let’s say that a given organization has eight new workers across all its departments. For the first three months of work, I estimate anywhere between 25-50% of those workers’ billable hours will be spent acclimating to existing systems and procedures and preparing their work environments for development. At an average rate of $45 per hour, that comes to a cost of $43,200 – $86,400 spent on acclimation in those first three months — and that’s that’s just for the new hires. Across all departments and systems, how many hours will the Operations & Maintenance teams spend working with systems each year? What about during a crisis? If there’s limited, inaccurate, or, even worse, no documentation, how many thousands of additional hours are being spent on getting up-to-speed across any given organization each year? In a small organization with 10 employees, roughly $45,000 will be lost each year due to a lack of documentation, and that scales upwards: without sufficient documentation, an organization with 100 employees will lose $450,000 per year; one with 1000 employees will lose $4,500,000 per year, and one with 3000 employees will lose $13,500,000 per year.

While cutting costs on documentation sounds at first like it’s trimming the fat, the reality is that a lack of documentation will slowly bleed an organization dry.

This article gives a brief overview of some of the most common problems an organization or individual might have with documentation and suggests an approach to fix it.

Problem: You don’t know who has the documentation for a system or application, or what you have is out-of-date.

Solution: Use a central repository for all documentation. Bonus points if it has some kind of version control: this could be SharePoint, OneDrive, Git, Confluence, or Wiki, but what really matters most is that it is SOP that all documentation from your department or organization goes to it. It should be organized intuitively and maintained regularly.

Problem: You aren’t sure where to get the right version of a required application or developer library.

Solution: Create a file repository on the same server as your central document repository. Organize all those different versions of Adobe, Apache, and Oracle apps (not to mention developer libraries!) in a way that’s logical for its purpose, which could mean bundling the files with the associated installation guides, or organize them by product. The most efficient method should be chosen according to the most common use-cases.

Problem: You find yourself having to open documents to figure out what they are.

Solution: Organize and name documents logically and consistently, and be sure to maintain this organization —it won’t help if you only use it for some documents but not others.Keep them hierarchical folder structure that is appropriate for your needs. Name your documents according to content, purpose, date, or any other criteria that you or others may be looking for. Just as an example, you might name your files according to the following format: <project name> – <document purpose> – <draft status>.docx. It may seem a bit basic, but you’d be surprised to see the jumbled file names on documents that get sent up to the very top (or from the top!) of a company or agency.

Problem: It takes too much time to find the information you need within your documentation

Solution: First, use MS Word’s Multilevel List feature to organize content in documents under clearly defined headings (plus, you can then quickly promote/demote the importance of a section using tab/shift + tab, which makes formatting much more time-efficient). Second, use Word’s auto-generated Table of Contents feature. This will generate a clickable ToC based on the headings in your document. You can make your documents even more convenient to navigate by using Word’s “Cross-Reference” feature, allowing a selection of text to be linked to another section anywhere in the document. Even better, all these interactable features will persist despite converting a DOCX to a PDF.

Another feature that helps save time is including a purpose section near the top of the document (usually near the introduction), so that readers can quickly determine if the document they are looking at is going to be useful to them.

Problem: You have documentation, but people have difficulty understanding and following it

Solution: There could be a few reasons for this, and I’ll go through the most likely culprits here. Firstly, the right medium needs to be chosen based on the message. Is the information a set of inputs/outputs and return codes for an API? It probably should be put in a table. Is it a list of database entities and their relationships? Make an Entity Relationship Diagram with a diagram or drawing app. Is it an introduction to the project including its history? It should probably be written in paragraph form and in chronological order.

And speaking of writing in paragraph form, this brings us to the next solution: make sure the information is organized in a logical and accessible way for your audience, i.e., the right level of background information and context is being provided. If it’s a Systems Design Document, it will be fairly technical, but if it’s an O&M guide, someone who was hired a week ago should be able to understand and follow it. But how can we write in a way that’s more logical and accessible? I’m glad you asked!

Generally speaking, information in writing should be presented from the most general first and get progressively more specific as it continues. One of the best tools to help writers understand this concept is what’s known as “the inverted pyramid model”

The inverted pyramid is a generalized model used for many different genres of writing, but the guiding principles of “general information -> specific information” and “more important -> less important” hold true regardless of whether one is writing an essay, news article, or technical documentation. If your article’s overall outline as well as the information in each paragraph follows this model, it will almost certainly be more digestible and easier to follow for readers of all levels of familiarity with the subject matter.

Conclusion:

If something is worth doing, it’s worth doing well, and that’s why just having documentation isn’t enough — it needs to be available, up-to-date, logical, organized, and understandable.

I hope these tips have been useful for you or your Technical Writer. If you have any questions or comments related to this article or writing documentation, feel free to reach out to me on LinkedIn.