WTFM

24 min readJul 15, 2015

Writing Effective Documentation

“A goal without a plan is just a wish.” — Antoine de Saint-Exupery

Abstract

Software documentation is not merely a nicety, it is a fundamental requirement of any software project. Ineffective documentation has real and quantifiable costs, measurable as lost time. The effectiveness of documentation can be evaluated by how quickly users are able to complete the tasks for which the software was designed. Given that most readers of the documentation are seeking the means to accomplish a specific task, the most effective format is focused on examples because examples are the most effective instructional tools. Other roles of the documentation (e.g. to provide academic explanations or its use as reference material) is strictly secondary. In the spirit of a Turing test, the examples furnished for a software project should be idiomatic and should demonstrate competency when imitated by an amateur.

Introduction

As a web developer I spend a lot of time writing code, but other than occasional encounters with clients from hell http://clientsfromhell.net/ the hardest thing about my job is sifting through endless documentation — “RTFM’ing” in developer speak (https://xkcd.com/293/) — finding needles in haystacks so I can complete whatever task is at hand. Although the internet has ensured a nearly limitless quantity of it, the quality of documentation remains an uninspired mess. If we had to eat it, we might starve from malnutrition, so we embark on “hunting and gathering” to sustain ourselves.

Despite all the resources available teaching developers how to write code, there are precious few on how to write effective documentation. Whether suffering from the negligence of unskilled writers or from the rush to get a product out the door, the documentation of a coding project is seldom exemplary. How many repositories on Github lack a README file, let alone wiki entries? A painfully large number. For all the “Cathedral and the Bazaar” benefits of open-source code, using it often becomes the digital equivalent of dumpster-diving.

The unacknowledged truth is that code by itself is rarely useful, even if the code is supposedly “good”. Without effective documentation, code is like a virus: it has enough genetic material to infect a host, but not enough genetic information to survive on its own without a life-support system of dedicated users with time to spare. This unfortunate situation is regrettably considered “normal”.

The deficiencies in documentation are understandable when one realizes that the ability to write meaningful instructions are grounded in skills that are completely different from those required to write code. In order to transmit information successfully, documentation needs to be compiled in ways many developers are unfamiliar with — it is a different language with different rules.

Whereas code either runs or it doesn’t, how should documentation be measured? How can it be benchmarked? The discussion usually drifts away from the black and white absolutes of syntax errors and if-statements and into the realm of personal preferences and educational philosophies. In such a touchy-feely atmosphere, it’s understandable that many developers throw up their hands in defeat or simply discredit the importance of documentation.

This article aims to identify the key points to include, pitfalls to avoid, and ways to measure efficacy in the hope that this will improve not only the quality of your documentation, but the quality of your projects as well.

What is Documentation?

It’s important to define the term so we are clear on what exactly what we are talking about. The perfunctory trip to the dictionary would leave us mumbling something about “instructions” or “official information”. Instead we can can cut to a more practical definition whereby developers generally take “documentation” to mean one or more of the following:

- Specifications (white-papers and other technical data)
- Reference Material (class definitions and function signatures)
- Manuals (installation and other bootstrapping instructions)
- Tutorials (how-to’s, guides, etc.)

Therefore:

Documentation: any information that demonstrates the usage of a particular piece of software to a potential user.

Think back to the origins of writing in ancient Sumer where clay envelopes were used wrap small tokens: the writing on the outside of the pouch described in detail what was inside (see the delightful documentary “The Story of 1”), and in the case of writing numbers, the marks in the clay eventually replaced the need for the pouch’s contents altogether. In the case of software, however, we need both the package and its description. The documentation is the information that allows us to make sense of the package’s contents without needing to break it open or take it apart.

We will discuss formatting later, but let’s be clear that documentation need not be written: it can include screenshots, video, or audio clips. Hypertext with links allows the author to combine media in whatever mixture works best.

Why Create Documentation?

