Tips for Improving Technical 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.

Why Most IT Service Desks Fail at Knowledge Management (And How to Make It Work) Your IT team has a knowledge base. But does anyone actually use it? The Problem Most IT service desks treat knowledge management like a one-time project. They build a wiki, dump a few outdated articles into it, and hope for the best. The result? A ghost town of forgotten documentation while techs keep solving the same issues from scratch. How to Make It Work 1. Make Knowledge Management a Habit Why it matters: If updating documentation isn’t part of daily workflows, it won’t happen. Here’s how: ↳ Require techs to update or verify articles when resolving tickets. ↳ Set clear ownership for maintaining knowledge content. ↳ Make it a KPI—if it’s not measured, it won’t improve. 2. Stop Overcomplicating Articles Why it matters: Nobody wants to read a novel to reset a password. Here’s how: ↳ Keep articles short and to the point. ↳ Use step-by-step formats with clear headings. ↳ Add images, GIFs, or short videos for clarity. 3. Kill the Junk Articles Why it matters: Old, inaccurate, or duplicate articles create more problems than they solve. Here’s how: ↳ Regularly audit and remove outdated content. ↳ Set expiration dates on articles that need reviews. ↳ Encourage feedback—if an article doesn’t help, fix or delete it. 4. Make Search Actually Work Why it matters: If techs can’t find the right article in seconds, they won’t bother looking. Here’s how: ↳ Use keywords that match what people actually type in. ↳ Structure titles like a Google search (e.g., “How to fix VPN issues”). ↳ Keep the search bar prominent—not buried under 12 clicks. 5. Reward People for Using It Why it matters: People ignore what they don’t see value in. Here’s how: ↳ Recognize techs who contribute high-quality knowledge. ↳ Gamify it—leaderboards, badges, and small incentives work wonders. ↳ Show success metrics (time saved, tickets reduced) to prove impact. A good knowledge base saves time, reduces escalations, and keeps IT from answering the same question 500 times. But only if it’s built right. What’s the worst knowledge base fail you’ve seen? ♻️ Repost to save an IT team from knowledge management nightmares. 🔔 Follow Bob Roark for more ITSM insights.

🌟 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.

Software documentation isn't guesswork. It's a process. But most teams skip the steps that make documentation actually work. Here are 7 steps technical writers use to write software documentation: 1. Know Who You're Writing For → Answer: Who's reading? What do they know? What problem are they solving? → Create user personas to guide your writing 2. Start With Questions, Not Answers → List every question your reader might ask → Better questions = better documentation 3. Build the Outline First → Map the structure before drafting → Prevents unnecessary detail or skipped steps 4. Go to the Source → Interview SMEs, review existing docs, test the product → Every assumption is a potential error 5. Write for Clarity, Not Perfection → Clear, concise, direct → Polish later, get information down first 6. Use Visuals Where Words Fall Short → Screenshots for UI, diagrams for architecture, flowcharts for decisions → If three paragraphs can be replaced with a five-second diagram, use the diagram 7. Edit With Fresh Eyes → Review for accuracy, get feedback, test it → Documentation isn't done until someone else can follow it Writing software documentation isn't about following every rule. It's about having a reliable process that works. Which step do you follow most consistently? Drop the number (1-7) in the comments. 👇 Save this for your next documentation project. Reshare with a technical writer building their process. 📰 Want weekly frameworks for technical writers? Subscribe to my newsletter (link in comments). Want more career insights for writers: 1. Follow Joshua Gene Fechter 2. Like the post 3. Repost to your network

I scanned 2.8 GB of QMS documents in a week. Then, shared this uncomfortable truth with the QA director: More documentation ≠ a better quality management system. Most companies drown in paperwork that doesn’t actually improve quality. Want to fix that? Start here: 1️⃣ Kill redundant SOPs. Do you really need three SOPs saying the same thing Nope. Review processes and cut the fluff. 2️⃣ Make SOPs usable. Stop writing mini-novels. Focus on clarity and actionability—less “legalese,” more “get it done.” 3️⃣ Use risk-based thinking. Not everything needs a procedure. Focus on the high-impact stuff that actually matters. 4️⃣ Streamline approvals. Empower the right people to finalize documents. Endless review cycles = wasted time. 5️⃣ Go digital. Why deal with stacks of paper when workflows can live in a streamlined system? Go for a lightweight eQMS and automate what you can. The goal isn’t more documents—it’s lean, effective processes that drive compliance AND improvement. QA people have a great opportunity here to be creative, which is quite underrated. What would you add?

Don’t fall for this common trap: Putting off the documentation until the end of a project. It just won’t get done if you do. Or it won’t be as detailed or complete as it should be. If you document your code along the way, you’re much more likely to remember important details and it’ll actually help you get the project done faster. What does documentation look like? — Comments on your CTEs describing why you needed one — Comments documenting any changes from the norm — Decriptions of functions you create — Updating the ticket with time spent and current tasks — My favorite: a log at the top of every query and script that outlines any changes people come in and make through the lifecycle of the code. Spend the time to document along the way. Trust me, I’m not good at remembering to do this 🤦🏻♂️ I did the bare minimum documentation before leaving on vacation this week. I don’t look forward to jogging my brain on Monday morning 😂