[Image: #WOCinTech Chat]
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 should be included in technical blog posts based on feedback from developers on 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.
Resources:
- DigitalOcean Technical Writing Guidelines
- ReduxJS docs writing guidelines and issue templates (discussion)
- Alt text decision tree by W3C
- Pocket Technical Writing List
This post originally appeared on my blog
I'm Stephanie, a Content Strategist and Technical PM. Visit developersguidetocontent.com to learn more about my work!
Top comments (10)
Great tips, thanks for sharing! I would add the source to diagrams so people can take it and adjust to their needs.
I did that for my cloud-native web development book and the feedback has been very positive. My recommendation is excalidraw.com. It's fully end-to-end encrypted.
Great recommendation, Mike, thank you!
One thing I find really frustrating is where authors decide to post a snippet but trim out imports or dependencies, which they think are somehow dull. So you end up trying various versions and trying to work out if the error is in your implementation or because it's the wrong artifact.
For instance, in Java unit testing you will find several implementations of "assertThat", "contains" and the like. Plenty of Entity objects, and so on. When I am trying to learn a new skill, I will just avoid blog posts that don't include the imports and which don't link to a github project for the completed example.
And speaking of the linked github repo, don't get me started on Baeldung and the articles with broken examples where you see that the repo has been updated to fix the problems you puzzle over, but the article is left in non-functional condition!
Thanks, Endie! Many people commented on the desire for dependencies and imports in technical blog posts. We should all be sure to include those!
Would you recommend a table of content ?
It depends on the length of the post! For posts that are really long and have nested sections, I would recommend a table of content at the top.
Great tips..thanks.I will try to incorporate these..
You're welcome!
These are some great tips! Thanks for sharing. :)
Thank you for reading it!