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:
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.
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.
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.
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
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).
'XYZ' isn't a valid optionis a better error message than
Here’s an example of error message improvements in usaddress, one of our open source libraries.
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.
A code example is worth a thousand words. Developers love them, and don’t see enough of them.
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
> 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
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.
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.
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?
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.
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.
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.
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.
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
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.
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.
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.
To make your own GIF from a recording of your desktop, use LICEcap.
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.
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!
Have some more practical tech communication tips to share? Leave a comment!