Tips for Creating Strong Documentation

My co-author, Colin Bryar, and I wrote, read, and reviewed thousands of business narrative documents during our combined 27 years at Amazon. Based on our experience, here are tips to follow and common pitfalls to avoid. 1. Write for a generalist executive audience. Picture your reader as intelligent but unfamiliar with the specifics of your domain. Imagine a new senior leader who just joined the company. This will make it easy for anyone in your company to understand your business unit or function’s plans, metrics, results, problems, and opportunities. 2. Skip the suspense. Building suspense works in mystery novels, not in business narratives. Get to the point directly. Make sure to use concise, direct language. Every sentence should add value and distill complex ideas into a document that enables high-quality decision-making. 3. Let data tell the story. Replace adjectives with data. Instead of saying “sales accelerated,” say, “Sales in February were $150MM, a 22% increase versus January, 15% year-over-year, and 3% above plan.” Weasel words like “many” or “significant” are meaningless without context. If you can’t quantify something, explain why not and outline how you’ll get better data to quantify it in the future. 4. Anticipate and include counterarguments. Inform the reader what you considered and rejected, along with the reasons. Provide more than one option or solution when possible, and explain why you chose the recommended approach. This demonstrates that you've thought through alternatives. 5. It’s Word, not PowerPoint. Don’t just copy a Powerpoint and paste bulleted text into a Word Doc. Use full sentences and a narrative flow to tie together related data, thoughts and concepts. True narrative writing creates logical connections between ideas, shows cause and effect, and builds toward conclusions. 6. Provide insights, not a data dump. One of the most common errors made by inexperienced managers and writers is to writing documents describing activity and data, but failing to provide insights and information. Don’t try to write about everything. Summarize, distill, and provide insights. 7. Less is more. The best way to destroy the benefits of writing business narratives and conducting meetings with narratives is to bring a long document to the meeting. For a one-hour meeting, the page limit is six pages. For a 30-minute meeting, the page limit is three pages. If narratives exceed these limits, the readers will not be able to carefully read the entire document during the 15-20 minute silent reading time at the beginning of the meeting. Readers are forced to skim, and your discussion and decision-making will be based on partial information. If you would like to learn more about writing an Amazon-ready narrative, our new online course on writing narratives has launched: https://lnkd.in/gYSnerCD

🌟 Best Practices in Salesforce Documentation 🌟 Clear, consistent, and up-to-date documentation is one of the most underrated secrets behind successful Salesforce implementations. Whether you’re working solo or as part of a team, great documentation empowers everyone to build smarter, fix faster, and onboard easier. Here’s how to get it right: 🔹 Start With the Basics Be Consistent: Use the same structure, language, and formatting across all documentation. This makes it easy for anyone to jump in and understand your work. Keep It Simple: Avoid excessive jargon. Write like you're explaining it to a smart teammate who’s new to the org. 🔹 Use Visuals and Metadata Wisely Add Diagrams and Screenshots: A simple flowchart or a well-placed screenshot can explain more than a page of text. Descriptive Field Names and Help Text: Include why a field exists, how it's used, and what it impacts. These small notes can save hours later. 🔹 Stay Agile, Not Rigid Document As You Go: The best time to write documentation is when you're in the middle of the work. Don’t wait until later—it rarely happens. Version Control: Track changes to keep a clear audit trail. Even simple naming like v1.2_final_FINAL (okay, maybe cleaner than that) helps avoid confusion. 🔹 Build Organizational Knowledge Create a Metadata Dictionary: Keep a living list of key objects, fields, and relationships in your org. This makes reporting, automation, and debugging faster and easier. Map Business Processes: Tools like Salesforce UPN or Lucidchart can help turn complex logic into digestible visual stories for both technical and non-technical stakeholders. 🔹 Think Long-Term Change Logs: Note what was changed, why, and by whom. You'll thank yourself later. Architectural Decision Logs: For major implementations, document why a particular design was chosen over others. It saves time when scaling or troubleshooting. 🔹 Use Salesforce’s Built-In Tools Leverage Notes, Knowledge Articles, and Chatter Groups to store and share documentation where your team already works. 🔹 Stay Ready for AI AI tools (like Agentforce for developers) thrive on clean metadata and documentation. Well-documented orgs will have a head start as AI takes a bigger role in development and support. 🔹 Make It a Team Effort Encourage feedback and contributions from your team. Documentation improves when it's a shared responsibility, not a solo task. Include key docs in training and onboarding so new team members hit the ground running. 📌 Pro Tip: Don’t try to document everything at once. Focus on areas with the most change or confusion. Over time, your documentation will become a powerful, living knowledge base.

