The internal and external structure of working procedures

Foreword

I love to try organization systems, and to read about documentation and productivity. I bring this passion at work, where I like to help organize my team’s files and documentation. It’s fun and natural for me to organize things and information. I always want to know more, and I ask myself a lot of questions.

Why is the structure of documentation important? What goals does it serve? How should working procedures be organized? What are the minimum requirements for a good documentation system? How can I make it easier for others to use and contribute to documentation? How can I make documentation more useful to my team?

In this essay, I follow these question threads and I try to synthesize and explain what I researched and learned about organizing documentation at work. It includes external references, explanations, methods and examples. As I am writing this, my goals are to become better at organizing documentation systems, to share my thoughts with others, and to discover even better ideas through conversation with you.

Introduction

In an enterprise, working procedures are organized in a business documentation system. The system helps organize the information in a tree of directories and document nodes, and then further organized within documents under a hierarchy of headings. In this essay I describe a categorization scheme that satisfies goal-driven behaviour for finding and using information efficiently in the workplace. Then I demonstrate the importance and a method for organizing information within documents by referring to knowledge about human memory types.

As a result of organizing working procedures in a tree of directories and documents, and of organizing information about working procedures within documents using headings, a documentation system provides the minimal amount of functionality required to successfully support employees in carrying out enterprise business efficiently.

Before concluding, I will comment on search and tags functionalities. Such features are not required strictly, but are useful enough to be almost always present in documentation systems.

There are other organization systems for other kinds of documents that I will not describe in this text. Project support material and customer documentation, for example, are not organized the same way as operational procedures. These will be described in future posts.

Literature review

Here are some recommended readings that provide complementary, contrasting or contextual information about documentation.

In Work the System, Sam Carpenter (2018) lays out fundamental principles for systematizing business outcomes through documentation. He proposes a format and process for creating the three main documents:

• Strategic Objectives
• General Operating Principles
• Working Procedures

Work the System is a very good guide to understand what working procedures are, why they are important, and how they should be written. My essay focuses on how to organize and structure this information.

Diátaxis is “a systematic framework for technical documentation authoring.” Diátaxis distinguishes four types of technical documentation: Tutorials, How-To Guides, Explanation, and References. This model has applications in working procedures as well. How-to guides and references are useful for day-to-day work. Explanations and tutorials are very important for onboarding and training new team members.

In The PARA Method, Tiago Forte describes a “simple system for organizing your digital life” under four main categories: Projects, Areas, Resources, and Archives. While PARA is a comprehensive and universal method for organizing information, business documentation described in this essay is mostly made of Areas and Resources.

Contribution

Expanding on Carpenter’s (2018) fundamentals, and abstracting from my experiences with creating procedures in a technical support team, I will elaborate on two main areas:

1. A taxonomy for organizing procedures in a documentation system to make finding relevant documentation efficient.
2. A style guide for structuring information in documentation pages to make it consumable easily and efficiently.

Working procedures are repeatable stories

Sentient life is universally expressed and experienced in the structure of nested stories. The start and end states of a story consist of a current situation with a problem, a desired end state where the problem is resolved, and a planned sequence of actions and decisions in between.

Life at work is no different. All work activity can be comprehended within this narrative structure.

Working procedures are collections of the best known solutions for solving recurring problems in an enterprise. You can compare them to story templates, or maps.

The external and internal structure

Our mind only perceives the world according to what is helpful or detrimental to reaching our current goal, from our current situation. The external documentation structure should help us to locate the one document that contains the information that will help us solve the problem we are facing right now.

Once we have found the most relevant document, the text must state the current problem (for validation) and walk us through the process of solving it reliably and confidently. The information needed to solve a problem is often complex. It has multiple levels of detail and abstraction, which is why it’s internal structure must organize the content using headings and semantic formatting.

Information in a documentation system is organized in a tree structure that reaches between and through all documents. The tree structure between the root and document nodes is what I call the external (or inter-document) structure. The tree structure that is contained within document nodes is what I call the internal (or intra-document) structure. A semantic, functional and formal division exists at document nodes, differentiating the external and internal structures.

A taxonomy for organizing working procedures

The main problem with organizing information in a documentation system is to chose the appropriate taxonomy. Documentation can be organized in infinite ways, but we need a classification system that is simple and serves a clear motivational purpose. The purpose of external documentation structure is to quickly locate the best known solution to a given problem.

