Taking documentation one step further: to the 21st Century


Our world is full of documents; practically flooded. It seems as if analysts are competing in a "most pessimistic statistics" contest when discussing information inflation. Nevertheless, humanity has been writing documents in the same manner for centuries. Obviously, I do not mean we write in the same technical manner. We don't use typewriters and it is true that computerization has progressed human society greatly in the field of . Yet, in terms of documentation methodology ages have passed with only the slightest of changes. This article will hereby present a methodology that can be utilized to improve our documents, upgrading them to “21st century documents" status. The proposed methodological change is not technology based; no advanced technology is required in order to so implement such. It relies on tools and abilities possessed by every owner of a computer equipped with Microsoft Office or any equivalent document editor. The article will provide every organization with tools to produce documents more easily written, more easily read and more easily comprehended. The proposed methodology focuses on internal information design, i.e. better structuring of the document itself. This not only simplifies writing the document writing process, but mainly benefits the readers. 



The article is compiled from the following components:






Article Map


This article manifests the method presented in it. This might simplify comprehending the importance of this method. Note that the method's effectiveness lies in its simplicity.



Understanding the need


People Love new things; shiny new machines, hip fashion trends etc. Shortly after purchasing these items, we desire something new even though the existence of new technology is hardly reason to purchase or use it. Not all that glitters is gold.

This why before I present the new writing method, I must preface and explain what's wrong with the current state of documentation; what makes reading this article and implementing this method worthwhile.

There are many inhibiting factors in today's world of documentation:

  1. People find writing a document hard. It's easy to read a document written by a colleague and suggest many improvements, yet when presented a blank page our mind goes blank as well. We stare at the page, puzzled, stammering for the first words, then the first lines. Usually, everything that follows goes smooth. We hope to assist document writers and ease the writing process, as well as ease the reading for the readers. This is a matter of importance, as this "first lines writer block" causes many people to avoid writing altogether.
  2. People reading a document have a hard time, too. They reach the document unsure of the benefit they can possibly gain from reading this document. Nowadays, in the age of advanced search engines, we are exposed to a vast amount of documents. We usually skim through some of the documents till we decide what document might be useful. Filtering the information in an article is not an easy task. Six years ago, a malfunction of some sort occurred in a large organization's plant in Tel Aviv. They flew in a German expert in order to solve the problem. After briefly diagnosing the issue, he detected the problem yet was puzzled. "Why did you bring me in, when the same problem was successfully solved in another plant of yours, 30 miles from here, merely five months ago?" Needless to say, this was embarrassing. What undoubtedly made it even more embarrassing was the fact that the engineers actually reached the document depicting the event in the other plant (including the solution!), yet did not complete reading it due to lack of time. We wish to understand the theme of the document quickly.
  3. Even if we reach the correct file, reading long documents isn't easy, and it's even harder to read them twice. Some documents require only one read, yet in some cases we would like the worker to review the document again. This is true regarding procedures, manuals etc. Think back: how many times did a worker operate according to memory or, better yet, improvise instead of reading the instructions due to the length of the document plus a lack of time or patience? We wish to allow the worker to read the entire document while still focused.


In short, there is a real business need for a new method that allows us read and write documents better.



Document Map                                                                                              

An important principle we wish to instill in these new documents is the internal organization of the document. This means carefully planning the opening page of this document hereby referred to as the "document map", in which we will include information that may assist readers in understanding where they are and what they can find in this document.  A visual map will then follow. The objective of the document map is threefold: First, to enable the reader to decide, whether he or she has reached the document they are seeking for; Secondly, to understand its content and structure within a short glance. And last, but not least, to enable the reader to easily navigate to a specific location in the document, answering a specific issue in mind. These goals can be achieved by including a short explanation and a visual map describing the document components and relationships between these components. In some cases, we might add some hyperlinks to appendixes or external sources of information. Designing such a visual map might seem an easy task, even obvious. Yet designing a simple, yet constructive, map is not a trivial task at all as the writer has to formulate the table of contents as a visual feature that enables better understanding. Why? Because we want the reader to fully understand the nature of the section he or she is reading (in map terms "where he is") with minimal cognitive effort involved.

