Source: https://thenewstack.io/writing-for-software-engineers-read-me-first/

Steps to writing

1. Visualise who you are writing for: "What do they know?", "How much do I need to explain?", "What are the unfamiliar terms?"
2. Decide who you are to the reader (level of authority).
3. Decide how much to cover: what ONE thing do I want to say?
4. What kind of writing is this going to be? TIL, tutorial, article, epic? E.g. word budget can help.
5. Do you write in third person (observer) or first (participant)?
6. What tense? Past or present. (Past is easier probably).
7. Write the first draft. "More is more" here as you explore the domain. Refine and edit later. It can be common to discard the first 2-3 paragraphs of the first draft ("throat clearing").
8. Write second draft. This is where you consider the structure of the piece. Take extra care to consider the reader here.
9. Don't have an explicit "conclusion" (definitely don't use it as a subheading). Also avoid phrases like "To sum up..." - boring for the reader. The ending should naturally flow with the rest of the post.

Extras

1. Titles are very important. Try think of a few. This is all a user has to base their decision on whether to read. Ask: "Without context, would I read this?".
2. Search terms in titles are good but remember that quality content is better.
3. Explain what you need to but maybe not more (remember your target audience).
4. Be consistent with acronyms and jargon (introduce shorthand if you're using it).
5. Be precise. Phrases like "in certain situations" should be backed up with evidence or omitted.
6. Use visuals when relevant - don't be tacky.

Common patterns

Note: not required but can sometimes be useful.

Inverted pyramid

Ranks the importance of elements of the article. The structure of the writing can roughly follow this order. First paragraph must be a good hook (think: youtube video titles, catchy and moreish).

1. Most newsworthy info: who, what, when, where, why, how?
2. Important details
3. Other general info / background

Hourglass

1. Inverted pyramid that summarises the key info first.
2. Pivot to transition.
3. A narrative to give the "story" depth and detail (n.b. you are the narrator). This leads to a chronological conclusion.

Focus

1. Lead: exposition. Max 5 paragraphs. Can also be an anecdote or story (then the nut graph needs to transition style, basically what would be a 4th wall break).
2. "Nut graph" (c.f. "in a nutshell"): state the central part of the story and support the lead (demonstrates how the lead illustrates the point).
3. Body: develop the central point in detail.
4. Kicker: bring it to a "natural conclusion" with a memorable remark.

SEO

Content is king.

Today, SEO can be fairly easily categorized as having five major objectives:

• Make content accessible to search engine crawlers. (semantic web?)
• Find the keywords that searchers employ (understand your target audience) and make your site speak their language.
• Build content that users will find useful, valuable, and worthy of sharing. Ensure that they’ll have a good experience on your site to improve the likelihood that you’ll earn links and references.
• Earn votes for your content in the form of editorial links and social media mentions from good sources by building inviting, shareable content and applying classic marketing techniques to the online world.
• Creating web pages that allow users to find what they want extremely quickly, ideally in the blink of an eye. (no SPA).