Best Practices For Engineering Documentation

Stop making technical documentation harder than it needs to be. It’s not just a stack of papers. It’s a system. Everything connects—or at least it should. Here’s how I streamline it↴ 5 tips for killer Technical Documentation (TD): 1. Stick to the intended purpose Misaligned docs with ≠ intended purpose = misaligned objectives = potential non-conformities. One "intended purpose statement" solves this. 2. Think ecosystem, not silos. Device description, GSPR, PMS, clinical evaluation, risk management, etc...—they’re puzzle pieces, not solo acts. 3. Use the 3C formula. Clarity: Write for reviewers, not for yoursel. Consistency: Double-check every links. Connectivity: Show how the puzzle fits. 4. Work backward from compliance. Start with GSPR. It’s the glue for your whole TD. 5.Keep it alive. TD isn’t one-and-done. Update it. Reflect your device’s latest state, especially post-market changes. Here is my go-to roadmap: → Start with GSPR: Map compliance first. The rest falls into place. → Structure for the NB: Follow MDR annex rules. Speak their language. → Summarize smartly: Highlight safety, performance, and quality. Synthesize, don’t just summarize each report. → Triple-check: No room for sloppiness. Fresh eyes help (external review FTW). → Update relentlessly: PMS? PMCF? Risk reviews? TD should reflect it all. Pro tip: Treat TD like project management. You need cross-team input, traceability, and killer attention to detail. Need more ? Use our templates: → GSPR, which gives you a predefined list of standards, documents and methods. ( https://lnkd.in/eE2i43v7 ) → Technical Documentation, which gives you a solid structure and concrete examples for your writing. ( https://lnkd.in/eNcS4aMG )

Accessibility tip that should be the standard anyway: Send documents in advance for review before asking people to respond to them. Don't share documents participants haven't seen before during a meeting and then ask for feedback in that same meeting. Also, provide a reasonable timeframe for review. Emailing documents a few hours before a meeting is still not enough time. Why? 1. Some people need more time to process information and develop thoughts. Those who are neurodivergent or have cognitive disabilities can be part of this group. 2. People are busy and might have competing priorities, and providing more time for review will support them. 3. When documents are reviewed in a live meeting, this is often an environment with background noise and bright lighting. It might be difficult for participants to focus on the documents or read them for understanding when there are people speaking in the background or someone is presenting. This is not an ideal environment to process, understand, and respond to new information. 4. More privileged voices can dominate non-inclusive situations like this and you can lose valuable feedback and insights from others. Has this happened to you before? Do you follow this best practice? #DisabilityInclusion #Accessibility #Meetings

Many thought leaders emphasize driving transformations through the lens of people, which I wholeheartedly agree with. People remain the heart of how an organization operates. How do we achieve this? One often overlooked aspect is high-quality procedure documentation.   Procedures are detailed instructions for completing tasks. They are crucial because they: - Improve productivity by eliminating the need to decipher unclear documentation - Break down silos, enhancing team collaboration - Facilitate scalability and growth by simplifying onboarding of new employees - Are the key to consistent and great customer experiences - Manage risks and ensure regulatory compliance - Foster problem-solving and continuous improvement   I’ve seen many organizations struggle with maintaining quality procedure documentation. In one of my consulting projects, we cleaned up a disorganized repository that was a massive pain point for the company.   What’s the key to success? Defining a consistent structure aligned with the business context. The best practice is to organize procedure documentation according to your complete inventory of processes using the Process Inventory framework. This approach offers several benefits: - Scope Definition: Clearly defined boundaries ensure no overlaps in documentation. - Ownership: Assigning a Process Owner for each process ensures accountability for creating and maintaining high-quality documentation. - Employee Alignment: Provides clarity on which employees execute processes, making it easier to close knowledge gaps. - Risk Management Alignment: Helps the risk organization verify that procedures provide the right risk and compliance controls.   This is only possible if an organization inventories every process they perform through the Process Inventory framework. To learn more about this framework, check out my book 'Digital Transformation Success' https://a.co/d/bmYf0oG   #Transformation #PeopleFirst. #ProcessInventory #BusinessScalability #ContinuousImprovement

I reviewed a Technical Specification today. It made me reflect on a few important points. Effectively drafting technical specifications is not about writing more — it’s about writing better. Too often I see specifications become a dumping ground for generic clauses, copied standards, disclaimers and risk transfer masquerading as “technical requirements”. The result? Ambiguity, ultimately disputes, and delivery teams forced to interpret intent long after decisions should have been clear. The UK Construction Playbook (and similar guidance we see echoed across Australia) keeps coming back to a few fundamentals that are worth repeating: 👉 Clarity of outcome before prescription Specifications should not be drafted in isolation to the intended contract. They should be explicit about what is required — performance, durability, safety, whole-life outcomes — before defaulting to overly prescriptive solutions or resorting to death by referencing too many industry standards. 👉 Align the Spec with the commercial model If you’re pursuing early contractor involvement, two-stage procurement, or modular delivery, your technical specifications must support collaboration — not lock in assumptions too early. 👉 Standardise where possible, tailor where it matters Standard forms and reference specs reduce friction, but only if they are actively curated. Blind cut & paste copying introduces risk, not certainty. 👉 Design for buildability and operation The Playbook (see image below) is clear: for good specifications consider what to avoid when drafting. 👉 Write for the people who will actually read and them A specification is a communication tool. If the contractor, subcontractor, or facilities team can’t easily understand it, the project will pay for that later. Ultimately, effective technical specifications are a management tool. They set tone, allocate risk intelligently, and enable better decision-making across the lifecycle of an asset. Less boilerplate. More intent. Better outcomes. #Construction #TechnicalSpecifications #ConstructionPlaybook #Procurement #Infrastructure #BetterProjects

Happy Global Accessibility Awareness Day everyone! It's a great day to remind people, that, accessibility is the responsibility of the whole team, including designers! A couple of things designers can do: - Use sufficient color contrast (text + UI elements) and don’t rely on color alone to convey meaning. - Ensure readable typography: support text resizing, avoid hard-to-read styles, maintain hierarchy. - Make links and buttons clear and distinguishable (label, size, states). - Design accessible forms: clear labels, error help, no duplicate input, document states. - Support keyboard navigation: tab order, skip links, focus indicators, keyboard interaction. - Structure content with headings and landmarks: use proper H1–Hn, semantic order, regions. - Provide text alternatives for images, icons, audio, and video. - Avoid motion triggers: respect reduced motion settings, allow pause on auto-play. - Design with flexibility: support orientation change, allow text selection, avoid fixed-height elements. - Document accessibly and communicate: annotate designs, collaborate with devs, QA, and content teams. Need to learn more? I got a couple of resources on my blog: - A Designer’s Guide to Documenting Accessibility & User Interactions: https://lnkd.in/eUh8Jvvn - How to check and document design accessibility in your mockups: a conference on how to use Figma plugins and annotation kits to shift accessibility left https://lnkd.in/eu8YuWyF - Accessibility for designer: where do I start? Articles, resources, checklists, tools, plugins, and books to design accessible products https://lnkd.in/ejeC_QpH - Neurodiversity and UX: Essential Resources for Cognitive Accessibility, Guidelines to understand and design for Dyslexia, Dyscalculia, Autism and ADHD https://lnkd.in/efXaRwgF - Color accessibility: tools and resources to help you design inclusive products https://lnkd.in/dRrwFJ5 #Accessibility #ShiftLeft #GAAD

Safety Innovation Advent: Day 18 - Assess the readability and accessibility of your safety documents. In the lead-up to Christmas, I’m sharing an insight, activity, or practical tip each day to help you innovate in health and safety. Today’s tip: Use readability and accessibility tools to improve your safety documents. Clear and accessible communication is foundational for ensuring that your safety documents are effective for everyone. Today’s challenge is to use tools in Microsoft Word to assess both the readability and accessibility of a document, and identify ways to make it clearer and more inclusive. Try this... Step 1: Assess readability 1️⃣ Open your document in Microsoft Word 2️⃣ Enable readability statistics Go to File > Options > Proofing. Check Show readability statistics under “When correcting spelling and grammar.” Click OK. 3️⃣ Run a spelling and grammar check Go to the Review tab and select Check Document. Once the check is complete, the readability statistics will appear. 4️⃣ Review key readability metrics Flesch Reading Ease: Scores range from 0–100. Higher scores mean the text is easier to read. Aim for 60–70 for general audiences. Flesch-Kincaid Grade Level: Indicates the U.S. school grade level needed to understand the text. Aim for Grade 8 or below to ensure accessibility for a broad audience. Step 2: Check accessibility 1️⃣ Run the Accessibility Checker Go to the Review tab and click Check Accessibility. 2️⃣ Review key accessibility metrics Colour and contrast: Ensure text and background colours are distinguishable for users with low vision or colour blindness. Alternative text for images: Check that all media, charts, and illustrations have descriptive alt text. Table structure: Confirm that tables are simple, logical, and include headings where needed. Font size and style: Ensure text is legible and uses a sans-serif font where possible. 3️⃣ Address accessibility warnings and recommendations Microsoft Word will highlight areas to improve, such as missing alt text or insufficient contrast. Follow the prompts to make adjustments.... You're welcome. Why this matters for health and safety innovation: Safety management system documents need to be clear, readable, and accessible to all workers, including those with disabilities. By improving readability and addressing accessibility issues, you can ensure your documents are inclusive, easy to use, and more effective at communicating critical information. 🔧 Pro Tip: For a deeper review, consider using additional tools like Hemingway Editor (for readability) or WebAIM Contrast Checker (for colour contrast). PS: Is anyone even reading these tips? If you got this far please like or comment so I know I'm not entertaining a bunch of LinkedIn bots 🤖 🤖 18 down! 6 to go - any requests? Stay tuned for more practical tips in this series by following my profile and the hashtags #SafetyInnovationAdvent #SafetyInnovation #SafetyTech.

If we want more companies and clients to adopt BIM practices, we need to stop producing 70+ page BIM Execution Plans (BEPs)! These are longer than the Standards themselves! BIM is supposed to streamline and enhance project delivery, not bog it down with unnecessary complexity. Yet, we see BEPs that are dense, overwhelming, and, frankly, counterproductive. Simplicity is key. We can drive wider BIM adoption by focusing on clear, concise, and actionable BEPs. By cutting out the jargon and focusing on what truly matters, we make it easier for teams to implement BIM effectively. For example, instead of saying: "All task teams are required to adhere to the clash detection processes outlined in this document, using the designated software tools to identify and resolve any spatial conflicts before progressing to the next project stage." Say: "Teams must follow the clash detection process and fix issues before moving forward." Original: "The Common Data Environment (CDE) shall serve as the central repository for all project documentation, where all files shall be named and structured in accordance with the project’s agreed naming conventions and protocols." Simplified: "The CDE will store all project files, following our naming rules." Let’s be honest, some of these complex sentences sound like they’re justifying their own existence (or the expertise of the person who wrote them) rather than helping the team. The real value lies in clarity, not in making things sound more complicated than they need to be. The goal: A BEP that’s understood by everyone, from the top-level executives to the on-site teams. No more documents that only the most seasoned BIM managers can decode! Simplify your BEPs and watch how quickly clients and companies embrace BIM. #BIM #Construction #ProjectManagement #Innovation #DigitalConstruction

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

Technical writers often struggle with the documentation process. But I don't... Here's why: I don't use neglected, out-of-sync docs. There's no need to treat documentation as an afterthought, losing countless hours to outdated information and miscommunication. Now, we're using Docs as Code—a trend that has changed how technical writers, developers, and stakeholders collaborate on documentation. Docs as Code means treating your documentation with the same respect and processes as your code. Same tools, same processes, same love and attention. By doing this, you integrate documentation into the development process, making it a native. As a result, you get to: → Use Git-based version control for your docs → Deploy updated documentation automatically → Allow your entire team to contribute effortlessly → Reduce tickets caused by outdated documentation → Implement review processes for documentation changes → Ensure users always have access to up-to-date information → Eliminate conflicting information across different doc versions → Track changes, manage branches, and resolve conflicts → Set up continuous integration to test for broken links → Maintain a single source of truth that you can trust → Automate doc generation from code comments → Keep your docs in lockstep with your codebase And the implementation isn't rocket science as well—it's more straightforward than you might think. Never treat your documentation like an afterthought—it's an integral part of your product. By treating docs like code, you'll: > 𝐒𝐥𝐚𝐬𝐡 𝐭𝐢𝐦𝐞-𝐭𝐨-𝐦𝐚𝐫𝐤𝐞𝐭 𝐛𝐲 𝐮𝐩 𝐭𝐨 50% > 𝐁𝐨𝐨𝐬𝐭 𝐩𝐫𝐨𝐝𝐮𝐜𝐭 𝐪𝐮𝐚𝐥𝐢𝐭𝐲 𝐚𝐧𝐝 𝐫𝐞𝐝𝐮𝐜𝐞 𝐞𝐫𝐫𝐨𝐫𝐬 𝐛𝐲 30% > 𝐒𝐤𝐲𝐫𝐨𝐜𝐤𝐞𝐭 𝐮𝐬𝐞𝐫 𝐬𝐚𝐭𝐢𝐬𝐟𝐚𝐜𝐭𝐢𝐨𝐧, 𝐛𝐨𝐨𝐬𝐭𝐢𝐧𝐠 𝐜𝐮𝐬𝐭𝐨𝐦𝐞𝐫 𝐫𝐞𝐭𝐞𝐧𝐭𝐢𝐨𝐧 𝐛𝐲 25% Stop losing money on inefficient documentation processes and start delivering value faster. Share your thoughts or experiences with Docs as Code in the comments. Have you implemented this approach?

𝐈𝐒𝐎 𝟗𝟎𝟎𝟏:𝟐𝟎𝟏𝟓 𝐐𝐌𝐒 𝐃𝐨𝐜𝐮𝐦𝐞𝐧𝐭𝐚𝐭𝐢𝐨𝐧 𝐒𝐭𝐫𝐮𝐜𝐭𝐮𝐫𝐞🎯 Implementing ISO 9001:2015 requires a well-structured documentation system that ensures clarity, consistency, and continuous improvement. Here’s a quick breakdown of the essential components: 👇 1. 𝙏𝙞𝙚𝙧 1 𝘿𝙤𝙘𝙪𝙢𝙚𝙣𝙩: 𝙂𝙤𝙖𝙡𝙨 𝙖𝙣𝙙 𝙊𝙗𝙟𝙚𝙘𝙩𝙞𝙫𝙚𝙨 - 𝙏𝙝𝙚 𝙌𝙪𝙖𝙡𝙞𝙩𝙮 𝙈𝙖𝙣𝙪𝙖𝙡-  The Quality Manual serves as the cornerstone of your QMS, outlining the organization's quality goals and objectives. It provides a high-level overview of how quality is managed, setting the direction for the entire system. 2. 𝙏𝙞𝙚𝙧 2 𝘿𝙤𝙘𝙪𝙢𝙚𝙣𝙩: 𝙍𝙪𝙡𝙚𝙨 - 𝙌𝙪𝙖𝙡𝙞𝙩𝙮 𝙋𝙤𝙡𝙞𝙘𝙞𝙚𝙨-  Quality policies establish the rules and commitments that guide the organization towards achieving its quality objectives. These policies align with the overall goals and provide a framework for decision-making across all levels. 3. 𝙏𝙞𝙚𝙧 3 𝘿𝙤𝙘𝙪𝙢𝙚𝙣𝙩𝙨: 𝙒𝙝𝙖𝙩? 𝙒𝙝𝙚𝙣? – 𝙋𝙧𝙤𝙘𝙚𝙨𝙨𝙚𝙨-  Processes define the sequence of activities required to achieve quality objectives. They answer the questions of "What needs to be done?" and "When should it be done?" ensuring that each step in the production or service delivery cycle is clearly defined and consistently followed. 4. 𝙏𝙞𝙚𝙧 4 𝘿𝙤𝙘𝙪𝙢𝙚𝙣𝙩𝙨: 𝙒𝙝𝙤? 𝙃𝙤𝙬? - 𝙋𝙧𝙤𝙘𝙚𝙙𝙪𝙧𝙚𝙨 𝙖𝙣𝙙 𝙄𝙣𝙨𝙩𝙧𝙪𝙘𝙩𝙞𝙤𝙣𝙨-  Procedures and work instructions break down the processes further, specifying "Who is responsible?" and "How should tasks be carried out?" These documents ensure that everyone knows their role and how to perform their duties effectively. 5. 𝙏𝙞𝙚𝙧 5 𝘿𝙤𝙘𝙪𝙢𝙚𝙣𝙩𝙨: 𝙒𝙝𝙚𝙧𝙚? - 𝙏𝙚𝙢𝙥𝙡𝙖𝙩𝙚𝙨, 𝙁𝙤𝙧𝙢𝙨, 𝙖𝙣𝙙 𝘾𝙝𝙚𝙘𝙠𝙡𝙞𝙨𝙩𝙨-  To standardize activities and ensure consistency, templates, forms, and checklists are used. They answer, "Where should information be recorded?" and help maintain uniformity in documentation, making it easier to track and manage quality-related data. 6. 𝙏𝙞𝙚𝙧 6 𝘿𝙤𝙘𝙪𝙢𝙚𝙣𝙩𝙨: 𝙒𝙝𝙚𝙧𝙚? - 𝙍𝙚𝙘𝙤𝙧𝙙𝙨 - Finally, records document the results of processes and actions. They provide evidence of conformity and serve as a reference point for audits, reviews, and continual improvement. 📢By understanding and implementing this documentation structure, organizations can build a robust QMS that not only meets ISO 9001:2015 standards but also drives continuous quality improvement. 📌Share your thoughts and experiences below!   If you resonate with these insights , please 👍🏻👏🏻❤️💡🔁 #ISO9001 #QualityManagement #QMS #ContinuousImprovement #QualityAssurance #Documentation #qa #qc #qaqc