Following this method is an acquired skill. Yet although it is initially hard to write briefly, writers rapidly grow accustomed to this method. Furthermore, concise writing improves the thinking process, a benefit which makes the whole ordeal worthwhile.

Organizations that decide to initiate this process will begin by defining the candidate documents for change. These documents must feature two prominent attributes: long documents and documents with a fixed structure. Allow me to explain: there's no use in creating a page long document map for a two-page document. Those documents will be improved as well if their writers possess concise writing skills, but implementing the full method is a waste for this short document. The fixed documents I refer to are documents with a shared logic: procedures, product specifications, concept white papers, manuals, etc. Each family of documents has attributes of common components, and thus the visual maps will contain similar components as well (possibly differently linked). This is why the writer is actually not starting from scratch; he will not have to face a blank page every time he or she starts working on a new document map. This makes things a lot easier; furthermore, the reader grows accustomed to reading such documents, as was the case with hyperlinks, tag clouds and other new methods we eventually got used to.

The document map, and in it the visual map, are utilized as a gradual reading tool. They enable the reader to see the entire document from a general point of view which can focus on specific issues.



Information nuggets                                                      


While the document map initially seems somewhat complex to plan, the rest of the document is considered to be easier to handle by most. It is comprised of individual information nuggets. Each nugget is a component from which we comprise the visual map. Each nugget is usually no longer than one page. Thus, we can ensure the reviewing reader finds focusing on his relevant question a relatively easy task and prevent him from acquiring irrelevant data beyond the limits of his research question.

It is recommended to include the symbol that represents the title of each nugget in the visual map.



Concise writing                                                                      


We do not assume every document writer in an organization will become an articulate journalist. Nevertheless, here are a few simple rules that can assist us in acquiring some improved writing habits:

  1. Winston Churchill once started one of his letters with stating he does not have sufficient time to write shortly and so he will write in length. This is true. We actually find writing in length easier than writing briefly. Nevertheless, limit yourself to one page, force yourself to think and write concisely.
  2. Learn to write positively, simply and clearly. Advanced vocabulary and technical jargon are fine for professional magazines, but organizational everyday situations require simple writing, using words that can be interpreted in a single manner. Any reader should be able to fully understand this document.

Note: experienced content editors may be familiar with a more expansive set of rules, but the approach above suits any average worker in any organization.  We decided to focus on the most important substantial rules of concise writing. If these basic rules are internalized and used, that's more than enough.  




What can we learn from other content channels?         


We turn to the internet for information on many subjects. The internet has promoted our computing habits, as well as our conversation and consuming habits. The internet even affects our matchmaking habits; nowadays many youngsters use social networks when searching for a life partner. We can learn a lot from the internet itself when designing an advanced solution for document writing. The internet's contents are usually not written as a continuous string of data. Think of any news site. The homepage includes a central story, two financial items, two current events, etc. clicking on an item directs us to the full article which usually contains a link to other elaborative articles. In other words, we are gradually presented information; we can dive and resurface, not necessarily reading continuously.


Another completely different content channel we can learn from is the written media, i.e. the press. Skim through any weekend newspaper and review the way articles are presented. Their pattern of presentation manifests the principle of gradual reading. An article used to be comprised of a headline and an article. Nowadays, there are secondary titles beside the headline as well as informative sections on the side of the page. How do we read this page? We read the main heading, and then ask ourselves: is this a potentially interesting article? If the answer is "yes", we review the secondary titles (which are usually distinct in color and font). If we decide that out of the heap of weekend papers this article is worth reading the next stage is probably reading the informative sections on the side of the page. We judge the content a little more, review the writing quality and style, and then (and only then) actually read the full article. In other words, even when using a medium with no computing or hyperlinks, writers can create a gradually-read document.


