Writing Technical Blog Posts for Engineers

The difference between a good design doc and a great one is usually clarity. Technical writing should be crisp and to the point. So, it is always better to treat every sentence like it has a cost. After writing, cut aggressively. Remove extra words. Then check if a line can go. Sometimes even a full paragraph is unnecessary. One thing I always do is to start the doc with the conclusion; this way, the reader/reviewer knows where we are heading. This is contrary to how most engineers write docs - listing every approach first and only concluding at the end. That slows readers down. I avoid this because long explanations make people lose track; most readers want the conclusion quickly. So, always start with the answer and why it matters. Then add details and alternatives below for those who want depth. A habit that helps is a quick editing pass like this: - Remove filler words and repeated ideas. - Break long sentences into smaller ones. - Prefer bullets when listing options or steps. - Check if the first section clearly states the outcome. - Add a link or short explanation where a reader may pause. Empathy matters more than most people realize. Try to read your document as someone new to the topic. Ask yourself what might confuse them. Add the missing context. Add the helpful link. Let the ideas evolve naturally from problem to solution. This skill develops over time. Use simple language and fewer buzzwords. The goal is to communicate, not impress. Simple documents get read more. More readers means better alignment and better visibility for the work. Finally, always provide enough context. A short setup about the problem, constraints, and prior decisions goes a long way. It helps readers understand why the decision exists, and, of course, it prevents unnecessary back and forth later. Hope this helps.

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

5 Best Practices for Technical Writing: But, let's first discuss Why Developers Need to Write Online: - As developers, we rely heavily on technical documentation and articles to deepen our understanding and troubleshoot problems. The ability to communicate technical topics effectively is a must-have skill. Yet many developers avoid writing for fear of not being "expert" enough. I'm here to tell you that you don't need to be an expert to start sharing your knowledge. In fact, writing about what you're learning is one of the best ways to solidify concepts. - The key is to be brief, avoid fluff, and structure content logically. Follow these best practices to level up your technical writing skills: 1. Organize content logically and remove fluff 2. Break complex topics into simple, step-by-step explanations 3. Use headings, bullet points, code-blocks, relevant images and white space for easy scanning 4. Use examples and analogies to illustrate concepts 5. Offer multiple learning pathways with cross-references Start small by documenting solutions to problems you've solved. Publish your writing online to help fellow developers and demonstrate your skills. Be respectful of your readers’ time; they’ll love you for it. #technicalwriting #developercommunity #proofofwork #documentation

“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!

A metapost about writing high-quality, technical LinkedIn posts for engineers: 1. Make the first line of your post the most important thing you have to say. I often start writing by asking the question, "So what?" and lead the answer. This is much easier said than done, but it's the most important thing you can spend time on. Remember: people don't read; they scan. 2. Post more about facts and less about feelings. Relevant facts are in short supply, and they're as high-value as it gets. 3. Visualize things you can't easily say with text. Liberally use screenshots of code and charts. 4. Cite your sources. We're nerds. We want to go down rabbit holes. 5. Go out of your way to talk about trade-offs. We know every technical idea has them, so don't make us hunt for them.

Do you ever get frustrated trying to explain complex topics? I help experts solve this problem every day. I ghostwrite for a lot of engineers, and they’re brilliant at their jobs but their work is highly technical, nuanced, and precise. In other words, it doesn’t always translate easily into a short article or post that readers will immediately understand. And if your reader doesn’t understand, they won’t buy (not good). So, whenever I interview them to write content, I ask questions in specific categories to create clarity: 1. Problem: What's the real problem we're solving? 2. Solution: How do you fix the problem? 3. Roadblocks: What gets in the way & how do you handle it? 4. Results: What actually happens when it works? 5. Partner: Why choose us over someone else? My goal with these questions is to strip away the jargon and get to what actually matters to the audience, which is benefits and results. The best part is that these categories are insanely useful for clarifying topics whether you're writing about leadership, engineering, software, finance, or anything. - Lead with the problem they recognize - Explain your solution in their language - Show them why it matters to their world You don't need to dumb it down to make it useful. You just need to translate it. P.S. Have you ever felt frustrated because you couldn’t get your point across?

I have seen software engineer's doing: - Write: about their new system design - Write: how they will be executing projects - Write: roadmap alignment - Write: their achievements and promo stuff To be honest, I’ve seen awesome engineers writing words more than lines of code. Seeing this, I’ve always thrived to get good at writing Initially, I used to read posts and docs written by senior engineers and would mimic their structure. Generally, they used a template like TL;DR, context, etc. I tried using the same approach for all my writings inside Meta. A lot of times, my mentors commented that I was writing more than required. Additionally, I used to spend hours drafting it. Slowly, I realized one key thing that accelerated my speed and helped me get better at writing. It is to 'understand my audience.' This is powerful when writing anything. One needs to understand their audience to deliver any message effectively. For example: 1. For a design doc, if your audience is technical folks, you can talk about layers like caching and internal systems. But if it’s XFN's, just giving simple examples and speaking at a high level helps. 2. Another area is writing your launch posts. You don’t need to include technical details; it can be as simple as stating the problem, the way to solve it, how it impacts, and attaching relevant docs for deep readers to keep it clean. But at the beginning, I used a common template that covered everything. However, I realized that people don’t have time, and writing what the audience needs can make your words worth their time. In the end, it’s no different from the features we ship. We ship products that meet user needs, not what we think is good for them. It’s the same with what we write. Writing is a powerful way to communicate when it’s done the right way.