Writing User Manuals

5-WHY ROOT CAUSE ANALYSIS (RCA) Problem Statement: A batch of parts was rejected due to an oversized hole diameter. 5-Why Analysis: 1.Why was the batch rejected?→ Because the hole diameter was larger than the specified tolerance. 2.Why was the hole diameter too large?→ Because the drilling machine was not properly adjusted. 3.Why was the machine not properly adjusted?→ Because the operator used an outdated setup sheet. 4.Why did the operator use an outdated setup sheet?→ Because the latest revision was not available at the machine. 5.Why was the latest revision not available at the machine?→ Because there is no system in place to ensure controlled document distribution. Root Cause: No document control system for distributing updated setup sheets. Corrective Actions: •Introduce a document control procedure to issue and display the latest revision only. •Restrict access to outdated setup sheets by removing old versions from machines. •Train machine operators and line leaders on verifying document revision before setup. Preventive Measures: •Digitize all setup sheets with access through a centralized network folder or MES (Manufacturing Execution System). •Implement revision control logs with sign-off for updates and acknowledgments by operators. •Conduct regular audits on setup documents at workstations. •Establish standard work that includes a revision check step before every job setup. •Integrate barcode or QR code scanning to verify correct document versions at machines.

The difference between a good design doc and a great one is usually clarity. Technical writing should be crisp and to the point. So, it is always better to treat every sentence like it has a cost. After writing, cut aggressively. Remove extra words. Then check if a line can go. Sometimes even a full paragraph is unnecessary. One thing I always do is to start the doc with the conclusion; this way, the reader/reviewer knows where we are heading. This is contrary to how most engineers write docs - listing every approach first and only concluding at the end. That slows readers down. I avoid this because long explanations make people lose track; most readers want the conclusion quickly. So, always start with the answer and why it matters. Then add details and alternatives below for those who want depth. A habit that helps is a quick editing pass like this: - Remove filler words and repeated ideas. - Break long sentences into smaller ones. - Prefer bullets when listing options or steps. - Check if the first section clearly states the outcome. - Add a link or short explanation where a reader may pause. Empathy matters more than most people realize. Try to read your document as someone new to the topic. Ask yourself what might confuse them. Add the missing context. Add the helpful link. Let the ideas evolve naturally from problem to solution. This skill develops over time. Use simple language and fewer buzzwords. The goal is to communicate, not impress. Simple documents get read more. More readers means better alignment and better visibility for the work. Finally, always provide enough context. A short setup about the problem, constraints, and prior decisions goes a long way. It helps readers understand why the decision exists, and, of course, it prevents unnecessary back and forth later. Hope this helps.

Users don't suck, but the information provided to them can. If your IFU reads like a legal contract, people won’t read it. Why? Because they’re confusing. Too wordy. Too complex. Too scattered. A great IFU should feel like having a clear-headed expert guiding you step by step. The user needs to know what to do, how to do it, and when to do it. Here's 20 recommendations/writing rules to improve your IFU↴ 1. Write procedures in short, identifiable steps, and in the correct order. 2. Before listing steps, tell the reader how many steps are in the procedure. 3. Limit each step to no more than three logically connected actions. 4. Make instructions for each action clear and definite. 5. Tell the user what to expect from an action. 6. Discuss common use errors and provide information to prevent and correct them. 7. Each step should fit on one page. 8. Avoid referring the user to another place in the manual (no cross-referencing). 9. Use as few words as possible to present an idea or describe an action. 10. Use no more than one clause in a sentence. 11. Write in a natural, conversational way. Avoid overly formal language. 12. Express ideas of similar content in similar form. 13. Users should be able to read instructions aloud easily. Avoid unnecessary parentheses. 14. Use the same term consistently for devices and their parts. 15. Use specific terms instead of vague descriptions. 16. Use active verbs rather than passive voice. 17. Use action verbs instead of nouns formed from verbs. 18. Avoid abbreviations or acronyms unless necessary. Define them when first used and stay consistent. 19. Use lay language instead of technical jargon, especially for medical devices intended for laypersons. 20. Define technical terms the first time they appear and keep definitions simple. Prioritize the user while ensuring MDR/IVDR compliance.

