Best Practices For Engineering Documentation

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.

Yesterday, the AI Office published the third draft of the General-Purpose AI Code of Practice, a key regulatory instrument for AI providers seeking to align with the EU AI Act. Developed with input from 1,000 stakeholders, the draft refines previous versions by clarifying compliance requirements and introducing a structured approach to regulation. GPAI providers must meet baseline obligations on transparency and copyright compliance, while models classified as having systemic risk face additional commitments under Article 51 of the AI Act. The final version, expected in May 2025, aims to facilitate compliance while ensuring AI models adhere to safety, security, and accountability standards. The Code introduces the Model Documentation Form, requiring AI providers to disclose key details such as model architecture, parameter size, training methodologies, and data sources. Transparency obligations include specifying the provenance of training data, documenting measures to mitigate bias, and reporting compute power and energy consumption. GPI providers must also outline their models’ intended uses, with additional requirements for systemic-risk models, including adversarial testing and evaluation strategies. Documentation must be retained for twelve months after a model is retired, with copyright compliance mandatory for all providers, including open-source AI. GPAI providers must establish formal copyright policies and comply with strict data collection rules. Web crawlers cannot bypass paywalls, access piracy sites, or ignore the Robot Exclusion Protocol. The Code also requires providers to prevent AI-generated copyright infringement, mandate compliance in acceptable use policies, and implement mechanisms for rightsholders to submit copyright complaints. Providers must maintain a point of contact for copyright inquiries and ensure their policies are transparent. For AI models with systemic risk, the Code introduces a Safety and Security Framework, aligning with the AI Act’s high-risk requirements. Providers must assess risks in areas such as cyber threats, manipulation, and autonomous AI behaviours. They must define risk acceptance criteria, anticipate risk escalations, and conduct assessments at key development milestones. If risks are identified, development may need to be paused while safeguards are implemented. GPAI providers must introduce technical safeguards, including input filtering, API access controls, and security measures meeting at least the RAND SL3 standard. From 2 November 2025, systemic-risk models must undergo external risk assessments before release. Providers must maintain a Safety and Security Model Report, report AI-related incidents within strict timeframes, and implement governance structures ensuring responsibility at all levels. Whistleblower protections are also required. With the final version expected in May 2025, AI providers have a short window to prepare before the AI Act takes full effect in August.

Hate how boring and time-consuming documentation feels? Yeah, same. But here’s the thing: the more you avoid it, the more you hurt your future self and miss opportunities to showcase your skills properly. So if you want to make documentation less painful (and actually useful), here are 6 tips I use with my clients to make it faster, clearer, and more impactful: 1. Start with an overview What’s the purpose of your project? What problem did it solve? Just 3–4 lines to set the stage. Make it easy for anyone to understand why it matters. 2. Walk through your process Break down the steps: How did you collect the data? How did you clean, analyze, or model it? What tools or methods did you use? This shows how you think and how you solve real-world problems. 3. Add visuals A clean chart > a wall of text. Use graphs, screenshots, and diagrams to bring your work to life. (And bonus: you’ll understand it faster when you come back later.) 4. Show your problem-solving What roadblocks did you hit? How did you fix them? Don’t hide your struggles, highlight them. This is where your value really shines. 5. Summarize your results What did you find? Why does it matter? What’s next? Answer these three questions clearly and your audience will instantly get the impact of your work. 6.  Use a structure that makes sense Try this flow: Introduction → Objectives → Methods → Results → Conclusion → Future Work Simple. Clean. Effective. P.S: After every milestone, take 5 minutes to update your notes, screenshots, or results. Turn it into a habit. ➕ Follow Jaret André for more data job search, and portfolio tips 🔔 Hit the bell icon to get strategies that actually move the needle.

FDA's AI Enforcement Shift: What the Exer Labs Warning Letter Signals for GxP Teams The era of treating AI as a "non-product" tool outside traditional validation is over. The FDA's enforcement against Exer Labs classified their AI motion-analysis system as a medical device and cited deficiencies across validation, change control, and lifecycle management. The signal: when AI influences regulated decisions, the solution must be brought under your quality system with expectations proportionate to process and patient risk. Three consequences for Pharma and MedTech teams: 1) Validation scope widens AI models touching labeling, dosing, safety, or quality decisions require a documented credibility assessment consistent with the January 2025 draft guidance's 7-step framework and your CSA/GAMP risk classification. 2) ALCOA+ includes model behavior Training data lineage, drift monitoring, bias detection, and explainability must meet the same data integrity standards as batch documentation. Audit trails for AI-supported decisions are expected, not optional. 3) Lifecycle management becomes continuous The agency expects active monitoring, not one-time validation. SOPs need change-control pathways for model updates and retraining. Not only for software releases. The January 2025 draft incorporated patterns from 500+ AI-related submissions since 2016. FDA reviewers know exactly where gaps typically appear. Practical next step: Inventory every AI system touching regulated decisions. Map each against the credibility assessment framework before your next audit. Which gap would an inspector find first: data lineage, model validation documentation, or change control procedures? #AIStrategy #LifeSciences #GxP #Validation #DigitalR&D #CSV #DataIntegrity #ALCOA #FDA