First and foremost, effective documentation saves time. It does this by providing clarifications and helping avoid roadblocks. Wasted time can have severe impacts on a project’s budget, on your software’s adoption, and even on a developer’s quality of life. Businesses often measure wasted time in terms of dollars and cents, and that metric can measure the savings earned from investing in effective documentation.

Measuring Documentation’s Efficacy

Unfortunately, an open-source project is unlikely to see its documentation evaluated via such direct benchmarks as its cousins in the for-profit world. However, I posit the idea that all documentation can and should be measured in such terms. Create documentation to save time, and recognize good documentation by how much time it saves. This is similar in concept to performance testing in applications: if you can measure the results of using your software’s documentation, then you will learn what practices are the most effective.

It’s important that any “focus groups” involved in benchmarking be appropriately inexperienced when it comes to your software. Polling your crowd of regular users and asking them to verify the status quo will not yield meaningful results. Human beings have an incredible capacity to make sense of confusing messages, so it is no mark of “correctness” if some users were able to decipher poorly constructed docs. The task of the documentation writer is to be an effective teacher: to guide the new-comers in language they can efficiently understand.

How we Learn

For all the years spent in classrooms, grist to the educational mills, we rarely ask ourselves the all-important question: “How do we ultimately learn?” The simple answer is that the most important currency in our education is that of examples. Every single one of us learns first and foremost by example. Why else would we demand our leaders to lead by them?

Consider the infant child, who begins his mastery of his mother-tongue exposed to no other pedagogical discipline other than an ample supply of examples. How does a lion cub learn to hunt? By observing the example set down by its mother. It is only after internalizing a foundation of examples that refinements and observational connections can be made.

The Imitation Principle

We do not need to bother ourselves with complex criteria for measuring comprehension. In the case of software developers, we need only to validate whether inexperienced developers are able to imitate experienced ones (here we respectfully tip our hats to Alan Turing for establishing this idea). We can infer the success of an imitation by measuring how long it takes: if an “inexperienced” developer and an “expert” developer accomplish the same task in the same amount of time, then for all intents and purposes they are operating at the same skill level and we must concede that the newcomer has learned well. If we wish to distinguish between their skill levels, we must test their efficiency at completing a different task.

Learning Languages via the Pimsleur Method

We can witness the efficacy of this approach when studying foreign languages. While living abroad in Europe and Asia, I recognized that my conversations followed predictable topics (where are you from? where do you work? etc.), and these patterns could be practiced and learned. I realized with some shock that of all the various grammatical books I had stuffed into my luggage, it was the simple phrasebook that was by far the most important.

Ultimately, fluency in a foreign language can be accomplished entirely via a repertoire of phrases: knowledge of grammar and isolated vocabulary can certainly be helpful, but it is not required. This should hardly be surprising given that it matches the patterns used by infants when learning their native language.

To put it another way, effective imitation can be most quickly achieved with a good supply of pertinent examples. This is not a new discovery: the Pimsleur language method is based on it http://www.pimsleur.com/, and studying languages using its courses is the fastest way to gain working fluency. In my personal experience, the Pimsleur courses combined with a Lonely Planet phrasebook (which focuses on phrase patterns with streamlined explanations on how to use them) allowed me to communicate without English in several foreign countries.

Learning an Instrument using the Suzuki Method

An example from the field of music education reinforces this concept and its efficacy. The Japanese violinist Shinichi Suzuki seized upon the idea of teaching children how to play music by focusing on repetition and imitation. He called this method the “mother-tongue approach” because it is modeled after the way children learn their native language. It has proven itself as a very effective teaching method: Suzuki students stand out for their rapid development and lasting musical proficiency.

The implications of recognizing how we learn is that it can influence how we teach. Once we recognize the low-level machinery in our brains that can produce results by imitating the raw material contained in examples, we have a better strategy for how to approach documentation in our software.

Parroting and Trajectory

Admittedly, the rapid, task-driven learning by imitation is not meant to be an all-encompassing education on a topic. However, the top priority in using any software is not theoretical knowledge, it is to accomplish specific tasks. As per the comparison with a Turing test, if a user is able to imitate competency with your software, then by definition that user is competent: you have given them the knowledge they need to accomplish that particular task.

