This article is a continuation from Effective Documentation for Organizations – Part 1.

Introduction

After a lot of toodling, it is finally time to take a look into the major requirements of good documentation in organizations.
^{Finally! Now, what makes documentation good?}

First and foremost I have to say (like any good engineer) “It depends”.
^LAME!

Good documentation heavily depends on the organization, its workflows, culture and many more aspects, but there are core-rules.

Nevertheless, there are some basic requirements for good documentation in organizations.

Requirements to achieve good documentation

Good documentation has clear rules

First and foremost, good documentation has clear rules. That means someone put some thought into the documentation-system, its use and the workflows around it.
^{I don’t want to think. Think for me!}

Without going too much into their details, let’s list the main categories.

1. Good documentation has a clear purpose
2. Good documentation is supported by and supports the workflows around it.
3. Good documentation is easy to work with
4. Good documentation has clear responsibilities
5. Good documentation is stored correctly
6. The people that work with documentation know about the rules.

Good documentation has a clear purpose

Large scale

First, the purpose of your documentation must be clear. That includes the large scale, as in: “What purpose has documentation for your organization?”

• General knowledge management
• Customer on-boarding
• Task management
• (Customer) Relationship management
• etc.
  ^{So many options.}

If you stumble at this step, you should definitely invest time to clarify. Trust me, it will pay off.

Small scale

Then there is the individual document level. Whenever you create a new file, drawing, task, etc. you must first know its intended purpose. Is it just for you or will others see the document? Will the documentation be left as is and never change (dead documentation, e.g. meeting notes) or will it be worked on (living documentation, e.g. project plans)?

PIC that shows living documentation and dead documentation. Perhaps a graveyeard.

In either case, consider the requirements. If the word file you create, must be readable and better yet, understandable by someone else, a customer perhaps, you should consider what information they need and what structure the documentation should have.

Good documentation is supported by the workflows around it

Next, ask yourself how documentation is integrated into the workflows in your organization. A lot a of errors can be traced back to how people are working with documentation in their daily day to day.
^{If paper gets lost or ‘single source of truth’ is merely a dream.}

“Is documentation a natural part of your organization’s workflows?” If the answer is “No” it makes sense to look at those workflows and see how well the tools for task- or knowledge-management are integrated.
^{Jira only brings you so far.}

For example, if a task can be marked as completed before the its results are documented it is no wonder, that no one knows the status of product developments or other kinds of projects.

Good documentation is worked with and therefore part of the general and natural workflows.

Good documentation should be easy to work with

When thinking of workflows it is of course important to keep every step as slim and easy as possible. Therefore, accessing and working on documentation should equally be easy.
^{Don’t just aim for easy! Aim for sexy.}

For many people writing stuff down is a chore.
^{Nobody asked you Stephen King.}

But it doesn’t have to be a great one. Shorthand documentation can be enough in most cases to bring the point across and iteration isn’t one of the many strengths of documentation for nothing.
If also witnessed effective documentation methods based almost entirely on drawings and mind-maps which additionally tend to reduce the resistance to work with documentation.

Always keep in mind, the easier documentation becomes, the better we can work with it and the more often we work with it [Ramayah 2006, Kim 2021].

Don’t go overboard of course. If information in a document can be changed on a whim, you open up a whole other bag of issues.

Good documentation has clear responsibilities

A good and effective technical counter to deal with too easy manipulation of documentation are clear access rights that go hand in hand with responsibilities.

Who can modify what? Not everyone should be able to change the company website for example or play around with its twitter account, right?
Then why are so often customer documents, jira tickets, budget reports and whatnot left to the whim of everyone and their mother in the organization.
^{Interns included.}

It isn’t just a nightmare for IT security, but every documentation system. Clarify who should be able to add, work with and delete what under what circumstances. Your documentation-life will become much easier.

Oh, and keep track of it. Nothing worse than someone leaving and no one who is able to access their files.
^{New map of rights right here.}

Good documentation is stored correctly

Also consider the tool itself. A word file is not the right place for the monthly budget-calculation and slack not the right place for a decision-template.
^{There are better ways to harden your work-day.}

Be aware of the tools you use in light of what you aim to achieve and the requirements attached to it.

People must know about the rules

And finally – ^{actually, not finally but this post has to end at some point} – the people working with documentation must know about its rules. I also call this rule:

“Nothing can be taken for granted in project management.”

^{But what does it mean?}

Let me take a step back to explain.
Everyone has their own unique background. Language is one of the many tools we use to share our thoughts. But just like any tool, there are differences in how we use, or in this case, understand it.
^{When you ask five people for the definition of water, you can count yourself lucky if you get five different answers.}

Words have meaning because of the associations among themselves and with experiences they have. For those around us, friends and family, those differences are infinitesimal small.
^{That’s why they are friends (and family).}

But even within families understandings can be cross through something as small as a sinle word.
^{Tell that to my wife.}

Take a step further (neighbors, acquaintances) and further (people living in the same town or city) and further (…same country) and further (…same continent) and so on and so forth, the differences in association increase dramatically [Anderson 2017].

In today’s interdisciplinary, and on top of that also often international, work environment it is all the more important to clarify because because…

…assumptions kill projects, businesses and people.

And while documentation is a great way to do just that (clarification), the rules on how to work with documentation must also be clear to everyone in the organization. Otherwise hiccups, errors and mistakes are pre-programmed and lead unnecessary additional work and demonization of documentation.

If you have clear rules, they only work if the people who are supposed to follow them, know about them. Make sure that everyone has a chance to learn about the guidelines, lead by example and enforce them, if necessary.
Get out them whips!

If you have clear rules, they only work if the people who are supposed to follow them, know about them. Make sure that everyone has a chance to learn about the guidelines, lead by example and enforce them, if necessary.
^{Get out them whips!}

Outro

As pointed out, the exact guidelines for good documentation depend too heavily on the organization to note them down here. The points above can nevertheless be seen as some general guidelines it doesn’t hurt to follow.

Sources

Key	Citation
Anderson 2017	Anderson, R. C., & Shifrin, Z. (2017). The meaning of words in context. Theoretical issues in reading comprehension, 331-348.
Kim 2021	Kim, S., Yang, J. W., Lim, J., Lee, S., Ihm, J., & Park, J. (2021). The impact of writing on academic performance for medical students. BMC Medical Education, 21(1), 1-8.
Ramayah 2006	Ramayah, T. (2006). Interface characteristics, perceived ease of use and intention to use an online library in Malaysia. Information development, 22(2), 123-133.