Because humans are a specialized species, responsibilities and tasks in an enterprise are divided in functional and mission-oriented business units and teams (Grove 2015). It follows that the most fitting taxonomy to organize documentation about every task follows the functional and mission-oriented organization model. This is not to say that the documentation directory tree maps directly to the company’s organization chart. As Andrew Grove (2015) describes in chapters 8 and 9, Hybrid Organizations and Dual Reporting, work is arranged both in a hierarchical fashion, as well as in cross-functional planes. The first level of categorization will capture functional, mission-oriented, cross-functional and peer groups.

At any given time, workers are in one of various possible modes of operation. It could be writing code, having a meeting, delivering or receiving training, interacting with a customer, or doing project management. While working in a given mode of operation, people switch from one task to the next within a set of related procedures. Workers are always in exactly one mode of operation at a time. The 2nd level categorization should be the modes of operation or areas of responsibility. At this level, the particular categories that emerge will be different for each profession, but some generalities exist.

I will refer to two existing models to help with classifying a team’s working procedures and references: Getting Things Done, and The Para Method.

David Allen (2015) teaches useful models which can help think about work modes in a team. In the “Do” stage of mastering workflow¹, Allan introduces “Context” as the first of the “Four-Criteria Model for Chosing Actions in the Moment”. Context is a primary category for organizing tasks in a productivity system. Context can be thought of as where we are, what tools are available now. David Allen uses this model for selecting which task to do in a given time, but I find this principle can also help categorize working procedures within a team’s collection.

Also in the “Do” stage of mastering workflow, Alan presents “The Threefold Model for Evaluating Daily Work”.

• Doing planned (“predefined”) work: crossing tasks off your list, “deep work” periods blocked off on your calendar, working on support tickets by order of urgency and priority.
• Doing project management (“defining your work”): sorting email, triaging issues.
• Reacting to interruptions (“doing work as it shows up”): working in a reactive mode, being on call, responding to alerts, documenting a new problem or updating documentation².

Another model I refer to when organizing procedures is The PARA Method by Tiago Forte. Specifically, Areas and Resources are the most relevant types of content that helps classify a team’s working procedures. Areas and Resources are analogous to the modes of operations I referred to earlier.

Based on these basic models of categorizing tasks, we can provide employees with a short path to the documentation they need to solve the problem at hand. The first step is the team membership. Then, the mode of operation. Finally, one document for each working procedure.

How to organize working procedures in a documentation system

Based on the taxonomy defined in the previous section, here are practical examples and tips for organizing working procedures.

Categorization level 1 identifies business units and teams. Documentation systems call these Collections (Guru³), Sites (Simpplr⁴), or Spaces (Confluence⁵). Their main purpose is access control to the content based on one’s team memberships and roles.

Guru enforces a maximum directory structure depth of 4. I find this limitations is effective at enforcing a pattern that is simple and works. It’s after using Guru that I noticed the two basic levels of procedures organizing.

Here is the basic organization model:

• Level 1 — group of people — “I am a member of the ____ team.”
  • Level 2 — mode of activity — “I need to solve a ____ problem.”

Each level may be 1 or more subdirectories deep, following the approximate structure of the business units within the company. Read the following two sections for examples.

Level 1: Functional units and business units

The first level directories might include names like:

• Company (company-wide references, strategy, policies, programs)
• Human Resources
• Solutions Engineering
• Marketing
• Customer Support
• Products (cross-functional knowledge base and procedures)

In the course of day-to-day work, employees will refer to multiple sections of working procedures, not just the one they “own” or “belong to”. For example, customer support employees will use the Customer Support section for their mission-related tasks. They will also refer to Corporate and Human Resources sections for operational guidelines. The Products section has resources relevant to both Sales and Support employees. Sales people need to know how the product they are selling are supported. Support people need to know how the product they are supported are sold to customers. Consequently, read and write permissions must be managed separately.

Level 2: Work states, or modes of operation

Building on top of the level 1 described above, we can start dividing into modes of operation, areas of responsibility, and topics of references. here is an example of a documentation system structure in a tech company, with levels 1 and 2 of this taxonomy.

• Technical Customer Support
  • Operations
  • Request types
  • Customer alerts
  • Trainings
  • Tools
  • Team
• Company
  • Who Are We
  • Tools, Links, Systems
  • Human Resources, benefits
  • Modus Operandi
  • Security
  • Offices
  • Social life
• Marketing
  • Operations
  • Blog
  • Community Management
  • Campaigns
• Sales
  • Operations
  • Tools
  • Competition
  • Collateral
  • Trainings

Special case 1: Products

There is a special case of categories reversal. In a company, everybody relates to the products and services. Sales use functional documentation and use-case stories. Customer Support needs to organize routine and troubleshooting procedures. There is no single team having central ownership of products. Not even product managers, because they cannot entirely predict how the products will fail or succeed in the hands of customers. Product managers establish strategy and guidelines, and they have a partial ownership of product documentation.