Some software authors are rankled by the thought of documentation being “muddied up” by too many examples, as if the examples should be boxed up and be kept apart from the “real” documentation. This resentment is entirely misplaced: examples ARE the documentation — everything else is secondary. Anyone who has assembled furniture from Ikea can relate to this: parodies aside, their instructional illustrations work.

Any further academic or theoretical learning about the software (or even its adoption in the first place) can only come about after the user has established some forward momentum in the learning process. Just as balancing on a bicycle is easier once it gets rolling, students learning the fundamentals of your software must first establish some basic competency before being saddled with the burden of theories and long-winded explanations behind them.

Being parsimonious with examples is selfish and ultimately counter-productive because it delays comprehension and postpones advanced learning. Without a baseline of relevant examples, users will lack the necessary skills to understand the more advanced concepts, and worse, they will waste time trying to digest the more complex discussions as a poor substitute for the foundational documentation.

Remember that first and foremost, the documentation is not for the authors of the software: it is for the newcomers, and the newcomers will be the primary consumers of it. Therefore the primary goal of the documentation must be always be to establish basic proficiency.

Documentation Driven Development

There has been a push in recent years to stress the importance of documentation. Tom Preston-Werner, the former CEO of Github, made a push for “Readme Driven Development” , but that was only the beginning. June Blender proposed this “documentation first” idea at the 2015 PowerShell Summit. Following in that same vein, I dub this movement “Documentation Driven Development”, or DDD. Thinking first and foremost through the details of how your software will be used will naturally get you thinking in terms of examples and use-cases. It could even lead you to build cleaner interfaces for your functions and classes.

In the same way that test-driven-development (TDD) leads you to define a function’s signature and come up with input variations, DDD forces you to identify clear and useful examples for how to use your functions or classes before you write a line of code. Yes, you might need to adjust your examples during the process of actually writing your code, but having bothered to summarize your functions or methods with an example or two will be invaluable to users and collaborators because it confronts head-on the realities of how your software will actually be used.

Before we outline how to structure your documentation, let’s nip a few trouble spots in the bud.

Tests are Not Documentation

Sorry coders: tests are not effective documentation. Although the input-variations used in a test might have similarities with an example you would present to new users to demonstrate functionality, a test serves a fundamentally different purpose.

For one, unit tests will test many things in mind-numbing variations. Demonstrating too many variations is inefficient at best and is often confusing.

Secondly, tests often use improper inputs to verify that a method fails gracefully (e.g. by throwing an exception). Expecting a regular user to grasp how to properly use a function or method after observing a litany of bogus inputs is a bit like expecting a child to learn Victorian table etiquette in a Turkish prison. The best examples show what to do, not what NOT to do, so tests rarely serve any educational purpose to newcomers.

The most important reason that tests cannot be considered effective documentation, however, is that understanding them requires additional and unrelated knowledge. Does the user need to know what a unit test is in order to use your software? Does the user need to be familiar with a particular testing framework? No? Then as documentation, they cannot be said to be efficient, if they can be counted as “documentation” at all.

Effective examples must seek to simplify as much as possible, and the users of your software should not need to concern themselves with whatever practices you followed while writing its code. Many users won’t even know what a unit test is, let alone how to read one. Even if a user is experienced enough to understand tests, he may not be familiar with the same testing framework, and how would he know which tests he should examine in order to complete a given task?

The only time when tests provide useful examples is when you are addressing the question of how to write tests. If you wish to provide thorough documentation (for other developers only) for how to write tests, then demonstrating or referencing tests is the perfect way to do this.

At the end of the day, you are not meeting your users half way if you are not providing regular examples and documentation. You may as well write your tests in Sanskrit because you are forcing your users to learn unrelated skills and translate your work to get the marginal benefits of the imperfect examples contained in them. Don’t be lazy and don’t leave your user hanging.

Source Code is not Documentation

