Plant trees: Writing documentation as a community

This essay, which considers aspects of effectively creating documentation as part of a community (perhaps our own but not necessarily), is the longer, prose version of a slide presentation I also wrote (video).

Introduction

Writing documentation is like planting a forest. It's a long-term endeavor. As the famous quotation observes, the best time to plant a tree was twenty years ago; the second-best time is now.

It's the same with documentation: the best time to write it was when your project started or when the need first arose, but the second-best time is right now. And just like trees, documents are living things that grow and need tending, not something you can plant once and completely forget about.

Does documentation matter?

Looking around the internet, it's all too easy to find projects with hundreds of participants, thousands of users and robust and living code bases whose documentation is thin at best. A sharp-eyed observer who's interested in saving time might argue, based on the existence of such projects, that documentation is not worth doing.

Self-documenting projects

• "Our code is self-documenting."
• "Our software is easy enough to understand for the smart people who are its audience."

For some smaller projects or for projects with a very narrow audience the foregoing claims are indeed persuasive; but the vast majority of projects, and especially those seeking to build an audience outside its core contributors, benefit from good documentation in a way not immediately apparent to the people closest to it.

Needing an explanation of the right way to use software or engage with concepts new to a user isn’t a sign of ignorance. In fact it's an absolutely normal part of daily life and shows curiosity, intelligence and humanity.

When someone makes repeated attempts to understand something new, and fails because they lacked an empathetic introduction to it, they often experience intense negative emotions: frustration, alienation, unworthiness -- and never more so than in the polarizing realm of computers and software.

It's incumbent on all project participants to keep their future users from experiencing this frustration. That doesn't mean it's immmediately obvious to all participants exactly how to bridge this gap, but that's all right. Before getting to any kind of implementation details, it's crucial to make that first leap from elitism to empathy.

Inevitable obsolescence

• "There's no point documenting something that changes so fast."
• "It'll be obsolete halfway through documenting it."
• "Let's wait until the project stabilizes."

Here's one myth that desperately needs busting: products essentially never stabilize to the degree that its participants suddenly declare themselves ready to document what has gone before.

Meanwhile, many documentation processes suffer from huge backlogs and a low priority, so it's very easy to think of including documentation in a product's release cycle as tying a lumbering beast to the legs of a speeding gazelle.

But a healthy documentation process not only can keep up with a project's fast iteration, it's inextricably tied into that iteration. What makes the argument of obsolescence so compelling is simply that documentation processes are all too often unhealthy, because they're being starved of resources at a low priority.

If an organization raises the priority of documentation and expends the resources needed to shrink its backlog, it suddenly becomes much more feasible to insert documentation into its product cycles.

A waste of time and resources

• "Writing documentation takes time away from more important tasks."
• "We have a long list of features that need implementing before we can write nice-to-have documentation."

In fact, documentation is best seen as an essential part of your product’s quality, which provably plummets when users, external or internal, can’t find information about it.

It's easy to imagine the concrete benefits of having up-to-date documentation. Internal users find onboarding and cross-training easier; external users produce fewer questions and support cases.

Getting started

Some projects manage to create a full-fledged first version of their product without writing an iota of documentation. Others are weighed down by out-of-date documentation that becomes harder to update with every passing day and project deadline.

Starting from scratch

Start by diving in and making a list of documents you think you need. Involve subject-matter experts and project participants who have a big-picture understanding of the project.

From that list, farm out the docs to participants who have time to create an initial outline for each document. Once you have a set of outlines, you can begin work on the documents themselves -- one slow step at a time.

Get ready for disappointment

Invariably, unavoidably, 100% of the time, your list and your outlines will be awful. They'll be inaccurate, incomplete and woefully provisional. And this is actually great news, as the next section will illustrate, but it won't feel like it.

If you somehow come out of the list- and outline-making process supremely confident in each proposed document and its outline, and those documents end up all being created exactly as specified, then you are an amazing unicorn with magical powers (and you can skip to Scoping and outlining).

Disappointment is awesome

Mortal humans may, on the other hand, find that as soon as writing begins, the deficiencies of the doc list and their outlines leap into sharp, embarrassing relief. This is actually a great outcome, because in noticing the deficiencies you can act on them.

You have to start somewhere. If you see inaccuracies, great: finding inaccuracy means you now know what's accurate. On the next pass, fix it.

If you find that a list or outline is incomplete, great: fill the gaps that leap out at you with what you now know is missing.

Finally, everything but EVERYTHING is provisional. Documents grow over time. They start as babies. They have to.

Starting by restarting

There is little in this world as daunting as a body of outdated documents that you need to bring up to date. Luckily, this process is actually just one step removed from the "starting from scratch" process touched on above.

All you need to do is hold your nose, dive in and begin dispassionately auditing the documents you've got. One by one, adding to a single list, simply note the existence of each and every document that exists without judgment or worry.

Then, next to each document, mark it as one of three types of document:

