Very often at work, my writing receives praises from fellow engineers, managers, and non-technical folks alike. I wanted to write down a few pointers on my approach as a means of sharing what I know.

Some guiding principles

• Good writing is an exercise in organising your thoughts.
• Good writing is honest, and doesn’t let you escape your blindspots. As such, good writing helps you be more honest with yourself.
• Good writing comes from empathy for your readers. Think about what your reader doesn’t know or understand, and structure your writing in manner that will serve as an explainer to them.
• It’s entirely possible you will end up with more questions than answers after working on your draft. This is the point of writing.
• Writing is iterative. You will never write a perfect first draft. Accept it.

There’s different kinds of writing for engineers. A few common types I run into daily are Jira tickets, design documents, run books for operators on call, quick reference guides, and investigative pieces. Each of these demand a different style.

I tend to structure my documents based on what I want the reader to take away from it. An On Call engineer needs something actionable and needs it quick. Run books should be a series of straightforward steps they can follow even half-asleep, as they often will need to. Investigative or research documents should make the reader ponder and think. Quick reference guides or cheatsheets will be read read over and over again, they should be easy to navigate.

Write with an audience in mind, but call out prerequisite knowledge. It’s infeasible to provide a comprehensive background since the beginning of time. Make assumptions about prior knowledge wherever possible, and mark those assumptions with a small note (and maybe a link to relevant docs for specific details when available).

Provide a background about the problem in sufficient detail, that will help the reader understand why you’re writing the document at all. Do not just say “This document outlines the implementation of XYZ feature” and jump straight into your proposal. Take a moment to write a few lines elaborating the problem your users are struggling with.

Write executive summaries at the very top. Decision makers like your managers often need high level bits first. Only if something feels unclear would they dive into the details that follow. Help your leaders by surfacing the bits that are important to them.

In my writing, I often ask if what I’m writing will make sense to an engineer/manager who might inherit this system a few years down the line, or if we onboarded a new hire who needed to be brought up to speed, will they be able to piece together the historical context?

Good writing comes from good reading. Read more than you write. Read far and wide. It’s good for inspiration and developing your tastes. My writing is a reflection of all I’ve read. Read from a variety of sources, be it blogs or research papers, or documents written by other teams in your company. At work we use Confluence, and it gives me access to reading anything anyone has ever written in the history of my company. This is a tremendous gift!

Fully leverage your tools

Often, a verbose paragraph can be formulated into a table instead. Be familiar with features of your text editor. A lot of features are common across different richtext editors. If you know Markdown, it’s almost universal everywhere (except for Google Docs which is frustrating sometimes)

Formatting is a powerful communication aid

Last year, I had to write a Jira ticket for the docs team for amending a public facing document with updated instructions. I formatted the ticket like a git diff, with red highlight for deletions, and green for additions. Using strikethroughs to signal obsolete information. This isn’t a standard, in fact there’s no guidelines on creating the ticket. I did it entirely because I loved the idea of making a ticket that visually communicates the end result. Creating the ticket took more time than just pasting the updated text would’ve but it probably saved me time in back and forth with the docs team. In fact, the writer assigned to the ticket praised it and said this made it dead simple for them to follow.

GitHub provides powerful tools for enhancing your PR descriptions and READMEs. I often use expandable sections to keep details that are useful but otherwise lengthen the document. People can expand them when they wish to check it. It also has native integration for Mermaid Diagrams which make it very easy to add long-living diagrams to your PRs and docs which are entirely text. Mermaid is picking up a lot recently with the proliferation of LLM assisted tools, and people would be surprised to know it’s not unique to GitHub. Even Grafana allows you to add panels of Mermaid Diagrams, where it can help create handy illustrative references for the flow of data across your stack.

Confluence allows you to create custom anchor links, using which you can point people to relevant sections in your document that aren’t necessarily under a header. I use it often to make it easier for people to jump to different points in the document without scrolling.

Use diagrams

Take the time to generate diagrams to aid your users. If it’s an incident report, it’s extremely helpful to the user if there’s a timeline of events illustrated clearly. You can either use diagrams here or a table could suffice too. But there are areas where nothing beats good visualizations. I once made Sankey diagrams to describe the split of our customers by different factors and it received praise for how well it informed the readers. Taking efforts like these to improve the readability can turn a simple document into an effective persuasion tool for your arguments.

For long lived documents like architecture diagrams, it’s very important to have the diagrams in an editable format. If your platform doesn’t support diagramming tool integrations, having a link to an external canvas where the diagram is maintained is very effective too.

On AI-assisted writing

At this point in time, I would recommend not leaning heavily on LLMs to do your writing for you. LLMs rob you of your unique voice, every piece of writing has the same tone, common tells, and a tremendous uncertainty of hallucinating.

LLMs are seductive, it’s very tempting to accept output that looks well written. It’s becoming more common for people to use LLMs without moderating the output (LinkedIn is filled to the brim with AI slop at this point, and I hate it). They place the burden of making sense of the writing on the reader. This misses the point of writing entirely. Good writing values your reader’s time.

If I notice smells of LLM generated content in a piece, I am immediately distrustful of the writer, and my perception of them changes for the worse. I’d prefer a document with typos and bad grammar over an LLM generated one. A silver lining however is that it’s easier to make your work stand out in a sea of AI-assisted writing.

Having said all that, I’d still recommend trying it out every now and then. The field is rapidly developing. It’d be naive to bury your head in the sand. Keep checking often, maybe it’s improved upon what it sucked at six months ago.

Closing Notes

I still struggle with writing. I follow the above every so often, but because this is all built on feel, intuition, and experience it’s very hard to follow all of it, all the time. I often fight with myself over my use of jargon. The objective of good writing is to simplify, but there’s a fine balance to be struck where you can simplify your writing, and at the same time, raise standards for writing and vocabulary.

I’ve been writing blogs since I was in the 8th grade. I would use it to exercise my writing skills which also fed into my verbal skills over time. The entries I wrote on this blog during my time in college helped me get noticed by recruiters, and some entries have contributed towards promotions, too. I had no idea that writing would have this kind of impact when I was writing those blogs. Even now, my intentions haven’t changed. I still write with the same intent - to share what I know, and to solidify my own understanding.