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.

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.

Most inaccessible documents aren’t created out of bad intent. No-one does it on purpose. They’re created out of habit. The good news is you don’t need to be an accessibility expert to help build a culture where accessible documents become the norm. Small behaviours, repeated often, shape organisational culture far more than policies do. Here are five simple things anyone can do, right now. (You can also find some further resources in the comments.) 1 - Build accessibility into your workflow Treat accessibility checks the same way you treat spellcheck. Before sending a document, take a minute to run an accessibility check and scan for obvious issues. When accessibility becomes a normal step in the workflow, it stops being an afterthought and starts becoming routine. 2 - Be an ally. You don’t have to personally need accessibility to advocate for it. Ask whether documents have been checked. Encourage colleagues to think about accessibility. If something isn’t accessible, raise it constructively, push back gently if someone sends you something that isn’t accessible. Cultural change often begins with someone asking the question. 3 - Learn the tools you already have Most people already have everything they need. Simple features such as document headings (heading 1, 2 etc), meaningful link titles, and built in accessibility checkers make a huge difference. Learning how to use these properly can transform the usability of a document in minutes. 4 - Think beyond screen readers. Whilst a crucial part of it, accessibility isn’t just about screen reader compatibility. Clear structure, readable layouts, logical headings, and descriptive links make documents easier for everyone to navigate and understand. Accessibility improves usability for the entire organisation. 5 - Automate your mailbox One simple trick is creating an Outlook rule that replies to anyone who sends you an attachment asking whether the document has been checked for accessibility. It’s a gentle prompt that helps build awareness and encourages better habits over time. Bonus tip - set the standard. If you want others to care about accessible documents, your own documents need to set the standard. When people consistently receive accessible content from you, it reinforces that accessibility is not an optional extra. It is simply how good work gets done. Accessibility culture doesn’t start with experts. It starts with everyday habits. ID: a Robbie Crow Purple infographic titled “Five top tips to build a culture of document accessibility”. It summarises the points in this post and full alt text can be found in the image. The graphic uses purple, pale yellow and gold branding with a “Progress Over Perfection” badge at the bottom.

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?

I timed our last client review cycle. 41 days. The actual reviewing? 3 days. Where did the other 38 days go? → 8 days waiting for Reviewer 1 to "find time" → 6 days because Reviewer 2 was on vacation (nobody checked the calendar) → 5 days resolving contradictory feedback between two reviewers who never talked to each other → 4 days because the SME added "one more section" after the draft was "final" → 3 days re-reviewing changes from the contradictory feedback round → 12 days of the document sitting in someone's inbox marked "unread" This isn't a documentation problem. It's a process problem wearing a documentation costume. Three fixes that have cut review cycles by 50-70% for our clients: 1. Structured review templates. Don't ask "please review." Ask specific questions: "Is the safety classification in Section 3.2 correct? Is the torque value on page 7 current?" 2. Async feedback with hard deadlines. Give reviewers 5 business days. Put this in writing before the cycle starts: without your sign-off, this documentation doesn't ship. And if the documentation doesn't ship, neither does the product. 3. Single-authority sign-off. One person resolves conflicting feedback. Not a committee. Not a meeting. One person with the authority to decide. The review cycle isn't long because documentation is complicated. It's long because nobody designed the process. #TechnicalWriting #Documentation #ProcessImprovement #ProjectManagement

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.

I just discovered how construction companies are creating complete SOPs in 45 minutes instead of 18 months. Building PPL shared their exact framework, and it's brilliant. Most companies approach process documentation like they're writing a manual for NASA. ❌ Old Way (18 months): • Form process improvement committee • Research industry best practices • Draft formal documentation • Endless revision cycles • Launch and pray people use it 18 months later, you have a beautiful manual that sits on a digital shelf collecting dust. ✅ New Way (45 minutes): • Grab your best person for this process • Record them explaining it to someone new • Use AI to structure the messy conversation into clear steps That's it. Building PPL worked with a construction company that had been "meaning to document processes" for 3 years. In one afternoon, they captured their entire submittal process—including all the unwritten tricks that actually make it work. The difference was they stopped trying to create something perfect and started extracting knowledge that already existed. Your people already know how to do the work. They just need help getting it out of their heads. Here's how to get started: STEP 1 - Pick Your Paint Point • List your 5-8 core processes that cause chaos when key people are out • Pick the one causing the most pain RIGHT NOW STEP 2 - Extract The Knowledge • Record your expert walking through the process • Don't script it. Let them ramble. • Capture the WHY, not just the WHAT STEP 3 - PACKAGE • Use AI to transform rambling conversation into clear steps • Simple format: Purpose → Steps → Success Definition • Store where people actually look for information What used to take committee meetings and corporate writing now happens over coffee. Your challenge: • Pick ONE process that confuses new people • Block 45 minutes on your calendar • Follow the framework: Identify → Document → Package You can start with just a phone recording and some AI help. Building PPL has turned this into a science, but the basics work for anyone. Construction is complex enough. Your processes don't have to be. 👇 Which process will you document first?