• In good shape (likely few of these)
• In need of updating
• Obsolete (to be archived but not deleted)

In working through this process, keep your eyes open to the existence of an invisible fourth document category, and add these to your list as well:

• Documents that need to be written

Now take the documents in need of updating and those that need to be written and, yes, begin outlining them. See the previous section for what to do after that.

Scoping and outlining

All this advice relies heavily on lists and outlining. Being clear on the scope of each document you specify is crucial to making your document lists meaningful and to addressing your audience's needs.

"Scope creep" is also known as "too long, didn't read". If your audience gives up before they get the information they need, your documentation has failed. That's why each document needs to be scoped properly, not too short, which risks a document being regarded as trivial or superficial, and not too long, which can bore a reader and also prevent the creation of a separate, properly scoped document that covers the topic the overlong document inadvertently slipped into.

As mentioned above, outlines are important and yet destined to fail in their original form. The challenge in working with an outline properly is knowing when to stick to an outline that is successfully keeping you on topic, and when you've gained enough to revise an outline that's holding you back.

Your instincts will serve you well here, and even more so a deep awareness of your audience.

Knowing your audience

Writing for the wrong audience presents a different problem from out-of-date docs. Worse than a placeholder, a document written for the wrong audience may read well, but it won't end up serving those who actually need it.

So do whatever you can to gain the best possible understanding of the proper audience for any given document, and think hard about their needs.

Also consider: the doc you really want to write may have an audience of just one: yourself. This is also known as taking notes, which is a worthy pursuit but does not in itself constitute documentation. Nobody wants to read someone else's notes. (But also see "Doing what you love" below.)

Answers you need

For any given document, consider these questions:

• What groups or demographics will read it?
• How will they end up reading it?
  • Can you control the path they'll take to get to it?

• What information do you want to impart?
  • What do readers already need to know? (Once you know, tell them! Point your readers to the resources you consider prerequisite to understanding your document)

• What is your readers’ attention span?
• What's their likely interest level?

Writing for an international audience

As you have probably already considered, you must always fine-tune not only the content but the language of your documents -- but never more so than when your documentation’s audience is likely to contain non-native speakers of your language,

Consider using shorter, declarative sentences. Break up thoughts into multiple sentences or simple, clearly delimited phrases; avoid threading together your longer and more complex ideas with conjunctions and subclauses.

Pay extra attention to readability. Try reading your text aloud. If you stumble over certain complex phrasings, your reader might too.

Avoid using slang, metaphor and niche references, because they're likely to confuse or even alienate non-native speakers. There is a firm middle ground between overly formal language, which we often employ to be as precise as possible, and the overuse of slang and other informal language, which often helps us ground our work and make it more relatable.

Informal but clear and simple language helps all readers connect to your material, not just non-native speakers.

A helpful exercise

A good way to achieve rapport with your intended audience is to imagine you’re sitting with them in person and to read your document aloud. Ask yourself this question as you step through the paragraphs of your document: what questions or concerns do you think they would bring up if they could offer you feedback immediately, in the room you're sitting in now?

This exercise relies on a facility that many people don’t immediately associate with documentation: empathy.

Empathy

Empathizing with your audience is the doc writer’s secret weapon. Once you’ve correctly identified your audience, you can embark on creating a document for them; now you must put yourself in your audience’s shoes and view your document’s topic as they will.

Try to imagine your state of mind before you learned what you need to document -- sometimes this is called "beginner's mind". Review your subject matter in this mindset.

Think of it as mental time travel. You're traveling to the past and reliving the process of learning what you know; but this time around, you have the presence of mind to write down your impressions, observations and things you remember finding surprising or exceptionally interesting when you learned it for the first time.

A vicious circle

In many organizations, even volunteer-driven ones, documentation suffers from a vicious circle of dissatisfaction.

Nobody likes reading the manual

With a new product before us, our first urge is often simply to try it out without looking at the manual, expecting the documentation to be boring and unhelpful. Sometimes it has even been inexpertly translated into a language we understand. It seems much easier simply to dive in and figure it out.

Even those “Quick Start” leaflets we sometimes see with physical products (often the desperate attempts of documentation authors to communicate a bare minimum of info) often get ignored or thrown out.

Our expectations are low, and all too often we see them validated.

Nobody likes writing the manual

Meanwhile, organizations and writers alike dread having to produce documentation. Organizations and community-driven groups alike often consider it a waste of time, de facto an avoidable step that costs valuable time and seems to pay few dividends; writers frequently have too little time (and sometimes too scant an opportunity to consult subject-matter experts) to produce good writing. Writers are also often given little incentive to excel, since they suspect most users will never even read what they write.

As a result the whole thing often ends up being rushed, postponed and/or deprioritized. Thus, users who do end up reading the docs have a harder time using the product, whether it be an appliance or a MediaWiki extension.

Communications between producer and consumer invisibly collapse, and the product’s image suffers.

Solution: a culture of documentation

