Technical writing, Part 2: Content types

Nov 20, 2020 • ☕️ 3 min read

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.


Technical writing — a blog series about what I've learned to build and maintain a successful technical blog


Your content should be structured around four different functions — tutorials, how-to guides, reference, explanation — each of them requires a distinct mode of writing.

overview

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.

More reading

Client-Side Rendering (CSR)

CSR strategy has very good developer experience but the impact on SEO and user experience still concerned

On Expectation of Technical Blogging

Starting a technical blog is easy but maintaining it for a long period of time is a pain in the neck

JavaScript Module Bundlers

Bundling JavaScript and non-JavaScript modules into bundles using Webpack, Rollup, or Browserify

Current State of CSS

These days, front-end mastery involves not only knowing how to write good CSS, but also which of these technologies to use, and when