The Medical Device Iceberg: What’s hidden beneath your product is what matters most. Your technical documentation isn’t "surface work". It’s the foundation that the Notified Body look at first. Let’s break it down ⬇ 1/ What is TD really about? Your Technical Documentation is your device’s identity card. It proves conformity with MDR 2017/745. It’s not a binder of loose files. It’s a structured, coherent, evolving system. Annexes II & III of the MDR guide your structure. Use them. But make it your own. 2/ The 7 essential pillars of TD: → Device description & specification → Information to be supplied by the manufacturer → Design & manufacturing information → GSPR (General Safety & Performance Requirements) → Benefit-risk analysis & risk management → Product verification & validation (including clinical evaluation) → Post-market surveillance Each one matters. Each one connects to the rest. Your TD is not linear. It’s a living ecosystem. Change one thing → It impacts everything. That’s why consistency and traceability are key. 3/ Tips for compiling TD: → Use one “intended purpose” across all documents → Apply the 3Cs: ↳ Clarity (write for reviewers) ↳ Consistency (same terms, same logic) ↳ Connectivity (cross-reference clearly) → Manage it like a project: ↳ Involve all teams ↳ Follow MDR structure ↳ Trace everything → Use “one-sheet conclusions” ↳ Especially in risk, clinical, V&V docs ↳ Simple, precise summaries → Avoid infinite feedback loops: ↳ One doc, one checklist, one deadline ↳ Define “final” clearly 4/ Best practices to apply: → Add a summary doc for reviewers → Update documentation regularly → Create a V&V matrix → Maintain URS → FRS traceability → Hyperlink related docs → Provide objective evidence → Use searchable digital formats → Map design & mfg with flowcharts Clear TD = faster reviews = safer time to market. Save this for your next compilation session. You don't want to start from scratch? Use our templates to get started: → 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 )

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

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.

𝗧𝗵𝗲 𝗱𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗮𝘁𝗶𝗼𝗻 𝘀𝘁𝗿𝗮𝘁𝗲𝗴𝘆 𝘁𝗵𝗮𝘁 𝘀𝗲𝗽𝗮𝗿𝗮𝘁𝗲𝘀 𝗽𝗿𝗼𝗺𝗼𝘁𝗲𝗱 𝗣𝗠𝘀 𝗳𝗿𝗼𝗺 𝘀𝘁𝘂𝗰𝗸 𝗼𝗻𝗲𝘀. Let me guess. You think documentation is the boring part of project management. I used to think that way too. Until I watched a senior PM use documentation to save her career and secure a promotion in one meeting. She was leading a complex software implementation that was spiraling out of control. The executive sponsor claimed requirements had shifted without approval. The team insisted the goals kept changing after development began. In the high-stakes meeting that followed, she calmly pulled up a simple decision log tracking every change request, approval details, and timeline impact. The room went silent. The facts spoke louder than emotions. That day taught me: documentation isn't just administrative work. It's career insurance. This revelation transformed not only my PMP exam preparation (where documentation questions are heavily weighted) but my entire approach to leadership. Strategic documentation creates three career advantages: → 𝗦𝘁𝗮𝗸𝗲𝗵𝗼𝗹𝗱𝗲𝗿 𝘁𝗿𝘂𝘀𝘁: You become the voice of clarity when emotions run high → 𝗣𝗿𝗼𝗺𝗼𝘁𝗶𝗼𝗻 𝗿𝗲𝗮𝗱𝗶𝗻𝗲𝘀𝘀: You demonstrate executive-level accountability and foresight → 𝗣𝗿𝗼𝘃𝗲𝗻 𝗿𝗲𝘀𝘂𝗹𝘁𝘀: Research shows proper documentation enhances project efficiency by up to 30% Successful PMs don't document everything. They document strategically: → Meeting notes capture decisions and commitments, not conversations → Requirements focus on business outcomes, not features → Status reports highlight value delivered, not just work completed Whether you're studying for certification or positioning yourself for advancement, your documentation approach can differentiate you from peers who view it as just another checkbox. The question isn't whether you're documenting. It's whether you're documenting with purpose. What documentation practice has most helped your project management career? Follow Brian Ables, PMP for practical tips and strategies to grow your career. ♻️ If this post helped you, repost it so others can benefit too.

In any data analytics project, documenting your work will save a lot of headaches in the long run. One of my favorite ways to do that is by using my a well written README file. Think about the README file as a “fools proof” recipe, where anyone can read and understand what your project is about. Here is what you can include: ⭐️ Project Overview: Start with a description of what the project goals are. In here you can put the scope of your analysis. ⭐️ Data Sources: Provide an overview of where the data comes from. This is specially helpful if you have multiple sources of data. ⭐️ Project Structure: Explain the organization of the project’s files and directories. This helps users know where to look for scripts, datasets, and outputs. ⭐️ Assumptions and Limitations: State any assumptions made during the analysis and acknowledge the project’s limitations, such as data quality or model constraints. ⭐️ Version Control: Maintain records of code and dataset versions to track changes and revert if necessary. ⭐️ ETL/Processing Pipelines: Document each step in data extraction, transformation, and loading processes, including the rationale behind any data cleaning, filtering, or transformation decisions. ⭐️ Business Logic: Clarify how the data connects to the business logic. For instance, how missing data is handled or the logic behind specific business rules applied to the data ⭐️ Analysis and Insights Documentation: Be clear about how the analyses was performed, which models were used, and how that relates to the project goals. This helps future users or team members understand how conclusions were reached. A solid documentation takes time. Remember that those tips are good not only for your coworkers, but your future self will also thank you Be curious and keep on nerding 😊