To break this vicious circle, an organization can do something fairly simple but extremely transformative: allocate more resources for documentation, setting a higher standard.

If you can make that change stick, the quality of documentation can't help but improve. And when it has, shout it from the rooftops. Feature your documentation. Announce your newly launched doc site; integrate it more tightly with your product. Put the improved documentation in front of the user in an attention-getting way that shows your pride in it. Bolster your docs with a good support system that's at least in part powered by the docs themselves. Provide not just a list of docs but a searchable knowledge base integrated with your support system. Implement a feedback system so people can let you know what docs do and don't work. Whatever it takes!

These measures will absolutely amaze the people who come to read your documentation expecting to be bored. Over time, their expectations will rise.

Inside your organization or group, the quality of your docs will inspire those who need your docs in order to complete their tasks; in turn, their expectations for their own work areas will rise. Everyone will see better outcomes when cross-training and onboarding when the docs needed to accomplish them are suddenly well written and vastly more helpful.

External users armed with accurate and usable documentation will likely find your products themselves easier to use, decreasing load on support and increasing the perceived quality of the product itself.

Time

There's no doubt that the more time you spend on preparing, writing and updating documentation, the more its quality and usefulness will grow.

In hierarchical organizations, management typically allocates resources and then jealously guards them. Documentation often has a woefully low priority and comes late in the process.

In volunteer-driven communities, the resources in question are donated by kind participants. Those resources are often torn from the participants' personal calendars. Because resources are often thinner on the ground, documentation is rarer and sometimes relegated to the darkest backlog, considered optional or nice to have.

But regardless of which kind of organization you're in, both participants and (community) managers can make good documentation happen by being judicious about how they handle the precious resource of time.

To make best use of time while trying to prioritize documentation, participants should let their interest guide them and commit as fully as possible to tasks they find interesting, without overcommitting. The key to success here is simply managing to follow through.

Managers, in turn, whether they're part of an organization's management or acting as facilitators for a community project, should concentrate on scoping tasks as precisely and narrowly as possible. In communities, these tasks should simply be announced and pointed at; they can't be assigned per se.

Managers should also devote as much time as is reasonable on reviewing the tasks, looking for progress, problems and inaccuracy of scope. (Nobody is immune to the failings of the provisional outline! See Getting started above.) In this role the key is following up, as much as is possible.

Do what you love

Even a good writer will inevitably produce bad documentation if they dislike the task before them. And a subject-matter expert can't provide useful information if they consider the subject boring or irrelevant.

Although we can't always choose the tasks we're assigned, we can use the resources our organization offers us and ask for help when we need it. The best path to good documentation involves seeing to it that people are given tasks that play to their skills and interests.

People looking down the barrel of a documentation project often envision a terrible slog ahead, which dooms the project from the outset and can easily be avoided. Instead of breaking the tasks up like drawing straws, participants and managers alike should focus a lot of early energy on figuring out who's good at what.

Writing

Not all documentation is technical, but it's technical writers in particular who are often expected to know everything about the topic they're writing about from the very beginning. In fact technical writers, and writers of documentation in general, often know little to nothing about a subject area before diving in.

Their skill lies instead in digesting information and crafting it into a comprehensible form that successfully addresses a given audience. But not everyone on a documentation project needs to be a writer -- which is good, because that is essentially never the case.

Interviewing

Often, someone who is good at outlining also possesses a skill that lies in the very important space between knowing how to do something and being able to write about out: interviewing. A good interviewer knows how to engage the brain of a subject-matter expert and elicit the special information only the expert knows. Then a writer, who may or may not be the same person, can create a document that relies heavily on those interview notes, which are often arrayed across the points of an outline.

Subject-matter experts

Does the technical lead of a project absolutely hate writing documentation, yet there's information trapped in their head that most others don't know? Is there a project participant whose time is so tightly booked that the thought of sitting down to write a document makes them laugh or cry?

In a healthy documentation project, valuable team members like these need only carve out small slices of time, sometimes even asynchronously (by email or in a ticket, perhaps), to supply to an interviewer the information the organization needs documented.

Managers

In a documentation context, managers are people whose skill lies in identifying who's the right person to do which task. It's incumbent on a manager in a documentation project to understand which team members possess each of the foregoing skills, and to make sure each person catches (and completes) tasks that conform to their area of expertise.

Smoothing the way

Participants in a documentation project often find much of the foregoing information about skill-based division of labor as a shock and relief. Knowing more of the nuts and bolts of a functional documentation process can take the pressure off already stressed team members and smooth the way to good collaboration and the willingness to prioritize documentation higher.

Conclusion

This guide uses a lot of words to say a few things that at the end of the day are fairly simple and frankly unsurprising. If you prioritize documentation, shine a light on it and give it the resources it truly requires, it will richly reward your organization in both predictable and not-so-predictable ways. Empathy and genuine interest constitute the rich soil in which your documents, and all your communications, will thrive and grow.