This weekend I asked Twitter, “What are some of your pet peeves when it comes to technical blog posts?”
What I really wanted to know was, “What’s missing in technical blog posts?” I get asked what information technical blog posts should include and how should posts be structured. As a reader of technical content myself, I sometimes only realize what’s missing once I’m reading it. I wondered if others were able to identify pieces of information that they need in a blog and why. (I received 22 responses; thank you to everyone who shared their thoughts in the thread!)
In this post, I will share seven crucial pieces of information that developers should include in their technical writing based on feedback from Twitter:
1. Text that introduces and contextualizes a code snippet
Text that precedes a code snippet properly orients a reader. Without any context or instructions, a reader may feel like they have missed a step and may not understand how the author arrived at what’s being presented. Without explicit information, readers will wonder the following:
What am I looking at?
Is this a command line or a file?
Am I supposed to type this in somewhere, or is this output from something else?
What’s the expected output/behavior?
I’m seeing an error when I type this. Am I supposed to get an error?
How do we write good code snippets? DigitalOcean’s writing guidelines contain a section called “Commands and Code in Steps” which includes examples of how to format commands and code snippets, and how to introduce them. Redux maintainer Mark Erikson also recommends including the path and file name at the top of a file.
2. Code snippets as text
While some blogs allow authors to preserve the formatting of code blocks, others don’t. Authors circumvent this by pasting code snippets as screenshots, but there’s one problem: screenshots aren’t accessible with screen readers. Not only is the code in the image inaccessible, but authors don’t consistently add alt text to their images.
To make it accessible, host the code snippet elsewhere (a GitHub repo or gist, for example) and add a link to the code snippet in the image caption for quick reference.
3. Alt text to all images, screenshots, and diagrams
Continuing with accessibility, alt text is an HTML attribute where authors can place descriptions on their images. When screen readers find an image on a page, they will read whatever description is provided in the alt text. Without this, a screen reader cannot interpret what the image is.
Earlier this year, I suggested adding code snippets to alt text. But Eric Eggert recommends hosting the code snippet elsewhere and not putting the code snippet in the alt text. Still, do add a basic description of the code snippet in the alt text for screen readers in addition to linking out to the snippet.
4. Final results of the tutorial’s code
What is everything supposed to look like at the end? Software engineer Thalida Noel recommends adding the final results of the code referenced in a tutorial blog post in order to “[see] how all the pieces fit together to determine if this is how I want to implement.”
5. Prerequisites including a list of dependencies and libraries
Prerequisites are a list of things that readers need to know, have, or do before reading your blog post. In a recipe, for example, it would be a list of ingredients and equipment, and maybe some pre-work that needs to be done. In a technical blog post, the prerequisites should list what prior knowledge or experience readers need with a topic and all the dependencies and libraries that need to be installed in order to follow code snippets. (Jacque Schrag says she has seen dependencies references in the body of a blog post, but not in the prerequisites.)
6. Release versions
Most technical tutorials have a shelf life because of software versioning. Including release versions in a blog post help readers find that information more easily; maybe they’re searching for a blog post that uses Ruby 2.2.6 and not Ruby 2.3. Developer Jorge Vergara lists the release versions as metadata at the top of his blog posts.
7. Publish date
A blog post publish date (or “last updated” date) is an important piece of metadata that communicates how current the examples in a blog post are, as @marmalade points out. Without this, readers don’t know if they’re reading something that is outdated (see #6 above). Include the original publish date and, if the post was updated, include the “Last updated” date as well to indicate the information is current.
While not comprehensive, including these seven pieces of information will help you anticipate questions readers may have when they visit your blog post. It will help you become a stronger technical writer.
Looking for more practical guidance around content creation? Purchase The Developer's Guide to Content Creation for content-related tips, exercises, and templates.
Resources: