Writing Technical Blog Posts for Engineers

This year, I published Beyond Cracking the Coding Interview and wrote 20+ technical blog posts (nilmamano.com/blog). Here is technical writing advice: 1. Many technical concepts are better explained schematically/visually. So, master a technical drawing tool. Images also act as rest stops where readers can pause and breathe before diving in again (I made 190 drawings for BCtCI, about 1 every 2 pages). 2. Use LLMs to workshop your paragraphs. Paste one paragraph at a time and ask for feedback. Nothing beats *instant feedback* when it comes to improving! I can vouch for ChatGPT Plus. 3. Make sure not to use any LLMisms. No em dashes, no "It's not X, it's Y", no smart quotes. People are paranoid these days, and you'll burn their goodwill instantly. 4. Brevity. It matters at two levels: 4.1. Word economy: fewer words to say the same thing is better. Expressions like "Note that ..." or "It's worth noting that ..." can be removed, and nothing is lost. Same for words like "very", "just", and "really". I think LLMs are good at pointing out if you are verbose--see (2). 4.2. Pacing: people have short attention spans. Each paragraph should introduce something new & move the text forward. There's a communication rule that says "tell them what you're going to tell them, then tell them, and then tell them what you told them." I think this is terrible advice for most technical writing today. 5. Use bullet points/lists. It's easier for the reader to mentally organize the text. 6. If your audience includes SWEs, don't shy away from including code. SWEs use code to ground the content they are reading. 7. Look for analogies. Amortized analysis is just making meals for the whole week on Sunday night. 8. Use memes. If you are writing about "X", google for "memes about X". Your piece will feel more accessible. It's a way of saying "don't worry, I'm not a boring, out-of-touch scholar." 9. Do passes of editing. After you're done and you think every paragraph is good, you should still read it again from top to bottom. Did I miss anything?

“You are not writing enough! Most engineers that have something interesting to say do not aspire to write at all!” ✍️ In this new TLJ episode, I sit down with Piotr Sarna, author of “Writing for Developers” and discuss the common hurdles developers face in writing. He shares how he got started into writing and provides practical tips to get started, including how to use AI for writing. Tune in to discover how cultivating a writing habit can not only boost your personal brand but also improve your technical skills and create new career opportunities. Key topics discussed: ⤷ The Writing Challenge Why many developers who have interesting things to say don’t write and the importance of writing culture in a company. ⤷ Finding Your First Topic How to identify valuable topics from your daily work, even if you think they’re not interesting enough or have already been written about. ⤷ Overcoming Writer’s Block Practical tips to overcome the fear of writing, including dealing with imposter syndrome and language concerns. ⤷ Leveraging AI for Writing How to effectively use AI as a reviewer to find logical fallacies, get feedback, and improve your writing without sacrificing authenticity. ⤷ Proven Blog Post Patterns Learn about effective patterns like the “Bug Hunt” to create engaging and educational content. ⤷ Promoting Your Writing Strategies to get your work in front of a larger audience, from company blogs to social media and content aggregators. ⤷ Beyond Blog Posts Discover how writing can open doors to speaking at conferences and even writing a book. If you feel like you should be writing more, but just don't know where to start, this episode is perfect for you!

I want more engineers to actually get better at writing. So I'm giving you a cheatsheet. Whenever I get stuck on how to elaborate, this is my list of what I could add: Evidence - Stats - relevant data and research findings - Examples - specific instances - Research findings - relevant studies or academic perspectives - Expert quotes - insights from authorities in the field - Case studies - real-world applications in detail - Personal stories - relevant anecdotes that create connection - Testimonials - feedback or experiences from users/customers - Primary sources - original documents or direct accounts Practical - Tips - practical, actionable advice - Steps - processes into sequential instructions - Applications - practical uses or implementations in various contexts - Frameworks - structured models for understanding or applying concepts - Technical breakdowns - complex systems or processes - Checklists - itemized lists for verification or implementation - Resources - tools, references, or materials for further action Analytical - Reasons - justifications for why something matters - Comparisons - different ideas, approaches, or concepts - Definitions - terminology and key concepts in depth - Root causes - underlying factors or origins - Limitations - constraints or boundaries of your main ideas - Counterarguments - opposing viewpoints to strengthen your position - Lessons - insights gained from experience - Mistakes - common errors or pitfalls to avoid - Cost-benefit analysis - advantages against disadvantages Speculative - Predictions - future implications or potential developments - Hypothetical scenarios - "what if" situations to explore possibilities - Future trends - emerging patterns or developments - Best/worst case scenarios - extreme potential outcomes - Thought experiments - theoretical situations to test ideas Contextual Understanding - Historical context - evolution or background of your topic - Cultural perspectives - how different cultures view the topic - Ethical considerations - moral implications or dilemmas - Transformations - how something changes over time - Industry context - the topic within relevant business ecosystems - Geographic factors - how location influences the topic Engagement - Benefits - advantages or positive outcomes - Questions - inquiries that prompt deeper reflection - Metaphors/analogies - familiar concepts to explain complex ideas - Visuals description - detailed word pictures that appeal to the senses - Provocative statements - conventional thinking to grab attention - Interactive elements - reader participation through activities or prompts