If you hang around with enough developers, eventually some genius will try to convince you that source code is documentation. In my experience, it is usually the most brilliant minds who make this claim, and that tendency should be a warning to the rest of us. To state the obvious: source code is not documentation. A user should not need to perform a Vulcan mind-meld with your creation in order to understand what it is or how to use it. Imagine if every cellphone user had to be proficient in mobile development or the physics of radio waves.

Remember our goals: good documentation saves time. Expecting unfamiliar users to match your skill level and your familiarity with your own code is delusional and smacks of arrogance. Failing to explain how to use your code may help keep your job secure, but it is not a model worth emulating. Yes, you’re very clever, but what sort of twisted pervert enjoys watching users grovel around in the dark?

I can share a relevant story from my education in music composition. My professor was a no-nonsense Oklahoma farm boy who was forever chawing an unlit cigar and drinking cold instant coffee (black). While a student, he changed his instrument every semester and that’s how he learned how to play (and write for) every instrument in the band. He was a master of melody and orchestration, but he was as likely to regale you with tales of fishing than he was of musical craftsmanship.

One day, a hot-headed prospective student boasted with pride that “my symphony is so difficult that even the Denver Symphony Orchestra cannot play it.” “Well sit down, kid” said my professor, whipping out a chair and putting his chawed cigar butt on the piano, “and we’ll fix that.” The implication was clear: writing playable music is hard and requires craftsmanship. The arrogant student did not enroll. Had his music been playable, he could have been judged by it. Instead of improving his craft and sharing with his peers, he chose to maintain his delusion.

I include that story because I think it touches on a bit of human nature: having your creation judged by others around you can be frightening. Sometimes the comments in forums or bug-trackers are not kind — you need a thick skin. Not everything you write will be a masterpiece. There will be bugs. But writing documentation is the only way to truly share your creation with others and if you fail to do it, you cannot truly be a developer in the same way that this young student failed to be a composer because he failed to create music that was performable.

Automatically Generated Documentation

Another tendency that comes up is having documentation that is automatically generated, e.g. by stripping doc-blocks from the source code and formatting it into web pages.

The primary benefit of using an automated process is for its thoroughness: it will prevent you from forgetting some function or class. After that, its usefulness wanes. The doc-blocks in the code are not the best place to write thorough examples, explanations, and variations on them.

Importantly, if you rely on automatically generated documentation, you block a vital feedback loop: users cannot easily make edits, corrections, or additions to your explanations because they are locked away in the source code. Remember that writing documentation is a separate skill from writing code, so relying on an automated system prevents swaths of writers from contributing; only developers can contribute to documentation that is generated and maintained in this way.

Although the doc-blocks in the source code are useful for making technical notes for other contributors, their target audience cannot be often said to be newcomers. The examples and warnings you might include in your source code as an aid to other developers cannot also represent the best examples and explanations for regular users. You must know your audience for any bit of documentation. Yes, this means more work for you if you want to provide and maintain the most effective documentation.

Writing Documentation

Now that we have covered the importance of clear and relevant examples and a bit about what good documentation is not, let’s go over how to structure your project’s documentation for maximum usefulness.

- Clearly and succinctly state the project’s purpose and audience (e.g. in your README).
- Sketch out your functions and their signatures.
- Sketch out how to use your functions to accomplish the tasks for which you are writing your software.
- Include variations. Stretch yourself to demonstrate different use-cases for your code. If a user asks how to do a particular thing, consider adding an example to your docs.
- Anticipate problems. The best documentation includes tips for what to do when things do not work as expected.

README

Tom Preston-Werner was not joking around: your project really should have a README file and it makes good sense to focus on it first. At the absolute minimum, your README file can communicate to potential users whether or not your code is what they are looking for. When I think of all the man-hours wasted sifting through projects that lack this pittance of information, I think of the burning of the Library of Alexandria and the knowledge that was forever lost. Instead of a massive conflagration, however, productivity in cyberspace is destroyed one omitted README at a time. If you don’t include a README file, then sorry lads, you will burn in developer hell.