How Are You Auditing AI Model Cards? I am certain of few things in this world of great change ... but I am going to go out on a limb and say that within six months (if not already) Boards and Management are going to be asking of Internal Audit: "So can you provide assurance ... by tomorrow ... over our model card?" And this will prompt a question you will quickly ask of AI - which as you will see by the end of this LinkedIn post is ironic!: "I have no idea what they are asking me to do; what is a model card?" I saw a great description of model cards being like a nutrition label for AI - a document that explains what an AI model is meant to do, how it was built, how well it performs, and what its risks or limitations are. A model card should help non-technical people - executives, regulators, customers (me!) - see if an AI system is safe, fair, and fit for purpose. (The Google Model Card page is worth a look: https://lnkd.in/g6z5-dHQ) Hmmm ... stakeholders wanting comfort that what they are using is safe and appropriate ... what function in an organisation could possibly help ... Stand up Internal Audit ... this is our time!!! And this is what we need to do. ~ Model Design & Purpose ~ 1 - Confirm the intended use case is clearly documented. 2 - Check that the business objective aligns with the model’s stated purpose. 3 - Ensure stakeholders can understand the card (plain language, no jargon). ~ Model Data & Development ~ 4 - Review how datasets are sourced, documented, and compliant. 5 - Assess bias testing and fairness methods (easier said than done!). 6 - Confirm that validation data is independent from training. ~ Model Training & Testing ~ 7 - Validate that performance metrics are fairly presented. 8 - Review stress testing for edge cases and robustness. 9 - Ensure limitations and assumptions are openly disclosed. ~ Model Risk & Compliance ~ 10 - Confirm operational, ethical, and regulatory risks are listed. 11 - Check alignment with laws and standards. 12 - Ensure misuse scenarios are anticipated and mitigated. ~ Model Governance & Deployment ~ 13 - Verify that the model card names clear accountable owners. 14 - Review version control for every model iteration. 15 - Assess change governance before deployment updates. ~ Model Controls & Safeguards ~ 16 - Confirm there are fallback procedures if the model fails. 17 - Review audit trail evidence for external (non management) review. 18 - Check coverage of third-party models interacting with the reviewed model. ~ Model Monitoring & Continuous Assurance ~ 19 - Confirm the card references ongoing monitoring of performance and risks. 20 - Assure that Internal Audit has visibility into the entire lifecycle for repeat reviews. ** AI may often feel complex (primarily because it is), but trust is simple: document, disclose, and independently assure. The first globally recognised AI Model Auditor is going to reshape the entire profession. Who will it be?

⚠️ Why should banks care about AI governance today—not tomorrow? Because model failures already exist. Because AI audits aren’t optional anymore. And because this new certification framework might be the most rigorous response to SR11-7 you haven’t heard about yet. 📘 Just read through ForHumanity’s Model Risk Management Certification Scheme v1.5—and it’s a game changer for Regulated Financial Institutions using AI, algorithmic, or autonomous (AAA) systems. What stood out? 💡 Why it matters: This isn’t just another standard. It’s a modular, compliance-by-design infrastructure that fuses BASEL III, SR11-7, SR13-19, and other federal guidance with human-centric governance criteria. Think of it as a bridge between: traditional model risk frameworks, and modern AI governance demands. No more waiting for AI Act enforcement. No more vague accountability. 🔍 Key strengths: Covers everything from conceptual soundness to decommissioning. Defines Top Management and Oversight Bodies, linking internal audit, risk, compliance, and ethics. Introduces clear audit-ready documentation like the cAIRE Report, Residual Risk statements, and Explainability+. Integrates Fiduciary human oversight and protections for vulnerable populations. Most importantly: It’s binary and enforceable—compliant or not. No grey zones. 👥 It’s also one of the few schemes explicitly calling for expert multidisciplinary teams—market experts, ethics professionals, cybersecurity leads—working together to reduce systemic risk in finance. Grateful to the 2,900+ contributors behind this work. ForHumanity continues to lead in defining practical, defensible, and ethical AI standards. #ModelRisk #AIinFinance #SR117 #AIGovernance #AAACompliance === Did you like this post? Connect or Follow 🎯 Jakub Szarmach Want to see all my posts? Ring that 🔔. Sign up for my biweekly newsletter with the latest selection of AI Governance Resources (1.400+ subscribers) 📬.

Audit documentation tip #5 Document how audit information (including client-prepared) relates to your planned audit procedures including the source (where did it come from and from whom?) and the purpose of the information (why is it in the audit file?). Document where the information came from. Who prepared it and how? Document the purpose of the information. How does it relate to the planned audit procedures (which should come from our risk assessments)? If the information has no relation to the planned procedures, is it needed? Include a purpose statement on each main work paper. Many auditors take exception to this; they say a purpose statement is redundant, that the procedures are in the audit program. But let me say as someone who has reviewed tens of thousands of work papers, it is often not clear why a work paper is in the file. It might make sense to the person who included it, but not to anyone else. I think I’ve spent months (maybe years) of my life staring at work papers and trying to make sense of them. Remember, create your documentation so it’s understandable to an experienced auditor/reviewer (this is the requirement of the audit standards). You are communicating to that audience (not to yourself). In summary, include the following on each lead work paper: Source of information Purpose of information Relation to planned audit procedures Does it take more time to document these? Yes, but less time than is lost by reviewers trying to understand what was done. #CPAHallTalk, #auditdocumentation

Screenshots are documentation rot. → They look helpful and they break everything. They go stale on the next release, then hide text from search and screen readers. They explode localization budgets and teach users to chase pixels instead of completing tasks. Here is what we do instead if we care about accuracy, access, and speed: 1) Replace pictures with tasks: Write the steps. Name the controls. Describe the state. Users finish work faster when they can scan verbs and nouns instead of hunting for a red box around a button. 2) Bind callouts to the UI, not to an image: Reference stable labels, roles, and selectors so instructions survive theme changes and layout shifts. If the product moves, the language still holds. 3) Show systems, not screens: Use one evergreen diagram per flow to explain concepts and relationships. Diagrams age slowly, screenshots expire overnight. 4) Use motion sparingly and on purpose: Short, evergreen GIFs for gestures only. Crop to the principle, not the pixels. No text baked into images. Always include alt text and a written path. 5) Make it maintainable by design: Centralize terms and labels. Version examples. Lint links. Treat docs like code so updates are incremental and testable instead of a screenshot scavenger hunt. If you need proof, audit your last 10 pages. Count the images. Now count the places the UI changed. That gap is your debt. Delete the screenshots and ship instructions that survive the next release. Users will finish tasks. Translators will move faster. Your team will stop babysitting pixels and start delivering clarity.

