I’ve worked in many types of organizations though mostly in public and non-profit, and it seems particularly in smaller organizations, or in organizations where they’re not building products, documentation is not always seen as necessary. I once asked a manager to attend the Write the Docs conference and they didn’t think it was relevant to my job. Granted, writing documentation was not part of my job description, but I didn’t quite understand how they couldn’t see its importance. Documentation is not just about product documentation.
Context and definitions
When talking about documentation, many think of product or software documentation.
At the same time, we think of technical writing as the profession most tied to documentation and that tends to include manuals for hardware and other physical items.
In the context of this post (and how I think about it), documentation is anything written down for the purposes of allowing anyone who reads it to action on whatever is documented.
Technical writer is a title/position and often tied to the profession of technical writing. Since most of the people I encounter that care about documentation aren’t technical writers, I’m going to use the term documentarian instead:
A documentarian is someone who cares about documentation and communication […] regardless of job title.
For the purposes of this post, I’m mostly going to be referring to “internal” documentation as well, namely processes and anything else you might put in a “handbook”, since the purpose is to talk about why that’s important.
Why write everything down?
There are a ton of articles and research on why documentation and writing things down is important. Reasons include but are not limited to:
- consistency
- not relying on memory
- helps prevent high bus factor
- scale: don’t have to repeat the same thing for every person who asks
- saves time (and therefore money)
While I’ve definitely seen a rise in people thinking documentation is important, it’s often limited to more formalized processes/tasks, or product (software, hardware, etc.) documentation.
We can and should go beyond that.
Templates for repeated tasks
Templates are great for any repeated list of actions.
However, I often see them limited to discreet, distinct tasks or requests. Whereas, we can use it for anything that happens repeatedly.
Onboarding
I did quite a few contract jobs after graduation, always filling in for someone though often with specific projects to complete in mind.
One of the biggest hurdles was onboarding.
The worst was trying to get access to things that only a few people had access to. At one place, I asked how to get FTP access to the website and I was told to go talk to a specific person to tell me what the shared login was.
In general though (especially with the rise of remote work), you don’t want new employees guessing where to go for things and to get started with their job. They were hired to do a specific job, not to spend days or weeks getting set up, which would be frustrating for anyone.
If possible, the organization should have onboarding material and tasks for any new hire, and individual teams should have anything that’s specific to their team. There should also be an indication of anything different (or a whole separate template) for a manager.
Temporary information
Sometimes what we write down can be temporary and only relevant for a short period of time, but that process should be well-documented.
A couple of great examples are handover and coverage. In both cases, the information is only relevant for a short time, but both of these happen so often that there should be a well-defined and documented process on how they should happen, who should be involved, and what information needs to be included.
Change management
You can even establish change management into a documented process.
It doesn’t need to be completely prescriptive, but it helps to have guidance on what is considered required, what others might look for, and what to base the decision on.
That’s not to say it’s easy to do. The team I’m in right now is still struggling with how to move proposals forward to action. Nevertheless, the groundwork is there to get the proposal into decent shape, which is the first step.
Allow editing
Editing documentation should be as open as possible. It’s the easiest way to keep it up to date.
Depending on the way you store the documentation, at least allow others to make suggestions with the changes approved and applied by a maintainer.
Some kind of version controlled system is usually best for that sort of thing, but even for Google or Office documents, you can allow comments/suggestions.
Paper version
In many workplaces, it’s not always practical to have access to a digital version of a document. In some situations, it’s critical to have an easy-to-grab or reference paper version.
The one thing I’ll say about paper versions it to make sure the following are printed in the header or footer:
- the date of printing, so that people know if it’s up to date, and
- location of the file, so people know where to find the original, if it needs to be updated.
Have at least 1 documentarian
While a technical writer is great to have (especially for product documentation), anyone with the knowledge and skills can be a documentarian; meaning you might find that documentarian anywhere in your organization, especially information management (and similar) professionals.
It’s great if they have any formal training in organization content and information, but the most important thing is that they care and are willing to help a group of people with documenting things in a meaningful way.
If you’re a manager and you have a direct report ask you to attend an event or conference that will help them become a better documentarian, please consider saying ‘yes’, especially if no one else in the organization is asking.
Take away
Documentation is about writing things down in an easy to follow, organized fashion so that others can find and make use of the information that someone is keeping in their head. Having a documentarian help with that process is important so that the information is usable for others, whether that’s keeping things consistent, or organizing the information.
I’ve only touched on a few points. If you’d like to see an example of documenting “all the things”, you can see the context of where “I come from” with the GitLab handbook.
Thanks for reading! Spot the well hidden potoo:
