Formatting Technical Documents

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.

Typography is not an aesthetic choice. It is an accessibility filter. We obsess over inclusive language, yet we ignore inclusive design. We demand people bring their whole selves to work, then hand them documents their brains cannot process. If your strategy document is written in 10 point Times New Roman, fully justified, on a stark white background. You have statistically locked out a massive portion of your workforce before they read the first word. You are not sharing information. You are creating cognitive friction. Corporate documents often act as a dense, impenetrable canopy. Good typography is the trellis that actually supports the reader. Here are 9 ways to build an inclusive visual trellis for your team. 1/ The Serif Ban → The Rule: Default to sans serif fonts like Arial or Lexend. → The Impact: Removes decorative visual noise that exhausts dyslexic readers. 2/ Strict Left Alignment → Rule: Never use justified text. Always align flush left. → Impact: Creates a consistent visual anchor and prevents distracting rivers of white space. 3/ The Contrast Shift → Rule: Use dark grey text on an off white background instead of pure black on pure white. → Impact: Prevents the strobe effect and reduces sensory fatigue. 4/ The 1.5 Spacing → Rule: Set line spacing to 1.5. → Impact: Breaks up the dense wall of text to prevent accidental line skipping. 5/ The Emphasis Strategy → Rule: Use bold weight for emphasis. Avoid italics and underlines. → Impact: Italics deform letter shapes and underlines cut through descending letters, causing cognitive strain. 6/ The Format Reset → Rule: Always paste as plain text to prevent mixed font styles. → Impact: Stops the ransom note effect that distracts the nervous system. 7/ The Agency Protocol → Rule: Share editable documents instead of locked PDFs whenever possible. → Impact: Allows the user to change the font, size, and background to fit their own visual ecosystem. 8/ CamelCase Hashtags → Rule: Capitalize the first letter of each word in a hashtag. → Impact: Ensures screen reading software can actually pronounce the words correctly (#InclusiveDesign). 9/ Descriptive Hyperlinks → Rule: Write descriptive links instead of just saying click here. → Impact: Provides navigational safety and context before the user leaves the current environment. Typography is policy. If your team has to spend energy decoding your message, they have no energy left to understand it. There are so many more nuances we could add here. What is one typography barrier you wish would permanently disappear from corporate communications?

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 )

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.

My take: Good docs for humans are good docs for LLMs. We’ve worked with top technical companies like Sentry , Docker, Inc, and OpenAI to adopt LLMs trained on their documentation. And overwhelmingly, I see that what works well for humans, works well for LLMs. Let me prove it to you. Here’s our official guidance for optimizing technical docs for optimal LLM consumption: - Embrace page structure and hierarchy - Segment documentation by sub-products - Include troubleshooting FAQs - Provide self-contained example code snippets (include imports) - Write text descriptions for images - Define specific acronyms and terms We’ve done this for 100+ teams, and it works. But I read that, and all I can think is “Those are also best practices for writing technical docs, period.” Humans want FAQs. They don’t want to guess what an acronym means. And they want well-defined and structured docs. So…if you’re trying to optimize your docs for an LLM, try to optimize for a human. If you follow the best practices, you’ll create docs that both will love to read.

Most teams think a document is done when it is written. Technical writers know the real work happens after the last word. Here are 6 things technical writers check before calling a document done (that most teams assume are already fine): 1. Is every step actually testable? → Can a real user execute step one and get the result the doc says they will get? → Are the expected outcomes described, or just the actions? → A document full of instructions that cannot be verified is not done. It is a draft with a deadline. 2. Does the structure follow the user's goal or the product's logic? → Is the document ordered around what the user needs to accomplish, or how the product was built? → Do the sections map to tasks, or to features? → Engineers document how it works. Technical writers document how to use it. 3. Are all terms used consistently? → Is one thing called one name, every time, in every step? → Do the terms in the document match the terms in the product interface? → Inconsistent terms create silent confusion that users blame on themselves, not the docs. 4. Has every assumption been removed or explained? → Does any step require knowledge that was never introduced in this document? → Are there prerequisites the reader is expected to know but never told? → Every unexplained assumption is a place where a user quietly stops trusting the product. 5. Does it still make sense without the screenshots? → If every image disappeared, would the text still guide the user through? → Is any critical information only visible in the image and not in the text? → Visuals support. Text carries. If the text cannot stand alone, the document is not done. 6. Would a new user know what to do next? → Is there a clear next action at the end of every section, not just the document? → Are there dead ends where the document stops and leaves the user without direction? → No dead ends. No "now what?" moments. Done is a standard, not a feeling. Most teams call a document done when it is written. Technical writers call it done when it works for the person who has never seen it before. Which of these does your team skip most often? Drop the number (1-6) in the comments. 👇 Save this for the next time someone says the document is ready to publish. Reshare this with a team that works closely with a technical writer. Want more career insights for writers: 1. Follow Joshua Gene Fechter 2. Like the post 3. Repost to your network

How the text appears on your reader’s page or screen matters. Document design, white space, and typography can all reflect on your credibility. These are the silent persuaders: 1⃣ Choosing the Right Fonts When it comes to fonts, the choices you make can impact both the readability and professional appearance of your document. Your goal should be to choose fonts that make your text easy to read while reflecting the serious nature of the material. 2⃣ Styling and Emphasizing Text Italics often serve as a better tool for emphasizing case names and other critical details in your text. Unlike underlining, italics do not interfere with any descenders in the letters, ensuring that the text remains clean and clear. 3⃣ Punctuation and Text Spacing Consider joining the one-space crew if you aren’t a member already. In our digital age, there’s no need to use two spaces after a period, a practice inherited from the typewriter era. Modern fonts provide sufficient space after a period already. 4⃣ Mastering White Space White space, or negative space, refers to the unmarked portions of a page. It’s not empty space, it’s a tool that can enhance your document in several ways. Consider the humble paragraph break: a single line of white space that provides a visual cue of a new thought or idea. 5⃣ Layout and Alignment The layout of your document, including margins, alignment, and line length, can also affect readability. Left-aligned text is typically the easiest to read, as it maintains a consistent starting point for each line. Ensure you have ample margins. Designing your documents requires some work outside of the normal words and sentences that legal writers most often focus on. But form can affect function. So your document’s design is worth investing in. - I’m Joe Regalia, a law professor and legal writing trainer. Follow me and tap the 🔔 so you won't miss any posts.

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

Hey CTOs: Your 23-page brilliant technical manifesto is worthless if no one understands it. Harsh? Maybe. But I've watched countless great ideas die because technical leaders couldn't bridge the communication gap between the server room and the board room. As a CTO, you're not just fighting technical challenges—you're fighting a war of translation. Every day, you're trying to: ➝ Explain complex technical concepts to non-technical executives ➝ Rally your engineering team behind big-picture changes ➝ Get buy-in from people who speak a completely different language I spent years watching CTOs struggle with this (hell, I was one of them). They'd write 27-page technical manifestos nobody read, or try to wing it with vague "vision statements" that put everyone to sleep. But there's a better way. Most CTOs try to solve everything with one massive document. Instead, you need 2 documents: the vision doc and strategy doc. It's not sexy, it's not complicated, but it works. Here they are: 1. The Vision Doc This isn't your typical fluffy vision statement. It's a one-pager (yes, ONE page) that paints a crystal-clear picture of where you're headed. It covers:   ➝ Value proposition ➝ Capabilities needed ➝ Solved constraints ➝ Future challenges Most importantly, it speaks to both business and tech. 2. The Strategy Doc This is your practical roadmap built on 3 pillars: ➝ Diagnosis (the real problem) ➝ Policies (rules to keep you on track) ➝ Action items (your next concrete steps) No 5-year plans here—just clear, executable steps that get you moving. Think of it like this: Your Vision Doc is the destination, your Strategy Doc is the GPS. You need both. Look, the tech landscape is too complex and moves too fast for unclear communication. Having the right technical vision is pointless if everyone else can't understand it. I've got breakdowns on these docs coming in future content because I believe this is the biggest unlock for technical leaders right now. The days of hoping people "just get it" are over. Time to take real steps and level up your communication game.

Every time you start a documentation project, how much time do you spend re-litigating the same decisions? Which words are on the avoid list? How are procedures structured? What is the callout hierarchy? When do you use 'log in' or 'login'? What colors, fonts, or structures do you use? A technical writing design system solves this. One reference that captures your voice and tone rules, content patterns, formatting standards, and word decisions. And it is structured enough that another writer or an AI tool could produce work that fits in with you and your existing documents. Design system is a UX term — Figma, tokens, component libraries. But the concept transfers directly to documentation. And it matters more now: when AI helps you draft or review, it defaults to general conventions. Your design system is how you govern that output. I built one recently using Claude, starting from my own website. The post below walks through exactly what to include, how to prompt for it, and how to use it immediately. It took resources and documents that already existed and created the design system and style guide elements. https://lnkd.in/emsA_2gz