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.

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

Document your projects! It’s not just about writing code; it’s about presenting it in a way that feels professional and usable. One major way to set your projects apart is by properly documenting them. A good README isn’t just an afterthought. It’s a signal to employers that you know how to create a complete, professional product. Your documentation should include clear setup instructions, a concise explanation of what the project does, and any additional features or tools used. Think about it from the perspective of another developer or an employer trying to run your code for the first time. If they can’t figure it out, it doesn’t matter how good the code is. Make it easy for others to understand your work. Document your API if you’re working on backend projects, include user instructions, and outline the purpose and goals of your project. Good documentation shows attention to detail, an understanding of user needs, and a commitment to making your work accessible and professional. It’s one of those small things that can make a big difference in how your projects are perceived.

🚀 Strong document control starts with strong file organisation. In construction projects, especially for Quantity Surveyors and Engineers, poor folder structure and unclear file names can create confusion, duplicate work, missed revisions, payment delays, claim disputes, and unnecessary searching time. A professional document and file organisation system helps every project team to save time, find files quickly, avoid errors, track revisions properly, and maintain complete project control. One powerful approach is to use a consistent metadata based file naming convention: Document Type_Discipline_Description_Revision Change_YYYY-MM-DD-HRS-MIN-SEC Example: Payment Application_QS_Application 05_Rev01_2026-07-03-10-15-21.pdf Short version: Payapp_QSapp05_R01_26-07-03-10-15-21.pdf This format gives every file a clear identity by showing the document type, discipline, description, revision status, date, hour, minute, and second. The final seconds make the file name unique every time, helping teams track documents more accurately without confusion. A well organised project folder structure should include: Contract Documents Drawings Correspondence Payment Applications Variations Quantity Take Off Procurement Site Documents Meetings Photos Final Account Key rule: never overwrite approved files. Always save revisions separately and maintain a clean audit trail. Good organisation today means smoother claims, faster approvals, professional communication, and successful project closeout tomorrow. Be organised. Be professional. Be a step ahead. #DocumentControl #DocumentController #DocumentManagement #ConstructionDocuments #ProjectDocumentation #FileOrganisation #FolderStructure #MetadataManagement #RevisionControl #DocumentTracking #EngineeringDocuments #QuantitySurveyor #QuantitySurveying #ConstructionManagement #ProjectControl #ProjectManagement #Aconex #SharePoint #EDMS #CDE #DigitalTransformation #ConstructionIndustry #ClaimsManagement #ContractManagement #ProcurementDocuments #SiteDocumentation #QualityManagement #ISO9001 #ProfessionalDevelopment #DocumentControlAcademy #DocumentControl #DocumentManagement #ConstructionDocuments #QuantitySurveyor #RevisionControl #ProjectControl #Aconex #SharePoint #EDMS #ConstructionManagement #FileOrganisation #DocumentControlAcademy

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.