At a minimum, create a plain text file with a “.txt” or “.md” extension that contains basics like the following information:

- Name: The name of the project
- Description: A brief description of the project answering “What problem is this project solving?”. Include an outline of the technologies used in the project. e.g. the framework, programming language, database, ORM.
- Authors: The names of the developers on the project.
- Links: Include links to any related projects (e.g.: Is this a Rails API that has corresponding iOS and Android clients?), and links to online tools related to the application (e.g. links to the Github bug-tracker or a link to the Dropbox where all the wireframes are stored).

See http://blog.thefrontiergroup.com.au/2013/05/writing-a-good-readme/ or http://www.wikihow.com/Write-a-Read-Me for more thorough discussions.

After reading it, an unfamiliar user should know what problems your code project solves and whether or not it should be examined further.

Bootstrapping: Installation and the Ilk

In the spirit of Isaac Newton’s exclamation, every bit of software development rests on “the shoulders of giants”. No software exists in a vacuum: if you are writing a plugin, then a user must be familiar with the app it extends, if you are writing an app, then the user must be familiar with the operating system, if a compiler, then the hardware, and so on ad infinitum. The nature of this interconnectedness can make it difficult to know where to draw the line when it comes to providing explanations to your users. The sentiment of “that’s out of scope” or “that’s not my job” will definitely come up, but don’t forget that your users may be encountering the challenges of installing or running code for the first time. You may be their first introduction to the crazy land of giants and piggybacking technologies.

Whether it’s information about how to install or how to run it, your documentation should include enough information for a new user to get started using your code. E.g. for a Rails app, list the perfunctory db:create db:migrate db:seed steps. For a PHP library, list the appropriate Composer commands. For a Golang package, reference the proper “go get” commands. This is a great place to include links to other tutorials that can help a frustrated user get up to speed. Documentation should help reinforce the proper commands and usage, not banish that information to some separate location. Repetition in documentation is good. Being parsimonious with information here is counterproductive, so put out the welcome mat.

If you’re not sure where the sticking points might be when installing or running your code, sit down with a noob and see where they stumble. Although your goal is not to write the definitive guide for how to install arbitrary packages/apps/plugins et al, you must at least provide the steps to get users started. If your software project omits this critical information, frustrated users will find another solution.

Many projects predictably suffer because some authors find it beneath them to impart these small tokens of knowledge. It’s so much more relevant to a new user to learn how to install a package when they have a specific one in mind (i.e. yours) — it’s what educators call a “teachable moment”, and you should take advantage of it. Reading the general instructions on installing Rails apps or Composer libraries may be a bit too abstract for new users. They may not immediately understand the process or its variations and subtleties, so it helps if you provide a relevant example for how to install your code so they can get it up and running as quickly as possible. Users will be especially grateful if you take the time to demonstrate these steps when the generic walk-throughs are unclear or missing examples altogether.

Once you have demonstrated how to get the ball rolling with your software, then you can move on to the main event.

Signatures

Every function or method used by your code should be documented with a proper signature so it’s absolutely clear what it accepts as input and what it returns as output. Some projects (notably WordPress) fails terribly in this regard: it is seldom clear whether a given function returns or prints its output.

Descriptions

These should be as short as possible while explaining exactly what the function or class does. The descriptions may be all that an experienced coder needs to review, but for most users, the description will tell them whether or not they should dig into the examples.

Examples

Examples are the most important building blocks of your documentation. Explanations should reinforce, not replace, examples. Examples are the proofs behind your work: just like in geometry class, your examples provide a written account of the complete thought process used to reach a result. And just like theorems in geometry class, without a complete proof, the theorem cannot be used.

A track meet can be run without a stopwatch: the foremost concern is running the race. Likewise, a coding project can be documented using only examples. The function signatures and descriptions are nice to have, but only the examples are indispensable.

It doesn’t matter how brilliantly worded you think a description is, a working example is infinitely better. Remember why we are documenting in the first place: to save time. Sure, your users could fire up a code editor and play around with each function (and they would learn from that), but why assign them this type of busywork?

