Writing a Technical Blog

The post says technical blog ideas often come from moments when you solve a problem, explain something to a coworker, finish a big feature, research something, build something for fun, or take detailed notes on something you just figured out. From there, it suggests choosing whether the post is a guide or a reference.

For a guide, it recommends stating prerequisites, identifying the reader’s skill level, starting from a blank slate, and giving context around code, including file names when the code spans multiple files. For a reference, it suggests outlining headings first, then adding more headings as the explanation grows, because reference posts can become dense. It also says to leave the draft for a day or two, read it out loud, ask someone else for feedback, and revise for repetition and clearer connections between concepts.

Reading notes

#

• Ideas for a technical blog can arise from solving a problem, teaching something to a coworker, finishing a big feature, researching a topic, building something for fun, or recording in detail what you just understood.
• After choosing the idea, the text proposes deciding between a guide and a reference.
• A guide takes the reader step by step and asks the author to define the audience’s level, prior knowledge, and prerequisites right at the start.
• In a guide, the starting point should be zero, and the code needs to come with context, including file names when there are multiple files.
• A reference text explains a concept instead of showing steps, and starts with an outline of headings.
• As the explanation progresses, the author may realize that they need to add headings or turn the idea into a new blog post.
• Since reference texts become dense easily, headings and memes help break up the text.
• During editing, the author recommends leaving the text alone for a day or two, reading everything out loud, and asking another person for feedback.
• In revision, the text can be tightened to cut repetition, rewrite sentences, and make the relationships between the concepts more explicit.
• The closing says that explaining something to another person helps you understand the topic better and that technical blogs help the author and readers learn at the same time.