harisrid Tech News

Writing a design document is just as satisfactory – sometimes, even more – than writing code : a wizened engineer

The Tasks

No matter an engineer’s level, there’s always somewhere we can receive constructive feedback to hone and to refine skills : architecture, coding, soft skills, or writing. In my situation, I’m a senior engineer, and I have hard work cut out for me when it comes to writing good design documents.

Alright, let me be your raconteur and narrate the story.

The Situation

What’s the situation. It’s Q2 of 2025, and I’m fast approaching the project deadline ; I’m in the final stages of delivering the automated feedback loop project. I’m putting in the hard work to effectively solution an ongoing business problem : to immediately export discrepancies after scanning data records for sensitive data elements.

The Tasks

However, I’m tasked with more than just coding. I’m a project lead; that means I’m tasked to write up the design document and present the purpose, the project’s background, and the justifications for critical design decisions.

Now, I do well at detailed communication tailored to engineers – I seldom overlook details. My style stems from my engineering background. I know that engineers love to dig deep technically, ask probing questions, and critically evaluate design choices.

But I received constructive feedback from my senior staff engineer on my first rough drafts. He always excels at highlighting my strengths – he takes positive note of my content’s comprehensiveness. Afterwards, he shifts focus to areas of improvement; he emphasizes conciseness and clarity – writing “to-the-point”. He also recommends incorporating visuals¹ of system diagrams, API request-response calls, and before-and-after UI overlays of records.

I’m to mired in the details; I need to shift the focus solely on the high-level, big-picture, “30-000 foot view” lenses. I also need to communicate to non-technical audiences who have little time – 5 to 10 minutes – to quickly read my documents. Doing so enables the audience to immediately grasp the why of things, without getting bogged down in the what of things or the how of things. Basically, why we solved a business problem.

Yep. It turns out that I needed to refine my technical writing skills and revisit my work.

The Actions

So I’m off to work. I take a series of actions.

To begin, I have to follow a templated functional requirements document ( FRD ); I’m adjusting and aligning my content to match targeted headings – the purpose, the interfaces to external systems, and data requirements. These actions require me to distill my paragraphs – to identify the pertinent and to eliminate the inessentials.

I also have to draw up minimal system diagrams, using tools like draw.io, to convey the appropriate level of context of my systems. I add accompaniments – an acronyms legend, color-coded visuals indicating service ownership, and sequence flows with brief descriptions – to quickly ramp up my target audience on structures and interactions .

The result

My senior staff engineer and engage in several collaborative sessions, and in the end, I develop a concise, easy-to-understand design document. A previously lengthy product 4-5 page document distills into a 2-3 page document ( excluding images ). My design document reads more like a thoughtful professor who crafts an easy-to-understand textbook.

My Learnings

I really enjoyed the process of writing up the design documents – they indicate a solid sense of ownership and understanding of the how, the what, and the why of a business problem I solved. I also appreciate how the documents assist future team members – newcomers can immediately consult the document to quickly answer questions and avoid efforts delving into complex or poorly organized code.

Personally, I value the learning experiences, because of the rarity of actionable writing skills feedback in my profession. We have robust feedback loops for clean coding and clean architecture, but a scarcity for effective writing. Moving forwards, I intend to emulate such practices into the rest of my technical career and any future roles.

1. As the saying goes, “A picture is worth a 1000 words”.¹” ↩︎