Nobody teaches you Document Control in university. You figure it out on the job. Usually the hard way. Here's the COMPLETE simple guide every DC and Engineer needs ━━━━━━━━━━━━━━━━ 1. WHAT IS DOCUMENT CONTROL? Organizing & managing project documents so that: ✅ Everyone uses the CORRECT version ✅ Documents are APPROVED before use ✅ Files are EASY to find ✅ Everything can be TRACKED Simple rule: Right Document • Right Person Right Time • Correct Version ━━━━━━━━━━━━━━━━ 2. TYPES OF DOCUMENTS YOU'LL MANAGE: 📐 Engineering Documents: → Drawings, Specifications, Method Statements 💼 Commercial Documents: → Contracts, BOQ, Invoices 📋 Project Documents: → RFIs, Submittals, Transmittals, Reports ━━━━━━━━━━━━━━━━ 3. DOCUMENT LIFECYCLE (Every doc goes through): Creation → Review → Approval → Distribution → Revision → Archiving Every single document. Every single time. No shortcuts. ━━━━━━━━━━━━━━━━ 4. DOCUMENT NUMBERING SYSTEM Example: PRJ-CIV-DRW-001-REV01 🔵 PRJ = Project 🔵 CIV = Discipline 🔴 DRW = Type 🟡 001 = Number 🟢 REV01 = Revision Master this → find ANY document in seconds ✅ ━━━━━━━━━━━━━━━━ 5. BASIC TOOLS TO KNOW: 📊 Excel → Track documents & registers 📝 Word → Create & format documents 📄 PDF Tools → Share & control files ━━━━━━━━━━━━━━━━ 6. DAILY WORK OF A DC: Every single day: ✅ Register documents ✅ Update logs ✅ Track revisions ✅ Send documents ━━━━━━━━━━━━━━━━ 7. IMPORTANT REGISTERS (LOGS): 📃 Document Register → Number, title, revision, status ®️ Drawing Register → Drawing details & revisions 📦Submittal Log → Submission status (approved/rejected) ━━━━━━━━━━━━━━━━ 8. WORKFLOW (How Documents Move): Contractor sends → Consultant reviews → Final approval → Issued for use ✅ ━━━━━━━━━━━━━━━━ 9. ADVANCED SYSTEMS TO LEARN: 🔵Aconex (Oracle) 🟠 Procore 🟢 SharePoint ━━━━━━━━━━━━━━━━ 10. EXCEL SKILLS EVERY DC MUST HAVE: ✅ XLOOKUP / VLOOKUP ✅ INDEX + MATCH ✅ Conditional Formatting ✅ Pivot Tables ━━━━━━━━━━━━━━━━ 11. COMPLIANCE & STANDARDS: ✅ Track performance (KPIs) ✅ Follow ISO standards (ISO 9001) ✅ Prepare for audits ✅ Keep records organized ━━━━━━━━━━━━━━━━ 12. MASTER LEVEL RULE: NEVER delete or overwrite old documents. Always keep the history. Always. ━━━━━━━━━━━━━━━━ Remember: Document Control isn't just paperwork. It's about ACCURACY, TRANSPARENCY and PROJECT SUCCESS.

In my different leadership roles, I’ve always struggled to get developers to write and maintain relevant documentation. It’s been their bête noire. And when they do write it, it’s usually under managerial pressure, resulting in long SharePoint or Confluence pages that slowly rot, disconnected from the actual architecture and code. In my last mission, I decided to face the elephant in the room and change the approach. Surprisingly, it worked. (Partly thanks to LLMs 😊) Here’s what we did: We moved to collaborative documentation (Microsoft Loop — but it could be Notion, Confluence, whatever fits your team). I encouraged devs to use ChatGPT — not to replace them, but to help them structure, improve, and enrich their writing. We made architecture and design discussions async and doc-first. I introduced a simple rule: 👉 “If it’s not on Loop, it doesn’t exist.” Within a few months, we went from static, outdated SharePoint pages... ...to living docs and Architecture Decision Records (ADRs) — that became a shared knowledge base for the team and the broader company. Of course, AI tools won’t write your docs for you. But they can help your team build a real documentation culture. And you — what’s your experience with documentation? #softwareengineering #engineeringmanagement #documentation #softwaredocumentation #architecture #adr #softwarearchitecture

The legacy system documentation is a ticking time bomb. Hey y'all! Something's keeping me up at night: while everyone's drooling over the newest AI toys, millions of critical COBOL systems are running with documentation that's basically a hot mess of digital spaghetti. The documentation problem is REAL, folks. Most big companies have decades of system info scattered across random folders, personal drives, and (I'm not making this up) actual paper manuals locked in cabinets nobody can find keys for anymore. Why should we care? Because when your last COBOL expert retires next month, all that knowledge walks right out the door with them. And guess who's gonna be panicking when that mission-critical banking system crashes at 2 AM? Yep, you. Some facts that should make you sweat: • Most companies have ZERO actual documentation standards for legacy systems • Documentation is often older than most entry-level employees • New developers waste 60% of their time just trying to figure out how the darn system works • Critical knowledge exists only in the heads of people about to retireThe solution isn't fancy or trendy, but it works: get your documentation organized, people!Smart companies are doing some basic stuff that actually works: 1. Create a standard folder structure for ALL legacy documentation 2. Set up smart search capabilities (like Smart Folders) that can find any document across your entire system¹ 3. Use naming conventions that even new hires can understand 4. Make sure the right team members can access what they need 5. Create specific spaces for critical documents like system diagrams and emergency proceduresWill this problem get better or worse soon? My bet: it's gonna get much, much worse unless companies wake up and do something now. The good news? You don't need some expensive fancy solution. A well-organized folder system with decent search can turn your documentation chaos into something usable overnight. If you're running legacy systems without a documentation strategy, you're basically playing Russian roulette with your company's most important stuff. Don't be that person.