A European Standard for AI cybersecurity: Baseline Cyber Security Requirements for AI Models and Systems. If you build or deploy AI systems for European markets, expect this standard to show up in customer due diligence, RFP language, and “map your controls” conversations. ETSI published ETSI EN 304 223 V2.1.1, “Baseline Cyber Security Requirements for AI Models and Systems”, a European Standard for AI cybersecurity. I read it so you don’t need to. (link in comments 👇) Highlights: 🔹 The standard sets a lifecycle security baseline across five phases: design, development, deployment, maintenance, and end of life. 🔹 It defines 13 high-level principles that are easy to map into engineering, governance, and operational controls. 🔹 It makes documentation and auditability core requirements, including traceability for models, data, prompts, and configuration changes. 🔹 It treats model exposure as an attack surface and calls out API abuse mitigations such as access controls and rate limiting. 🔹 It requires ongoing monitoring for AI-specific failure modes, including behavioral drift and indicators of data poisoning. My take: 1️⃣ For AI vendors selling into Europe, it is worth starting to align their controls with ETSI EN 304 223 now. 2️⃣ AI security vendors should publish mappings showing how their tooling helps teams meet these requirements. 3️⃣ The standard is intentionally high level. It doesn’t specify metrics, thresholds, or minimum testing depth, so, as with ISO/IEC standards, teams must translate it into measurable controls, acceptance criteria, and checklists. 4️⃣ Secure development is the focus: 5 of 13 principles, and a strong push for audit-ready evidence. 5️⃣ AI security and AI safety are converging. See my earlier post on the Cisco AI Cybersecurity Framework (link in comments 👇). ETSI’s planned TR 104 159 for generative AI extends the focus to deepfakes, misinformation and disinformation, confidentiality risks, and copyright and IPR concerns.