Examples are not code: the “Don’t Repeat Yourself” principle does not apply. Your examples should repeat core concepts. Users learn from repetition.

Examples remain the single most effective way of demonstrating what your code does and how it works. A user with a well-stocked “phrasebook” full of examples is able to get around with your code as quickly and easily as possible. Pimsleur and Suzuki would be horrified that some developers consciously weed examples out from their software documentation.

One final example here comes from the field of zoology. There exists the concept of the holotype, or “type specimen”, i.e. the specimen demonstrating the physical evidence for which a new species is named upon. When identifying new species of dinosaur, for example, a representative fossil must be chosen which bears the distinguishing characteristics of that species. Your function and class examples should do something similar: they should embody the most accurate and representative incarnation of each function, as if you were choosing one example above all others.

Simplest Example: Hello World?

For any given function or use-case, it can be useful to reduce the usage down to the simplest possible example. This doesn’t need to be a tired regurgitation of the “foo-bar” variety, but it can be if the functionality is really that inane. Sometimes this simple example is all you need to demonstrate a simple function, but error on the side of having more examples if in doubt. Sometimes it takes some really clever inspiration to come up with a simple and elegant way to demonstrate complex functionality.

Relevant Examples

More users will follow examples when they are relevant. If you are demonstrating return values from an API endpoint, then return real and plausible values — don’t use Unix timestamps if the responses are UTC datetimes. If your function is designed to operate on US phone numbers, don’t use “123” as sample input.

Be especially conscious of proper capitalization — I remember the API documentation of one web host that used capital letters in its documentation examples, but the actual service used lowercase. Little mistakes like that can cost experienced developers a lot of time and lose newcomers entirely.

Again, error on the side of too many examples rather than too few. You are more likely to hear someone say “I’m getting fed up with this orgasm” than you are to hear someone complain of there being too many examples in your documentation (does Seth MacFarlane write documentation?).

Cross-reference

Sometimes the most important thing to include in your function documentation is a link to another related function or class. If you understand what use-cases are similar, then point your users to those other functions. The PHP and Python docs include a “See Also” section where related or alternative functions are listed, whereas some languages (e.g. Ruby and Golang) inexplicably do not — usability suffers.

Maintenance of the Docs

For small projects, it’s hard for the developer(s) to escape the task of writing and maintaining the documentation, but once a project gains some momentum, then it can be vastly helpful to have a writer/educator who is in charge of drafting initial versions of documentation or polishing contributions.

The painful truth here is that sometimes code authors are the worst possible candidates to write the best documentation because more than anyone else, their view of the code is biased. They see the code from the inside out and cannot for the life of them see it through the eyes of a newcomer. If you have code authors writing the documentation, the biggest challenge may be non-technical: you may need to soothe their egos enough to get some real end-user perspective into the documentation.

At the end of the day, you do not want developers being the final gatekeepers of the documentation any more than you would want an educator to be in charge of merging code commits. Give each sphere a reasonable amount of control and independence to excel at their tasks.

Beware projects that are gripped too tightly by their developers: examples are scarce or incomplete and the explanations are too pithy or convoluted to be useful and dammit “the documentation is — sniff — SO PERFECT.” So goes the sentiment when developers consider themselves master educators. Having a feedback loop in place can help prevent this vicious cycle.

Feedback Loop

No matter how good your documentation is, you must provide a way for users to provide feedback. This can be via links where users can make comments or file “bugs” or where they might fork the repo containing the docs.

Github, for example, utilizes a separate repository for a project’s wiki. That’s a great way to ensure that interested users can contribute to your project’s documentation. Tools like ReadMe.io often include link where readers can “suggest edits”. The online PHP manual includes a section of “User Contributed Notes” for each function or class.

How exactly you wish to allow for feedback and how you wish to groom it is up to you, but it is critical that the feedback system is well-functioning. A software project without a feedback mechanism is like a person without functioning kidneys: death or dialysis awaits.

Formatting: the Superiority of Hypertext

