How to Write Technical Documentation

In the past 10 years, I’ve reviewed 100s of design docs. Here’s how to write review-ready design docs in 3 simple steps. 1/ Start with a skeleton, write these: • Metadata (Title, authors, status, date, reviewers, approvers) • Context and background • Problem statement • Summary or tl;dr (Optional) • Proposed solution details with tradeoffs and selection rationale  • Other alternatives considered • Failure modes of the proposed solution • Open Questions • References (Optional) 2/ After the skeleton, fill in the content under these headings. -If there are sub-sections, add sub-headings.  -Provide examples and sample calculations. -Use bullet points and lists wherever applicable -Include architectural diagrams, graphs and tables. 3/ If the document is large, put a summary after the problem statement. Start with the skeleton, take it one step at a time, and before you know it, you are done! Remember, a good design doc: -helps understand design decisions and implementation details -helps in identifying potential issues and challenges early  -gives a clear understanding of the architecture -serves as a reference doc during the project While you write and review, make sure your work follows these guidelines. I know writing detailed docs doesn’t come naturally when you’re focused on problem solving. But it’s an essential skill you have to learn to level up. just follow a simple procedure, practice and you’ll get the hang of it. – P.S: Check out additional writing tips in the comments below ↓

Two pharma teams. Two regulatory submissions. Two very different outcomes. Team A: Twelve revision cycles, six months delayed, writers and reviewers teetering on the edge of sanity. Team B: One revision. Done. Submitted on schedule. Everyone is delightfully sane. The difference wasn't writing skill. It was something far more fundamental. The conventional wisdom? Add more reviewers. Create more templates. Add more comments. But here's what working with dozens of pharma teams has taught me: Technical documentation fails when we treat it as a product to fix rather than what it really is—evidence of how we think through complex information. Consider: A development report comes in from your research team. The science is solid, but the document needs "major revisions." Traditional approach: Mark it up, send it back, repeat until acceptable. Result: Weeks or months of back-and-forth, frustrated teams, and delayed submissions. But what if that unclear document isn't just poorly written? What if it's revealing gaps in shared understanding about: - What regulators need to see and why - How data should be presented - Which details matter most The teams that consistently produce strong technical documents don't just write better. They align on understanding before anyone opens a document. They approach writing strategically. They use their problem-solving skills to think through who needs what information and why. They plan how to present complex data for maximum impact. And only then start writing. I saw this work brilliantly with a Phase III clinical team. Before writing began, they got clear on: - Exact regulatory requirements - Key data presentation formats - Critical success factors Result? One revision cycle. Then done. Want to transform your team's technical documentation? Stop treating unclear documents as writing problems to fix. Start seeing them as opportunities to leverage the strategic thinking your team already excels at. Your regulatory submissions—and the patients waiting for them—will thank you.

I’ve struggled with bridging the gap between technical concepts and non-technical stakeholders, but this approach unlocked clarity and action: (And it’s not just about dumbing things down.) → Simplification with Purpose. Here’s how to apply this to communicating technical ideas effectively: 1️⃣ Use Analogies They Understand Technical concepts often feel abstract. Analogies help bridge the gap. For example: "The cloud is like renting a storage unit. You don’t need to own the building or worry about maintaining it, but you can store your things there and access them whenever you need." 2️⃣ Avoid Jargon—Use Everyday Language Too much technical language alienates your audience. Simplify without oversimplifying. "Instead of saying 'We need to refactor the codebase to ensure scalability,' say: 'We’re making sure the software can handle more customers as we grow.'" 3️⃣ Focus on Why It Matters, Not How It Works Stakeholders care about the results, not the technical journey. "We’re implementing this new security feature to make sure your customer data stays protected, which ultimately builds trust and reduces risk." 4️⃣ Use Visuals to Break Things Down Visual aids make complexity easier to handle. A simple flowchart, for instance, can illustrate how a data pipeline works far better than words alone. 5️⃣ Relate it to Their Goals Connect technical efforts to business outcomes. "We’re upgrading the database infrastructure so you can access customer insights faster. This will help improve decision-making and speed up time-to-market for new features." This approach taught me more than any traditional technical communication strategy. Master these techniques, and you’ll become the go-to person who simplifies complexity and inspires action 🚀

Just reviewed your procedures, …and – well – they’re not good… ->they’re either too detailed, turning into a novel, or so vague they leave the reader scratching their head. The secret? Tailoring your procedures to your audience and hitting that "just right" level of detail. Here’s how I try to strike the balance… ->Write for the people executing the procedure. Are they experienced engineers, junior analysts, or cross-functional (HR, Accounting, etc.) teams? Use language and concepts they’ll understand. ->Avoid unnecessary theory or deep background and PLEASE assume a baseline of competence. Outline clear, actionable steps someone ->skilled in the art<- can follow without needing extra guidance. ->Include enough detail to prevent confusion or missteps, but not so much that your procedure becomes heavy to follow or maintain. ->Use concise, active language. Focus on tasks, tools, and outcomes. Every word should add clarity & value to execution. ->Have someone unfamiliar with the procedure try to execute it. If they ask for clarification, refine it. If they finish without questions, you’re close to “goldilocks.” When procedures are done right, they empower your team to act confidently and consistently. Start by writing a procedure to make a peanut butter and jelly sandwich, then have someone follow it and provide feedback. Iterate and improve. #ciso #dpo #MSP #compliance #procedures