The ownership and responsibility of product documentation is tricky. For all other documentation sections, the “ownership” and maintenance of working procedures is obvious. For products, the main structure is owned by product managers, and other teams have their own subsection for their resources and supporting material. Multiple teams have write access to this area, and the responsibility and ownership is collective.

Here is an example of a folder structure under the level 1 folder Products:

• Products
  • Product A
    • Product roadmap and strategy
    • Sales plays
    • Support resources
  • Product B
    • Product roadmap and strategy
    • Sales plays
    • Support resources

I think the exception of centralized and cross-ownership of the Products section as a first-level category is justified. There is value in allowing Sales people to know the scope of support. There is also value in Support people knowing how the product is sold. A company’s core products transcend teams and business units. The entire company shapes itself around the manufacture and selling of its products.

Special case 2: Security

Security procedures are a special case because security is a prominent example of a hybrid function in a company. Because good security is “security in depth”, there will be a centrally-managed Security documentation section, as well as security sections scattered across all other documentation procedures.

Primarily, a central corporate functional unit is responsible for governing security for the entire organization, across all mission-oriented teams.

Secondly, every team, procedure and system must implement appropriate security controls in accordance with corporate guidelines.

HR experts performs background checks for candidates. Customer Support engineers have a procedure to authenticate requests. The central corporate function enforces social engineering awareness and other training programs. Products have security features, recommendations, certifications, vulnerability reporting and patching.

How headings help ingest information

The external organization structure and taxonomy has helped us locate the document relevant to our current situation and desired outcome. Hopefully, that document describes the best known solution for solving the problem at hand, based on collective previous experiences dealing with it. The content of that document has a high potential value. However, reading documentation is expensive. It takes time and focus. As a reader, I need to know if reading this is worth the effort before investing energy into it. Additionally, it would be lovely if the information was organized in a way that naturally flows to engage memory and motor systems, otherwise we would have to spend extra cycles to parse out a mess of unstructured thoughts.

Intelligent prose is written and read across multiple planes of analysis, simultaneously. This section describes frames of analysis that I find relevant for writing good documentation.

Cultural and temporal context

Past

Where does this information come from? How have other people handled this situation before?

Present

What’s the current status of the procedure? Can I use it? What is the delimitation of known and unknown territory?

Future

Which way are we trying to pull strategically? What are the collective ideas or plans for future improvements?

Reader narrative

Information in a document follows a narrative structure that accompanies the reader through a sequence of states of mind.

• The first part presents contextual information that answers the question “Is this document what I’m looking for? Should I continue reading?”.
• The middle takes the reader on a walk, step by step, through the best known solution.
• There are multiple possible endings. Readers don’t parse through the entire document linearly.
  • Some endings are the best outcome. Job is done. Reading stops.
  • Some other endings are ambiguous or not yet abstract or general enough, so they require described examples and screenshots.
  • Other endings are dead-ends, unknown territory, uncharted edge-cases. Hopefully, there is a person to contact, or a clue left by someone who had a hypothesis but didn’t have time to experiment with it.

Neuro-psychology

The information needed to carry out a procedure has many levels of abstraction. These levels of resolution map to different types of human memory⁶ and abstraction levels⁷.

• Procedural memory is used when following a sequence of steps, involving motions like typing, clicking, navigating an application.
• Episodic memory is one level of abstraction higher, where information is understood in context, and as a sequence of subjective events.
• Semantic memory recalls information applicable outside of context, like facts, concepts.

How content sections relate to memory types

Section headings should engage the appropriate memory structure and the right frame of thought for processing the information that follows. By segmenting and organizing information into headers, you are helping the reader engage the right memory unit.

Qualities of good headings and document structure

The headings play two roles.

First, they tell the reader how to use the information that follows. For example, the section heading “Context and scope” evokes episodic memory. The reader will expect to understand how the procedure is nested in a overarching story. The section heading “Procedure” evokes procedural memory. The reader will expect to use their motor system to perform a sequence of motions in the physical world.

Second, headings form a narrative path that the reader can follow. That is the arrangement and order of headings within the document. This structure follows a typical introduction, content and conclusion pattern. It is not quite a literary essay, but there is a priority order of information that the reader is typically interested in. First, they need to validate whether a document is relevant to their story. Then, they need to know about operating parameters or guidelines so they can use their best judgment in ambiguous situations and know where to ask for help if a situation is outside of the scope of the procedure. Then, they will follow step-by-step procedures, templates, examples and visual aids. Lastly is information on known unknowns (“Future improvements”), links to related articles (“See also”), links to reference documentation.

