Writing for Developers: Blogs that get read

Writing for Developers: Blogs that get read by Piotr Sarna and Cynthia Dunlop is about, you guessed it, writing for developers. While it is full of practical tips that can apply to any technical writer, the book is focused on writing technical blogs.

This book is packed full of information about writing a technical blog post, including going through the draft process, polishing your post, getting feedback, publishing, and even following up.

To be honest, while I found the book easy to read, I skipped over parts that didn't interest me or were already familiar. It's a good book to keep on hand for reference.

Here are a few notes I took while reading.

What to write and why

• We write to leave our comfort zone, gain a deeper understanding of our code, receive free feedback on our code and solutions, enhance our personal brand, advance our career development, stay current with the latest technical trends, improve our skills, and share our knowledge with others.
• We often don't write because we don't think of ourselves as a writer, we don't have enough time, we don't want to write about something incomplete, we think it's not relevant to others, it's already available in some other form, we don't want to leak confidential details, or we don't think its interesting to anyone else.
• We can write about the cool things we did, a post-mortem, bug hunts, an open source contribution, a fun weekend project, a significant decision you made, an interesting design, vent our frustrations, share some data or numbers, propose using something uniquely, or make or revisit predictions.

Prep

• Prepare for writing by conducting initial research, reading relevant posts, gathering the necessary materials, or conducting further research.
• Think through these questions:
  • Who do you want to read this to?
  • What do they already know about what you're writing about?
  • Why do they care about what you're writing about?
• Determine the goal of the blog post and why your perspective on this topic is interesting. This is your goalpost as you write and edit.
• Create an outline or mindmap.

Writing your draft

• Start with a draft where you dump everything you can think of onto the page. This stage is about getting things out of your head and out of your notes.
• Look for gaps and ensure you've covered everything you intended to.

• Remove what doesn't clearly drive the goal of your post.

• Provide an appropriate level of context for your audience. Remember that not everyone knows what you know.

• The title of the post should intrigue the target reader without misleading them. It should be concise and clearly explain what the reader can expect from the post.
• The introduction of the post should expand upon the title and should entice the reader to read more. It should allow the reader to decide if they want to continue. Include any backstory and reason why this topic is interesting to you.

• The conclusion should summarize and provide any key takeaways. If appropriate, include any subsequent actions for the reader.
• Headings should be used to break up the post into manageable chunks. They make it easy to scan. Less is more.
• If you're including any code, make sure it is shareable, realistic, concise, and actually works.
• Write your post as a conversation between you and the reader. Ask the reader questions during the post to keep them engaged.
• Scan for walls of text and break them up into shorter, easier-to-digest paragraphs. Or, break things out into bulleted lists.
• Links should include text that describes where the user is going. Don't use "here".

Feedback

• Read the "completed" article yourself. Even better, have it read out loud by your browser or favorite LLM. Hearing the words makes a huge difference.
• For more complicated posts, ask for feedback. Treat it like a Code Review. Look for individuals with diverse qualities who can focus on various aspects.

Publishing

• The title should be 50-60 characters for use in search engines.
• Ensure your post has a meta description <meta name="description"... that is added to your head tags for search engines to pick up. This description is often what is used in search results and even social media sharing.
• Your blog post URL should be lowercase and use hyphens, not underscores instead of spaces. The length of the URL makes no difference for SEO.
• Share your post on social media, Hacker News, Reddit, and other communities that are specific to your blog topic.