Better Living Through Documentation

Published on May 28, 2015

At DataMade, we write a lot of open source software. When it comes to developing software in the open, it isn’t enough to just write code that works; it’s also important for that code to be clear to others.

Effective technical communication involves more than just writing code comments or documentation - the spectrum of communication design also includes tutorials, examples, web interfaces, error messages, issue tracking, Stack Overflow answers, and many others.

There are all sorts of benefits to better communication in tech:

• Greater reach - More people will use your project if it’s easy to use
• Better contributions - If code is well documented, it’s easier for others to contribute improvements back to you
• Your future well being - It’ll be easier for you to work with your own code in a few months. Your future self will thank your current self for being so considerate
• Inclusion - The open source community has high barriers to entry; good documentation is one way to lower those barriers and increase diversity

The following is a summary of tips I gathered from the smart folks at the Write The Docs conference last week (especially Kevin Burke’s talk and Janet Swisher’s talk, which were splendid), along with some thoughts of my own.

These tips are primarily geared towards open-source developers, though some lessons do apply to communication and design in general.

20 tips for better tech communication

1. Avoid giant blocks of text!

If you only remember one thing from this blog post, let it be this: people do not read giant blocks of text. When browsing the web (especially when browsing dense technical content), people don’t read carefully from start to finish.

Instead, people scan.

Break up text to keep paragraphs short (under 4 sentences). Re-work sentences to use fewer words. Turn text into bullet points or numbered lists where possible.

This blog post is a listicle for a reason.

2. Show and hide content dynamically

Don’t treat the web like paper content with a URL; the great thing about the web is that it’s not limited to static text.

Hide non-crucial content by default, and expand content via clicking or hovering. This will make your documentation less verbose, less intimidating, and easier to scan.

3. Avoid the word ‘just’ *

As in, just submit a pull request. ‘Just’ is a very sneaky form of arrogance. Try not to assume that something easy for you will also be easy for someone else.

*unless you are talking about ‘just’ as in justice, in which case, that’s cool

4. Treat error messages as a design problem

Most of programming involves getting error messages and then figuring out how to get past the error message. If you code errors, think of error messages as a user interface (because they are the user interface, for a developer).

• Don’t just say that something went wront - indicate what went wrong. for example, 'XYZ' isn't a valid option is a better error message than Invalid Option.
• Break up a generic error into several, more specific errors with some if/else statements.
• Make sure that the most important content is the most visually prominent (consider order, spacing, capitalization, and symbols).
• Use friendly, natural language instead of robotic machine speak.
• When possible, give the user suggestions for fixing the error.
• Include links to relevant content, such as documentation or a place to report errors/bugs.

Here’s an example of error message improvements in usaddress, one of our open source libraries.

5. Include the exact text of your error messages in your documentation

This will improve your documentation’s Google juice when your user inevitably Googles the error message they just encountered. Other Google juice boosts include ensuring that your HTML meta desc tag and your URLs correspond your content.

6. Provide code examples

A code example is worth a thousand words. Developers love them, and don’t see enough of them.

7. Make sure code examples are okay to copy/paste

Most of the time, people just copy/paste code examples. That means that your code examples should avoid implicit configurations, and include import statements for any libraries used. If your code example is for the command line, don’t include $ or > at the beginning - some people may paste this, and Googling $: command not found does not yield helpful results.

$ pip install -r requirements.txt

pip install -r requirements.txt  

8. Don’t put important content directly before or after a code snippet

User testing shows that people rarely read text directly before or after a code snippet - they just care about the glorious block of code. Either put important content elsewhere, or include it in the code example as a comment.

9. Tell people what kind of code example they are getting

Where should the user copy/paste the code? Into the command prompt? Into a python interpreter? Into a ruby interpreter? Into a text editor?

This consistently trips up beginners I work with, and yet it’s rarely made explicit because experienced developers take this knowledge for granted. I consider this the lowest hanging fruit on the tree of inclusive documentation.

10. Document build instructions

Document how someone can get your project running locally. Include this in the README.md of your GitHub repo, at minimum.

Do you have instructions for cloning from GitHub? Are there configurations to set? Do you have to install anything? If there’s a website involved, how do you start the server and visit it? Does stuff need to be done in a certain order? Are multiple terminal sessions involved?

11. Find a guinea pig to review your build instructions

It’s best if you get a beginner to try them out. Nearly every time I have done this, I’ve been able to identify things that are missing or unclear.

12. Include installation resources where applicable

Beginners are usually unfamiliar with package installation (e.g. pip install, gem install). Include links explaining how to download/use these installation tools, as well as tips like employing sudo when permission errors arise.

13. Include git resources where applicable

Git can be confusing to beginners - include links on installation/usage. Also, make sure a beginner understands that git & GitHub are different things.

14. Create invitations, not roadblocks

Open source projects aren’t perfect or complete, and documentation isn’t only for code that already exists. If there’s work that needs to be done, try to frame it as an invitation.

Sorry, we don’t have this feature yet

Want to help build this feature?

Use your GitHub issue tracker to document work that could be done. Label issues as beginner friendly where possible.

Defining what needs to be done and then extending an explicit invitation is a great way to help new folks get involved.

15. Remember to state what problem you’re solving

If you’re writing about a tool, don’t jump right into covering the classes and methods. A high-level blurb (a sentence or two, even) about the problem being solved should be visible or easy to access from any webpage.

This is often missing from technical documentation, which is unfortunate. Chances are, many people have the problem that you are trying to solve; make it easy for them to recognize how your tool can be useful.

Bonus points for including a high-level overview of design decisions.

16. Put the most important content near the beginning

Make sure that your line-length isn’t too long (45-90 characters is a good guideline). People are likely to miss content on the right side of a page when they scan, so short line-length makes text more legible.

Put important keywords near the beginning of sentences. For example,

do this thing using git

use git to do this thing

17. Turn links into buttons when they are important

Links that lead to the next page of documentation, or to pre-requisites, should be buttons instead of text links. It’s easy for people to miss text links when scanning.

  Quick Start Tutorial

Quick Start Tutorial

18. Make every page a landing page

People are likely to come to your content through social media or through Google, not from any landing page of your choosing. That means that every webpage you control (your project website, project documentation, project code, project blog post, project distribution, etc) should include links to all other relevant pages.

19. Employ GIFs!

GIFs aren’t only for sharing lovable dogs - they’re also powerful for documentation because they can show user actions as well as responses to user action.

GIFs are especially nifty for demonstrating command line usage (javascript for cats is a great example of smart GIF usage). You can also use GIFs to demonstrate a new interface (for example, here’s a GIF of the Geomancer interface).

To make your own GIF from a recording of your desktop, use LICEcap.

20. Actively seek feedback from others

Communication is about understanding what your audience knows, and meeting them where they are.

Remember that you aren’t the one who decides whether your content is clear. You can’t know that your documentation makes sense until someone else reads it and confirms that it makes sense.

---

Inspired by Knight-Mozilla Open News & Write The Docs

Last week, I attended a code convening run by Knight-Mozilla Open News. The event gathered a bunch of developers working on journalism-related projects from all over the country. We all worked on tying up loose ends to release open source projects to a wider community.

I worked on documenting Geomancer, a tool we worked on with the Associated Press to help journalists mash up datasets based on shared geography. Look out for a blog post with Geomancer updates soon!

After the code convening, we attended Write The Docs, a conference about the art and science of documentation. You can watch the talks here.

Have some more practical tech communication tips to share? Leave a comment!