𝗜𝗘𝗖 𝟲𝟮𝟰𝟰𝟯 𝗶𝘀 𝗻𝗼𝘁 𝗷𝘂𝘀𝘁 𝗮 𝘀𝗲𝗿𝗶𝗲𝘀 — 𝗶𝘁’𝘀 𝗮 𝗳𝗮𝗺𝗶𝗹𝘆 𝗼𝗳 𝗱𝗶𝗳𝗳𝗲𝗿𝗲𝗻𝘁 𝗱𝗼𝗰𝘂𝗺𝗲𝗻𝘁 𝘁𝘆𝗽𝗲𝘀. 𝗔𝗻𝗱 𝗲𝗮𝗰𝗵 𝘀𝗲𝗿𝘃𝗲𝘀 𝗮 𝗽𝘂𝗿𝗽𝗼𝘀𝗲. When people say “IEC 62443 compliance,” they often miss an important nuance: not all documents in the series carry the same weight or intent. Understanding the document types helps teams interpret requirements correctly and avoid treating guidance as mandatory controls. 𝗧𝗵𝗲 𝗺𝗮𝗶𝗻 𝗱𝗼𝗰𝘂𝗺𝗲𝗻𝘁 𝘁𝘆𝗽𝗲𝘀 𝗶𝗻 𝗜𝗘𝗖 𝟲𝟮𝟰𝟰𝟯 • IS — International Standard The normative requirements. These define what must be met for compliance or certification. 👉 Example: technical and process requirements • TS — Technical Specification Detailed technical requirements or methods where full consensus may still be evolving. 👉 Often more implementation-focused • TR — Technical Report Informational guidance, background, or explanatory material. 👉 Helps interpretation but is not normative • PAS — Publicly Available Specification Early guidance published quickly to address emerging needs. 👉 May later evolve into TS or IS 𝗪𝗵𝘆 𝘁𝗵𝗶𝘀 𝗺𝗮𝘁𝘁𝗲𝗿𝘀 Many teams mistakenly treat every document as mandatory — which leads to confusion and unnecessary complexity. In reality: 👉 IS defines requirements 👉 TS provides technical depth 👉 TR explains context 👉 PAS captures emerging practices Knowing the difference helps you build a roadmap that is both compliant and practical. #IEC62443 #OTSecurity #IndustrialCybersecurity #ICS #CyberResilience #Standards #SecurityFramework #CriticalInfrastructure

🙈 𝗔𝗿𝗲 𝘆𝗼𝘂 𝗽𝗹𝗮𝘆𝗶𝗻𝗴 𝗵𝗶𝗱𝗲 𝗮𝗻𝗱 𝘀𝗲𝗲𝗸 𝘄𝗶𝘁𝗵𝗼𝘂𝘁 𝗿𝗲𝗮𝗹𝗶𝘀𝗶𝗻𝗴 𝘄𝗶𝘁𝗵 𝗿𝗲𝗴𝘂𝗹𝗮𝘁𝗼𝗿𝘀 𝗱𝘂𝗿𝗶𝗻𝗴 𝘆𝗼𝘂𝗿 𝘁𝗲𝗰𝗵𝗻𝗶𝗰𝗮𝗹 𝗳𝗶𝗹𝗲 𝘀𝘂𝗯𝗺𝗶𝘀𝘀𝗶𝗼𝗻? 😱 Ever submitted your medical device technical documentation without a compliance summary checklist? Including a compliance summary checklist alongside your documentation submission is like handing the assessors a treasure map. X marks the spot and they can swiftly find all the vital information, saving you from the dreaded round of "Where's Waldo" questions! 🗺️ While checklists aren't always mandatory, let's be real – they're a best practice. Your checklist guides the assessors to the information they seek without having to scroll through multiple documents. By doing so, you're not just complying with regulations but also winning the favour of those reviewing your submission. Trust me, they'll appreciate it more! Remember, a smoother submission process not only makes your life easier but also strikes a harmonious chord with the assessors. Happy assessors = impressed assessors! By including that compliance summary checklist, you're showcasing your dedication to clarity and transparency! #MedicalDevices #TechnicalDocumentation #Submission #EUMDR #510k