🌟 Understanding Quality Documents – The Foundation of a Strong QMS A good Quality Management System (QMS) is not just about inspections or audits… It begins with clear, structured, and well-organized documentation. Here’s a simple breakdown of the 4 key document levels every quality-driven organization must have 👇 🟦 Level-1: Quality Manual This is the top-level document of your entire Quality Management System. It helps everyone understand the “big picture.” 📘 What it includes: Company’s Quality Vision & Mission Core Policies Organizational commitments towards quality Overall structure of the QMS 🔍 Think of it as the “Quality Constitution” of the organization. 🟩 Level-2: Procedures These documents explain how the company operates within the QMS. They provide cross-functional guidance so every department follows the same process. 📄 What they include: Document control procedure Corrective & preventive action (CAPA) Calibration process Operational procedures ⚙️ Procedures ensure every team works in a standardized, uniform manner. 🟧 Level-3: Work Instructions (WI) This is where the real action happens! Work Instructions provide detailed, step-by-step guidance for each task. 🛠️ Used by: Operators Technicians Supervisors 📋 Examples: Welding instructions Assembly steps Inspection procedures 🎯 Work Instructions reduce errors, improve consistency, and increase productivity. 🟨 Level-4: Records / Forms These show proof that the actual work was performed as per the procedures. They provide traceability and help during audits or customer reviews. 📂 Examples: Inspection reports Test certificates Checklists Daily production logs 📝 Records are essential for transparency and accountability. 🚀 Why These 4 Document Levels Matter ✔ Improve consistency in work ✔ Reduce rework and errors ✔ Strengthen audit readiness ✔ Build customer confidence ✔ Support ISO 9001 & other global standards ✔ Create a culture of continuous improvement 📌 Quality is not one person’s responsibility — it is a system. And a strong system begins with strong documentation. #QualityManagement #QMS #ISO9001 #QualityAssurance #QualityControl #ContinuousImprovement #Lean #ManufacturingExcellence #ProcessStandardization #DocumentationManagement #QualityCulture

Documentation protects you… unless it buries your point. Many years ago, I wrote the most detailed audit report of my life. We’re talking 40 pages 🤦🏽♂️ → Charts. → Narratives. → Appendices. → Footnotes. It was bulletproof. At least, I thought so. I handed it to the client expecting appreciation. What I got? “Can you just tell us what you want us to do?” They didn’t care about the 18 pages of background. They didn’t want the full history of the control environment. They wanted direction. Clarity. Action. That’s when it hit me: I wasn’t writing for them. I was writing for me. → To protect myself. → To prove I did the work. → To make it look complete. But complete ≠ compelling. Documentation only matters if someone reads it. Here’s what I learned the hard way. People won't: • Act on what they don’t understand. • Sift through clutter to find the message. • Thank you for being thorough if they feel overwhelmed. So I started writing differently. → Clearer summaries → Shorter sections → Visuals that guide, not distract → And I stopped trying to include 𝘦𝘷𝘦𝘳𝘺𝘵𝘩𝘪𝘯𝘨—        only what mattered Because when your business writing reads like a novel, nobody finishes it. But when it reads like a conversation? → People engage. → They listen. → They act. Struggling to balance clarity with completeness? Our trainings help you communicate in a way that gets results. P.S. Ever write a report so long even 𝘺𝘰𝘶 didn’t finish it?

"My code is well-formatted and well-structured. That makes it self-documenting." Your code may not be as self-documenting as you think, even if you follow the best code standards and practices. If you rely on code alone to tell a story, you may still need one thing - context! If you write the code, you've got to support it and documentation is a self-service option to support anyone who will interact with your code. Think about it this way - your comments and documentation are not for you right now. They're for: 🚀 You in the future, when you've had time away from this code and want to jump back in 🚀 Your teammates who will be working on, reviewing, and supporting the code you write 🚀 The new team member who needs to ramp up quickly 🚀 And so many others! Does everything inside your codebase need a comment? Absolutely not, but here are a few good practices you can implement in your development lifecycle if you're not currently doing so. 1️⃣ Write comments that explain 𝘸𝘩𝘺 not just 𝘩𝘰𝘸 2️⃣ Update documentation regularly. Make it part of your PR acceptance criteria where applicable! 3️⃣ Use documentation files like READMEs and wikis 4️⃣ Provide usage examples, FAQs, and pitfalls in your docs