Jan 23 Document like a Journalist

Documentation is one of the harder problems to solve in software because it seems so inconsequential compared to the code we are writing. And really, who has the time? When you're writing your feature and you're in the zone, do you really want to stop to comment your code?

When you have back-to-back projects scheduled, who has time to stop and update the readme before starting the next project. However, even if it is difficult, documentation provides many benefits to both your user and you, as the developer.

Users are far more likely to choose a product if it provides thorough documentation. Additionally, it's much easier for developers to onboard onto a project if documentation is provided. With this in mind, how can we write documentation and stay on top of our development work?

Journalism is the original documentation. The entire profession is based on taking subjects -- some of which might be very technical -- and distilling them for a large audience to consume. As such, journalism has some tips that we can apply to technical documentation to make the process faster and easier.

Take good notes

Nearly every journalist conducting an interview will take notes. You might think that taking notes isn't as important or useful for a software developer. However, keeping a notepad window open and jotting down what you're trying to do with your code, as well as the results you're seeing, is incredibly useful.

Taking notes as you're coding will help your memory later, should you leave and return to the project. It will also provide valuable context for code comments. Perhaps most helpful, if you plan to provide step-by-step instructions for how to use your product, the documentation can almost write itself from your meticulous notes.

You'll want to write down what you are attempting, and the result you get. If there are any errors, be sure to note them. Lastly, write down the resolution to any errors. This way when you begin writing your documentation guide, you have an idea what errors users might run into, and can provide suggestions on how to solve them.

Now that we have our notes ready, let's start writing.

Don't bury the lede

The lede is the first sentence of an article and contains the most pertinent information. For example, you wouldn't see an article about a new store opening with a first sentence about the store's last quarter sales. That's because the article isn't about the store's last quarter sales, it's about the new store opening.

Similarly, the first sentence of your README should be explaining what your app or library does. Later on, we would describe how the library works, but first the user needs to know what the app does before they can make any decisions about whether or not it meets their needs.

Inverted Pyramid

The inverted pyramid hails from simpler times when journalists would send their stories via telegraph. The technology was notoriously unreliable and information would often be lost. Because of this, the writer would send the most important information first to make sure it was received. If less important information was lost, it wouldn't have the same impact.

The secondary benefit of this was an editor needing to make space in the newspaper could begin cutting from the bottom without concern about losing relevant information.

Let's put this idea toward a user reading your documentation.

Take the most pertinent details and put those toward the top. Does your library require a third-party dependency? Is it only available in a specific package manager? These and other answers can go at the top of your README or wiki, with less pertinent information below.

Write Short

This rule is a boon for those who don't enjoy writing documentation. Because newspapers had (and still have) limited amounts of page space, it was important for reporters to "write short." Today, we face a different problem -- not with real estate, but with attention spans.

Readers often don't finish articles and posts. So when you're thinking about your documentation, think about the absolute necessities users will need to know. There is no need to provide length explanations, particularly not in a README or Getting Started document. Instead of explaining exactly how one of your methods works, you can simply say what it does and link to a more thorough wiki.

Five Ws and an H

There are six questions every article should answer: who, what, when, where, why, and how. Technical documentation isn't complete without answering each of these questions, either. Let's discuss each question in more detail.

Who

There are multiple whos in documentation. There's the person writing it, the person who developed the library or product, the developer who may use the library, or the end user of the product. So whom are we addressing in the documentation?

For documentation purposes, you'll want to focus on the user. This question might be asking, who would use this library? Our answer might be, "a JavaScript developer who wants a simple library for easy array sorting."

What

As you ask yourself how to answer the question of "what" in your documentation, think about what your product is trying to achieve. What problem are you trying to solve? You might include something like, "Sorting arrays is hard and our library makes it easier with three simple functions."

When

Your reader will need to know when the library was written so they'll be able to see if your library is current. Additionally, your reader may ask "when should I use this library?" And perhaps more importantly, "are there scenarios when I shouldn't use this library?"

Are there circumstances when a developer should not use the library? An explanation might look like, "Our simple sorting library only handles four common sorting issues. If you need something more robust, you can check out ."

Where

The question of "where" doesn't necessarily refer to a physical location. Your documentation should tell the reader where they would go to find more information about your library. Are there discussion boards or a Slack channel? Is there a wiki? Your documentation should tell the reader where to find all of this information.

You might say something like, "If the README doesn't answer all of your questions, check out the FAQs. If your question still isn't answered, you can make your way to our discussion board," while providing links for both.

Why

When your reader is asking themselves why to use your library, what they are really asking is why use your library instead of another library. You can answer that by explaining why you wrote the library or product. If there was another library that inspired yours, but was missing some key functionality, you can explain that and answer your reader's question while simultaneously explaining your product further.

How

When your reader is reading your documentation, they will need to know how to interface with your library or how to get started with your app. You should briefly outline the steps in a skimmable way -- remember, write short! Bullet points or numbered steps are the easiest way for your reader to consume the information. This is especially true if they are moving back and forth between the window their app is in and your documentation page. It's easier to find your last place in a bulleted list, rather than re-read an entire paragraph.

However, it's unlikely that your wiki will be as short as your README, and for good reason. Your wiki is the place for more thorough documentation. When you begin documenting individual functions, you'll want to explain how each method works in some detail. You'll also want to explain how to implement each function, so be sure to mention any required and optional parameters.

Bringing it all together

It's common for certain paragraphs of your documentation to overlap on which questions they answer, and that's OK! The most important part of documentation is that it is thorough, and by answering the questions above, you'll come out with helpful and concise documentation.