Typography is not an aesthetic choice. It is an accessibility filter. We obsess over inclusive language, yet we ignore inclusive design. We demand people bring their whole selves to work, then hand them documents their brains cannot process. If your strategy document is written in 10 point Times New Roman, fully justified, on a stark white background. You have statistically locked out a massive portion of your workforce before they read the first word. You are not sharing information. You are creating cognitive friction. Corporate documents often act as a dense, impenetrable canopy. Good typography is the trellis that actually supports the reader. Here are 9 ways to build an inclusive visual trellis for your team. 1/ The Serif Ban → The Rule: Default to sans serif fonts like Arial or Lexend. → The Impact: Removes decorative visual noise that exhausts dyslexic readers. 2/ Strict Left Alignment → Rule: Never use justified text. Always align flush left. → Impact: Creates a consistent visual anchor and prevents distracting rivers of white space. 3/ The Contrast Shift → Rule: Use dark grey text on an off white background instead of pure black on pure white. → Impact: Prevents the strobe effect and reduces sensory fatigue. 4/ The 1.5 Spacing → Rule: Set line spacing to 1.5. → Impact: Breaks up the dense wall of text to prevent accidental line skipping. 5/ The Emphasis Strategy → Rule: Use bold weight for emphasis. Avoid italics and underlines. → Impact: Italics deform letter shapes and underlines cut through descending letters, causing cognitive strain. 6/ The Format Reset → Rule: Always paste as plain text to prevent mixed font styles. → Impact: Stops the ransom note effect that distracts the nervous system. 7/ The Agency Protocol → Rule: Share editable documents instead of locked PDFs whenever possible. → Impact: Allows the user to change the font, size, and background to fit their own visual ecosystem. 8/ CamelCase Hashtags → Rule: Capitalize the first letter of each word in a hashtag. → Impact: Ensures screen reading software can actually pronounce the words correctly (#InclusiveDesign). 9/ Descriptive Hyperlinks → Rule: Write descriptive links instead of just saying click here. → Impact: Provides navigational safety and context before the user leaves the current environment. Typography is policy. If your team has to spend energy decoding your message, they have no energy left to understand it. There are so many more nuances we could add here. What is one typography barrier you wish would permanently disappear from corporate communications?

I've interviewed 50+ senior designers in the last quarter. Two alarming trends emerged: 𝟭. Portfolio paralysis: They can't showcase their best work. 𝟮. Memory fog: They struggle to recall project details from mere months ago. The result? Panic-induced all-nighters piecing together fragmented case studies. 𝗧𝗵𝗲 𝟭𝟬% 𝗦𝗼𝗹𝘂𝘁𝗶𝗼𝗻 👇 Implement this habit now: • Dedicate 10% of your week to documenting your design journey. • That's just 4 hours for a standard work week. • The payoff? Weeks of future stress eliminated. 𝗬𝗼𝘂𝗿 𝗗𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗮𝘁𝗶𝗼𝗻 𝗧𝗼𝗼𝗹𝗸𝗶𝘁: 𝟭. Daily Micro-Journaling (5 minutes) • Capture key decisions • Note stakeholder feedback • Record "aha" moments 𝟮. Weekly Summaries (30 minutes) • Outline sprint accomplishments • Highlight major pivots • Archive key artifacts 𝟯. Project Milestones (1 hour) • Synthesize learnings • Curate a "greatest hits" collection • Record quantitative & qualitative impact 𝗣𝗿𝗼 𝗧𝗶𝗽: Set up a Notion template or FigJam board. Make documentation frictionless. 𝗧𝗵𝗲 𝗖𝗼𝗺𝗽𝗼𝘂𝗻𝗱 𝗘𝗳𝗳𝗲𝗰𝘁 👇 Imagine this: 6 months from now, you have: • 26 concise weekly summaries • 130+ daily entries • A curated showcase of your best work You're not just prepared for job hunting. You're primed for: • Promotions • Speaking engagements • Mentorship opportunities Remember: Your future self will thank you. Your future hiring manager will be impressed. Don't let your best work fade into memory. Document, curate, and shine. ----- I've posted about this issue recently & had some great feedback & conversations. 💬 ----- #design #tech #ux #productdesign #careers

Submission looks tidy. Review finds the gaps 💥 Incomplete technical documentation rarely fails at upload. It fails when the NB starts reading. Missing rationales, broken traceability, or evidence that does not match the claims turns into rounds of findings and months of delay. Build for Annex II and III from day one, then prove every statement with a source. Clear, consistent, and linked beats thick. Practical ways to ship complete tech docs: ↳ Use an NB-style table of contents that mirrors Annex II and III. ↳ Keep a GSPR matrix with direct links to test reports, risk controls, and labeling. ↳ Check claims, IFU, and clinical evaluation say the same thing. ↳ Include partial-standard justifications and state-of-the-art references. ↳ Add PMS and PMCF plans that tie to known risks and open questions. ↳ Run an internal “cold review” by someone who did not write the file and fix every broken link.

Software Architecture Documentation Good architecture is as much about communication as it is about code. A well-documented architecture bridges the gap between vision and implementation, aligning teams and ensuring longevity for your systems. Software architecture docs are the blueprint for understanding, talking about, and changing a system’s design. It helps teams work together better by keeping track of important decisions and details. Good docs make it easier to scale, debug, and improve the system, plus everyone understands what’s going on. Keep your docs short, useful, and organized (like using ADRs, RFCs, etc.). Think of them as code—always updating. Here are a few ways of writing and managing one: 1️⃣ Architecture Decision Records (ADRs) Every choice in architecture has consequences—technical, operational, and cultural. ADRs provide a lightweight, structured way to document why decisions were made, the trade-offs considered, and the context at the time. They’re invaluable for future teams to understand the why behind the how. 2️⃣ Request for Comments (RFCs) Collaboration is key for a sound architecture. RFCs enable open dialogue by inviting feedback on proposed changes before implementation. They create a culture of shared ownership, making the architecture a living, evolving entity rather than a rigid blueprint. 3️⃣ Event Storming When designing complex systems, especially those using event-driven architectures, event storming helps. By focusing on business events, you uncover hidden domain knowledge, identify bottlenecks, and align stakeholders—technical and non-technical alike. 4️⃣ The C4 Model Clarity is king. The C4 model—Context, Containers, Components, and Code—provides a zoom-in/zoom-out approach to documentation that scales with your audience. Whether you’re talking to a developer or a CEO, the C4 model ensures they see what they need to see. To summarize Architecture documentation is significantly more than mere paperwork; it serves as the crucial bedrock upon which resilient, scalable, reliable and maintainable systems are built and sustained. The proper execution of this process will significantly enhance your team’s ability to work at an accelerated pace, all while ensuring the maintenance of high standards and minimizing the potential for errors. What are your go-to techniques for documenting architecture? #SoftwareArchitecture #Documentation #ADRs #RFCs #EventStorming #C4Model

My take: Good docs for humans are good docs for LLMs. We’ve worked with top technical companies like Sentry , Docker, Inc, and OpenAI to adopt LLMs trained on their documentation. And overwhelmingly, I see that what works well for humans, works well for LLMs. Let me prove it to you. Here’s our official guidance for optimizing technical docs for optimal LLM consumption: - Embrace page structure and hierarchy - Segment documentation by sub-products - Include troubleshooting FAQs - Provide self-contained example code snippets (include imports) - Write text descriptions for images - Define specific acronyms and terms We’ve done this for 100+ teams, and it works. But I read that, and all I can think is “Those are also best practices for writing technical docs, period.” Humans want FAQs. They don’t want to guess what an acronym means. And they want well-defined and structured docs. So…if you’re trying to optimize your docs for an LLM, try to optimize for a human. If you follow the best practices, you’ll create docs that both will love to read.