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 101 — 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.
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.
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.
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.
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.
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.
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.
Popular lightweight text editors to write code in multiple programming languages across platforms
Common security threats to know before deploying a serious web app
While the blogging scene has developed over the last decade, the benefits of blogging are still plentiful
Top resources for you to learn and find awesome stuff related to React web framework