The document method described above is similar to the press reading. You can read it all, yet you can zoom in and out and focus only on the most important at any specific moment.



Supportive infrastructure-organizing the document                                  


Internal organization of a document is a meaningful step towards taking documentation to the next level and into the 21st century. Nevertheless, it is important to remember that this step is complementary to other methods in use. It is always helpful to follow known guidelines as:

  1. Giving documents an explanatory name so people open it in the right context.
  2. Making the document easy to find by saving it in a folder from which it can be easily retrieved.
  3. Sorting all theme-related documents together in one environment in order to ensure only one copy and version of each document exists.


We won't explain how these processes are actually implemented since most organizations are already familiar with them and are currently implementing them in their work environment (on some level, at least). We just need to understand that internal organization of a document is complementary; it helps those who did reach the document. The other guidelines deal with external organization (AKA external information design) assist people during an earlier stage, when they are trying to understand what document is worthwhile reaching.



Illustrative example-organizational procedures                                         

Revolutionary changes in organizations are not mandatory. In many cases, a gradual, evolutionary change might take more time to complete yet is more likely to be internalized and realized. The same goes for smart document writing. Several organizations have begun with implementing the method for the group of managerial procedures. One problem we encounter in many organizations is that procedures exist and are written in detail, yet time after time we discover that despite the time and effort invested in writing them they are not enough in usage.


Organizations usually discover this when reviewing quality audits or reading debriefs. We are always shocked; we repeatedly discover that our employees do not fully follow our instructions. A procedure has been established, published and made known to the workers and yet still ignored. Some managers attempt to punish the workers which neglected the procedures, but the root of this problem also lies in the way we write the procedures. We're used to writing long procedures with many introductions, terms, approaches and versions. This tires the worker attempting to read through the document. Even those diligent enough to read through the complete procedure despite our tiresome writing, will probably not turn to this procedure when facing a real problem. Correct internal information design of a document, using the method suggested above, can improve procedure reading by volumes. It minimizes the time spent on writing the procedure since the worker writing the procedure is writing the procedure map according to strictly defined, uniform rules. He is practically filling in the fields of a form. The information nuggets are defined, and filling them in is easier as well.


Reading the document is also simplified, since the reader receives an image of the procedure excerpted from the map, specifically the visual map. He can either read the full procedure, pausing between information nuggets, which also serve as breaks.  He can read internet style, diving and resurfacing. And he can read, when perplexed, only the relevant section of the procedure, which he can reach via the visual map. It is too soon to tell, statistically, what percentage of malfunctions was reduced due to changing the procedure system, since the first projects in which this method was implemented are still running, yet it is clearly a change for the best.  People see a successfully written procedure and stand in line to recruit the unit to write improved organizations in their division or group.


We won't elaborate on the order in which we choose procedures (hint: there is a gap between existing procedures and implementation), nor will we describe the preparatory infrastructure work for an inclusive organizational move of this magnitude. We will only say that people love success and when they spot one, they want in on it. Implementing this method can solve a problem which was yet to be addressed. This method solves the problem itself instead of focusing on its symptoms (i.e. the direction and internalization). And as was learned over time, you can't argue with success. 



Summary: Benefit-what do we get out of this?                                                   


Implementing the method described above benefits all participating parties: the writers, the readers, and mainly: organizations as a whole.

The writes benefit from this method, since they learn to:

  • Write concisely, according to specifically defined rules that ensure accuracy.
  • Create a consistent document writing language.
  • Utilize a specific, detailed writing process.
  • Improve the flow of the relevant data to the appropriate worker.

The readers benefit from this method, since they can now:

  • Navigate through the document guided by an easy to understand map.
  • Quickly locate relevant knowledge.
  • Utilize an overall view of the written document.
  • Read interactively, in any style they prefer.

And finally, the organizations benefit from using this method since it improves the use of existing knowledge and information and ultimately enhance the organization’s advantage over competitors.


In short, this method is more than worthwhile.