Technical Blogging, Part 2: Content
One of the biggest headaches that you have to deal with as a technical blogger is not having a clear picture of what you should be doing. You write and rewrite, but find it hard to make it fit together in satisfactory ways.
- Part 1: Overview
- Part 2: Content (this post)
- Part 3: Grammar
- Part 4: Traffic
Your content should be structured around four different functions — tutorials, how-to guides, reference, explanation — each of them requires a distinct mode of writing.
Tutorials
Tutorials are lessons for newcomer to get started learning, through a series of steps to complete a project of some kind, useful for the beginner, easy to follow, meaningful, extremely robust, and kept up-to-date.
- Make sure that your tutorial works
- Ensure the user sees results immediately
- Make your tutorial repeatable
- Focus on concrete steps, not abstract concepts
- Provide the minimum necessary explanation
- Focus only on the steps the user needs to take
How-to guides
How-to guides take the reader through the steps required to solve a real-world problem, they are recipes, directions to achieve a specific end.
You can assume some knowledge and understanding. You can assume that the user already knows how to do basic things and use basic tools.
- Must contain a list of steps to be followed in order
- Must focus on achieving a practical goal
- Must address a specific question or problem
- Don’t explain concepts, link to them if important
- Should allow for slightly different ways of doing the same thing
- Practical usability is more valuable than completeness
- The title should tell the user exactly what it does
Reference
Reference guides have one job only: to describe. They are code-determined, because ultimately that’s what they describe: key classes, functions, APIs, and so they should list things like functions, fields, attributes and methods, and set out how to use them.
Technical reference can contain examples to illustrate usage, but it should not attempt to explain basic concepts, or how to achieve common tasks.
- The only job of technical reference is to describe
- Provide examples to illustrate the description when appropriate.
Explanation
Explanations can equally well be described as discussions; they are discursive in nature. They are a chance for the documentation to relax and step back from the software, taking a wider view, illuminating it from a higher level or even from different perspectives. You might imagine a discussion document being read at leisure, rather than over the code.
Discussions are less easy to create than it might seem, defined by what you think is a reasonable area to try to cover at one time, so the division of topics for discussion can sometimes be a little arbitrary.
- Explanations are the place for background and context
- Discussions can even consider and weigh up contrary opinions
- Don’t instruct, or provide technical reference
Picking the right content type from the beginning is crucial because it will save you from wasting time to wrestle the information you want to impart into a shape that makes sense, because each of these types of post has only one job.
- Tutorials, how-to guides: concerned with describing practical steps
- How-to guides, reference: we need when we are at work, coding
- Reference, explanation: concerned with theoretical knowledge
- Tutorials, explanation: useful when studying than actually working
Once you understand the structure, it becomes a very useful tool for analyzing existing blog, and understanding what needs to be done to improve it.