Simple Steps to Better Documentation

By Noah Veltman

(original Apollo 11 flight plan as PDF)

We all recognize what a difference thoughtful, approachable documentation makes when we’re trying to make sense of someone else’s code, but we don’t always heed that lesson when we’re publishing our own. Instead, we slap a hasty pro forma README together and then, what a surprise: our inscrutable library sits there unused, a single tumbleweed rolling past.

Open sourcing your code is great, but it’s even better if people can actually figure out how to use it. With that in mind, last month Cathy Deng and I facilitated a session at SRCCON on how to document our work better.

Good docs help people use your work, but they have other benefits too. They encourage community contributions. They save you from your past self when you’re revisiting your own code six months from now. And they help you think: much like talking to a rubber duck helps you find bugs, carefully documenting your work for users helps you see it from a different perspective and design better code.

In the course of our session, some recurring suggestions emerged:

Give Context Up Front

"Just a few simple steps." (Florian Klauer)

A lot of documentation jumps straight into reference material and skips over the big picture questions a user might have. What does this project do? What does it NOT do? Why did you start it in the first place? Are you still actively working on it? What alternatives are out there? Answer these questions so that someone coming in cold can decide whether this project is what they’re looking for.

Break Things Up

People probably aren’t going to “read” your documentation, which is to say they’re not going to take it to the beach and read it cover-to-cover. They’re going to skim and scan and skip around, searching for what they need to accomplish their task. So don’t write your README like a novel, write it for the skimmers and the scanners. Prioritize the most common use cases. Include a table of contents and a clear structure with section headings so they can get what they need without getting lost.

Avoid Jargon

Some amount of specialized vocabulary is inevitable when we’re talking about software, but that doesn’t mean you have to go full git man page. Unnecessary jargon and acronyms can be pretty alienating, especially to a beginner. Switch to plain language when you can and try to define terms on first use or link out to explanations. And go easy on the marketing-speak: every time you throw in a “just” or “simple” or “easy” it’s an unintentional sneer at the user who’s not finding it quite so easy at that moment.

Think Beyond the README

READMEs, demos, and blog posts are all forms of documentation, but so are things like:

• Error messages

  It’s hard to know where to start debugging undefined is not a function. If your code throws literate, meaningful error messages, it will go a long way toward helping users get unstuck. One SRCCON participant recounted the sheer joy she felt when she once got a detailed error message with a Stack Overflow link inside it.

• Variable names

  If users are trying to trace how your library works or modify it for their purposes, they’ll probably end up reading the source code itself at some point. Keeping your code readable and intelligible is its own form of documentation. Use consistent style. Break up your giant functions into smaller ones. Comment liberally. Use descriptive names for files, functions, and variables.

• Stack Overflow
  

  (XKCD)

  When users can’t figure out how to accomplish a particular task with your library, they might pore over your README for the answer, but more likely they’ll just Google what they’re after and end up on a forum where someone has asked the same question before. It’s pretty amazing when your D3 question leads you to a thread where Mike Bostock himself chimes in with an answer.

Use Complete Examples

Remember that some users are going to copy and paste your examples and use them as a starting point. That means your examples should include inline comments and use meaningful variable names instead of foo / bar placeholder nonsense.

It also means you shouldn’t leave out necessary code that you think is implied. If you skip “obvious” bits and pieces like an import statement, a confused user is going to copy-paste that non-working example and hit an error message right away.

Include Clear Guidelines for Contributors

If you’re hoping to get contributions, lay down the ground rules. How does a developer bootstrap the project to start working on it? What’s the preferred code style? How do you run the tests? What’s the license? What are the biggest areas of need?

Note What's Missing

Easter egg–driven development is not a lot of fun. Try to make your docs as thorough as possible. If there are known bugs, mention them somewhere or open an issue. Keep your docs up-to-date if things change. And if you haven’t been able to document everything, add notes to that effect so a user knows what’s missing.

Write as You Go

Some developers espouse a documentation-first approach, where you start by documenting the API you want and then write the code to make it a reality. If you’re not into that, at least try a documentation-during approach and flesh out your docs in parallel with your code. If you make “write docs” one last checklist item (you’d never do that, right?), there’s a good chance you’ll rush through and end up with something a lot less useful.

One approach is to use an automated documentation generator like Sphinx or JSDoc that creates docs based on your code comments. These tools can encourage good habits and save time, but the SRCCON crowd was split on the results, because they can also lead to very rote output that’s better for robots than humans. Use them with care.

Get an Editor

Have someone else read your docs and give you feedback on what’s clear and what’s not. Better yet, ask someone to try to use your project and keep track of where things get confusing. It’ll be more educational for both of you.

Additional Reading

• Write the Docs—A Beginner’s Guide to Writing Documentation by Eric Holscher
• How to Write Documentation for Users that Don’t Read by Kevin Burke
• Designing a Library That’s Easy to Use by Carl Worth
• Documentation: Not Yet Implemented, But Coming Soon! by Brad Mehlenbacher

Read Full Story from Source https://source.opennews.org/articles/better-docs/
This article by Noah Veltman originally appeared on source.opennews.org on August 26, 2015 at 08:30PM