Effective formatting should allow users to control the level of detail visible in the same way that they might zoom into or out of a map or photo. Users should be able to skim an outline and “drill down” into any particular topic.

Hypertext is your best friend here: you can easily cross-reference related topics, or you can implement hide/show functionality to help streamline the interactions with your docs.

Dead-tree paper docs are vastly inferior to hypertext when it comes to flexibility and formatting. The ability to jump between topics and drill down into them is something that is done far more efficiently using hypertext, and the ability to quickly navigate those relations is what helps users learn your software more quickly.

Common Errors

What are the most common ways that documentation can go wrong? Here is a short list of mostly self-explanatory time-wasting goofs:

- Grammatical errors
- Poor translations
- Improper assumptions
- Failure to provide proper context
- Failure to anticipate problems
- Failure to provide examples
- Overly succinct or overly explicit
- Failure to link to related material

The most inexcusable errors here are the most easily preventable: just make sure that someone competent in grammar and wording is in charge of preventing any simple mistakes.

We can elaborate on some of the more subtle offenses.

Goldilocks: not too much, not too little

It can be hard to strike the proper balance in your documentation that includes “correct” amount of information — some users may want more, some may want less. Proper formatting is really what allows your users to have their cake and eat it too. Experienced users can get what they need by viewing a collapsed outline, e.g. simple function signatures. Users who are struggling more to make things work drill down into more examples and explanations. How you format this extra information is up to you: it can be a simple scroll down “below the fold” (e.g. on the PHP.net manual), or it can be a show/hide operation (e.g. used by the Golang packages).

Abbreviations

Avoid them. Some languages have a culture of using compact abbreviations (e.g. C or Go), but it can really slow down a user’s comprehension if these compact variable- or function-names are never explained. It may be clear that “int” is an integer and “str” a string, but it’s less obvious that “b” is slice of bytes or that “e” is an error or “r” means “reverse”. We are no longer punchcard-carrying members of the ASCII Preservation Society, so stop being a twad use a descriptive name! In the very least include a note in your descriptions as to what your abbreviations mean.

Improper assumptions: Words to Avoid

If your documentation is fueled primarily by examples, you have fewer pitfalls to worry about, but whenever you veer into prose descriptions, you need to be extra vigilant about making improper assumptions. There are a few trigger words that signal that you are making improper assumptions:

- Obviously
- Simply
- Clearly
- Of course

Any time you use a word or phrase like that, it’s time to reassess what you’re talking about. “Obvious” is the worst possible word to use in documentation — if it were truly obvious you wouldn’t need to document it, so don’t be a jerk and boast that this obscure esoteric thing is obvious to you. It’s virtually guaranteed that the unwitting public will not share your opinion.

Another area where improper assumptions can flare up is in assuming your users are either less or more intelligent than they really are. Proper formatting and hyperlinks can save you here too: keep your pages geared towards your average users, and if someone needs more explanations, you can link to extra material (e.g. tutorials). If they need fewer explanations, they can skim the material or peruse the outlines.

Having a proper feedback process for your docs will help keep these issues in check.

Failure to Anticipate Problems

This is one area where you separate the amateur documenters from the pros. If you are keeping your hand on the pulse of your project, you will know what questions your users have and what trouble they have encountered, and you can weave that information into your docs. Your users will be very grateful if you provide them with solutions to problems that they did not anticipate.

Conclusion

Writing effective documentation is challenging, but it is a necessary part of any serious coding project. The most important component of your documentation will be its examples: they are the most effective way to demonstrate how your code works. The effectiveness of documentation can be measured, and you should strive to produce documentation that saves the most time by giving users what they need to see. Documentation Driven Development (DDD) urges you to draft your documentation before you write any code: doing so will force you to design and re-evaluate your interfaces and confront the realities of using your code from the user’s perspective. Make sure you provide an adequate feedback mechanism in your docs so users can make suggestions or corrections. Listen to what newcomers are telling you, and your docs can become a boon to your coding project instead of a barrier to entry.