The hidden engineering team you didn’t plan to hire. I have built and reviewed enough products to spot this pattern early. It always starts small. “Just a form.” “Just a PDF.” “Just one signature flow.” Then it quietly grows into something else. Suddenly you are dealing with: - Field validation edge cases - PDF versioning and placement bugs - Signature failures you cannot afford to lose - Audit trails, permissions, and compliance reviews - Engineers getting pulled back in month after month None of that shows up on the original roadmap. Here is the uncomfortable truth most teams learn too late: Document workflows are not a one-time build. They are permanent infrastructure. This is why tools like Anvil matter earlier than people expect. Anvil lets product teams turn paperwork into API-driven workflows from day one. - Dynamic webforms. - Automated PDF generation. - Embedded e-signatures. - All styled to your product and embedded directly in your app. Think TurboTax, but for your product experience. One set of fields. Data routed everywhere it needs to go. No engineers babysitting forms forever. The strategic reframe for PMs and founders is simple: Every internal document workflow you build is a long-term maintenance commitment. Today, I would default to buying that infrastructure. Not assigning engineers to quietly become a paperwork team. Try here: https://lnkd.in/ec9aSyfD What do you think about this shift in how we do paperwork? Comment below 👇 #AnvilPartner 

Document Control is essential in every organisation and every project because it protects information, reduces risks, and ensures that people always work with the right document at the right time. 1. Ensures Everyone Works on the Latest and Correct Information Document Control prevents teams from using outdated, incorrect, or superseded documents. This directly avoids: • Rework • Construction mistakes • Safety risks • Cost overruns • Delays In engineering projects, working on the wrong revision can cost millions. 2. Provides Structure, Standards, and Consistency Document Control enforces: • Naming conventions • Metadata • Templates • Versioning rules • Controlled workflows This ensures the entire organisation follows a consistent and professional structure. 3. Supports Compliance & Governance Document Control ensures alignment with: • ISO 9001 / QMS • Contractual requirements • Client standards • Regulatory authorities • Audit trails Strong control protects the organisation legally and contractually. 4. Maintains a Single Source of Truth (SSOT) A controlled EDMS/DMS ensures everyone accesses: • One system • One revision • One approved source No confusion. No personal folders. No scattered versions. This improves clarity and decision-making. 5. Improves Efficiency and Productivity Document Control: • Speeds up review and approval cycles • Ensures automatic notifications • Reduces admin workload for engineers • Makes documents searchable and retrievable • Prevents duplication of work Teams work faster, smarter, and with fewer errors. 6. Enhances Collaboration Across Departments Document Control supports smooth information flow across: • Engineering • Procurement • Construction • Quality • Commissioning • Vendors & Subcontractors • Clients The process becomes timely, traceable, and well-coordinated. 7. Strengthens Traceability & Audit Trails Good Document Control maintains full history: • Who created • Who reviewed • Who approved • What changed • When it changed • Why it changed This protects the project during: • Claims • Disputes • Variations • Handover 8. Supports Digital Transformation Modern EDMS/DMS tools enable: • Automation • Integration with planning & cost systems • Real-time dashboards • AI-assisted quality checks • Role-based access • Remote collaboration Document Control is a foundation of digitalisation. 9. Critical for Handover & Operations Operations require: • As-built documents • Vendor manuals • Data sheets • Certificates • Test packs • Drawings Document Control ensures everything is complete, organised, and verified. 10. Reduces Risks, Costs, Delays & Safety Issues Weak Document Control leads to: • Construction errors • Schedule delays • Cost overruns • Safety hazards • Contractual non-compliance • Disputes • Reputational damage Effective Document Control prevents problems before they happen.