Writing Technical Blog Posts for Engineers

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!