Collection
I often get asked for my advice about technical writing and I am always happy to share it. Since I’ve also spoken and written about writing, I thought it made sense to compile a collection of my own material on the subject. Access to some of these documents requires a subscription to O’Reilly, but several are available via free websites.
In this article I explore the craft of writing for engineers. I emphasise that writing is a learnable skill that can be improved through practice, and by using different narrative techniques. Offering insight into writing structures, such as the inverted pyramid and hourglass, I provide guidance on the writing process—from identifying your target audience to drafting, creating and editing compelling text.
In this guide to effective writing for technical professionals, I explain how to convey complex ideas clearly, and make content more inviting to readers. I highlight the importance of understanding your audience and point to useful resources to help improve your writing skills. I also compare writing to coding as a form of problem-solving and recommend looking at other writers’ techniques.
This shortcut explores the world of tech blogging—including motivations, network-building and professional development. I provide guidance on generating article ideas while emphasising the importance of thorough research and regular writing practice, without using AI tools. I outline different publishing options, from personal blogs to prestigious tech publishers, and address practical considerations such as payment, pitching to publishers and working with editors.
During my career I’ve helped hundreds of developers become better writers. By equipping them with better communication skills, I hope to inspire more engineers to get excited about sharing their knowledge. In this talk I explore the parallels between programming and writing. I explain my writing processes, offer tips on how to write well and discuss how to get published.
This shortcut discusses the importance of effective technical writing for engineers, emphasising that writing is a learnable craft, crucial for professional success. I explore the critical role of good documentation in project success, and how poor documentation can hinder progress. I outline key principles for technical writing, such as clarity and consistency, and the importance of feedback and revision.
In this shortcut I explore the challenge of maintaining accurate, up-to-date technical documentation, emphasising the need for clear ownership, strategic automation and regular review processes. Since good documentation requires systematic approaches and ongoing effort, I explain how to creating a culture that values documentation as a key part of the development process, with dedicated documentation owners and automated link-checking reminders.
This shortcut explores the importance of effective technical diagrams—clear, purposeful visual images that bridge the gap between spoken language and precise code. I recommend learning standard notations like UML and the C4 model. And I offer practical tips for creating diagrams that convey critical information in an accessible, consistent way that supports team communication and enhances wider understanding.