How to structure information in documentation

Here are practical examples and tips for structuring working procedures.

Examples of section names

Use the example outline below as a template for writing new documentation. It achieves both goals of organizing information by type and of creating a narrative for the reader. Using an outline template also helps the writer to ensure the all the relevant and known information is present, and that pieces of information are organized.

• Context (when does this procedure apply)
• Guidelines (scope, limits, overarching strategy and goals)
• Procedure (step by step motions to perform)
• Mechanism (describes the automated parts of the procedure)
• Template (communication templates)
• References (external reference documentation)
• Example cases (links to support tickets or project documents)
• Case analysis (edge cases described)
• Future improvements (known unknowns, ideas for improvements)
• See also (related procedures)

Style guide for section headings

Here are some guidelines and advice for using section headings within a document.

Don’t use bold and larger font size on regular text to make it look like a header. Use the predefined styles.

It is very hard to read a linear text with more than 2 levels of structure. Consider splitting into multiple documents.

If you put multiple procedures or templates in a documentation article, append a colon (:) and a subtitle. For example:

• Procedure: Refilling the thing
• Procedure: Cleaning the thing
• Template: Existing customer
• Template: New customer

Avoid blobs and brain dumps

Brain dump are raw field notes copy-pasted into a document and saved as-is. It looks like a blob of loosely related information without processing or cleaning. Brain dumps have some value in that they contain the information you need, “it’s there.”

But when reading this kind of semi-structured mess, the brain has to work extra hard:

• to decide if the information is applicable to the current story/context in the first place,
• to associate related things together,
• to distinguish what is a guideline, an example and a procedure step,
• to put things in sequential order.

If the brain was able to just absorb information like a mouth on a fire hose nozzle, then we wouldn’t need to think about internal structure.

Comments about search and tags features

Every documentation system has a search engine. So why bother organizing information in a directory tree structure?

On a search results page, the title, directory and tags are the only meta-data available to put items in context and decide which ones are relevant. Without a well chosen title and classification, search results are opaque, noisy and meaningless. Consequently, search cannot replace careful organization. But organization and retrieval without assisted search is possible.

Tags are ad-hoc, arbitrary, and their semantics are always contextual. They can enhance the search capability when used in filtering. They allow creating groupings that escape the directory tree structure. But their usage cannot be enforced globally. Therefore they cannot replace organization structure, they can only complement it.

Conclusion

By documenting how I do documentation⁸, I hope to achieve several goals simultaneously:

• To be able to explain my method and my reasoning with more clarity,
• To discover different, better ideas in conversation with you,
• To share models and templates that are sufficiently general to be applicable in many other projects and companies,
• To get better at writing and organizing documentation,
• To make people’s working life better.

Before writing this essay, I had an intuition of how and why I organize business documentation a certain way. I’m glad I took the time to examine the internal and external structure of documentation. I’m surprised at how many concepts and ideas this topic involves!

I’ll close off with two advices and one request.

Having well organized documentation is not a project goal or an end-state. It’s an ongoing process, a habit. It requires a daily and weekly maintenance and incremental improvements by everyone involved in the day-to-day work activities. Setting up a skeleton structure and some templates as a starting point helps a lot, but what keeps documentation relevant and useful are the daily improvements, week over week, year over year.

Smart people know a dependable system when they see one and use it for some time. I believe that once a good system is in place, and people start trusting that they will find information they are looking for, with a little bit of guidance and coaching, people of all writing skill levels and personality types will successfully and enthusiastically adopt the system, maintain it, and contribute to it. At some point, it sort of picks up by itself.

If you find this topic interesting, you want to ask me a question, or leave a comment, please email me or find me on Mastodon/Fediverse.

You might also like

Here are other blog posts I wrote on the topic of documentation, or in the format of documentation.

• Thoughts on documentation. 2021. Philosophy, strategies and guidelines. Captured thoughts on business documentation that I want to talk about.
• A place for every thing. 2021. Home organisation system documentation.
• How I organize my home directory. 2021-2022. Computer organisation system documentation.
• House cleaning. 2021-2022. Process documentation.
• Posts in my blog category Organization.

Featured image credits

“Göttingen, SUB Library, Lesesaal. Index by Title.”, Public Domain, via Wikimedia Commons.

References

Allen, D. (2015). Getting things done: The art of stress-free productivity (Revised edition). Penguin Books.

Carpenter, S. (2018). Work the system: The simple mechanics of making more and working less.

Grove, A. S. (1995). High output management (2nd Vintage Books ed). Vintage.