Common Documentation Problems & Solutions

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.


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.

Can We Defeat Totalitarianism Without Becoming Totalitarian?

Image Credit: Unknown

In late 2009, a man ran through a crowded Beijing street with a sword, stabbing around 18 people and killing an unknown number of them. Who was he, why did he do it? People will never know: It was banned from being reported as it would disturb the public to know something like this had occurred — there was no benefit for the Party if it was reported. Thus, the Party determined it would not be on the news and any mention or discussion of it online would be scrubbed.

The only reason I know of this event is because a friend of mine worked for Chinese state TV at the time, and they had been told by the party not to report on the event — so, of course, by telling people what not to report, they knew roughly what had transpired.

In 2014, when a terrorist attack in Kunming killed dozens of people at a train station, it was reported widely. The knife-wielding attackers were terrorists furious over ongoing Uyghur repression in Xinjiang, and stoking fear, anger, and overseas sympathy all served the party. State newspapers and foreign newspapers alike reported on the tragedy for weeks.

In relatively free societies where media and other facets of life are not tightly controlled by the state, it is not a political party or government who determines what news is reported on, but instead the prerogatives of the journalists and editors. I say “relatively free”, because today the vast majority of newsrooms are based on ratings/clicks for revenue. Without a tightly state-curated online environment, individuals are free to upload content to private corporate platforms such as Twitter, YouTube, Substack, Reddit, et al. if they wish to report on their own news. In this case, certain content and perspectives are projected according to the publication, and censorship is performed by the staff running the platforms according to their own beliefs and interests.

Time for the big questions: How can a society plagued by petty in-fighting and divided artificially resist the combined power of another people bound by a singular ideology, regardless of how bankrupt that ideology may be? How can such a loosely organized, chaotic and distracted people come together and achieve what is necessary to prevent the ever-creeping encroachment of totalitarian dictatorships?

Do we need a unifying media presence? Public news that is neither for profit, nor censored according to private companies’ ideologies? A coordinated, cohesive voice that tells people what to pay attention to and care about so that we can actually get something done rather than pull ourselves apart? Is there even a way for such a thing to exist anymore, and if there were, would it even be sufficient? And would doing so not put that society at risk of becoming totalitarian itself?

And, don’t forget the kicker: The result of falling to totalitarianism is becoming totalitarian. These might be difficult questions to ask and answer, but we avoid asking them at the risk of losing the ability to question at all.