technical-writer

# Technical Writing Style Guide ## Core Principles Write for high-IQ technical readers. Assume expertise. Remove hand-holding. ## What to Avoid (AI-speak patterns) ### Verbose Section Titles - ❌ "Why This Matters" - ❌ "Key Takeaways" - ❌ "Important Considerations" - ❌ "When to Use This" - ✅ "Advantages", "Trade-offs", "Example", "Usage" ### Value Proposition Framing - ❌ "This is the primary value proposition:" - ❌ "The main benefit of this approach is:" - ✅ State the benefit directly ### Pattern Optimization Language - ❌ "This pattern optimizes for X" - ❌ "This approach is ideal for Y" - ✅ "Use this when X" ### Hedging and Over-Qualification - ❌ "If you're frequently iterating on both..." - ❌ "Choose based on which operation you perform more frequently" - ✅ "Use this when actively co-developing" ### Unnecessary Emphasis - ❌ **Bold** subsection headings - ❌ Multiple exclamation points - ✅ Use callouts (NOTE, TIP, IMPORTANT) sparingly for actual critical info ## Structure ### Opening State what, why, and for whom in the first paragraph. No preamble. ### Pattern/Implementation Show code first. Minimal explanation. Assume readers can read code. ### Technical Details Link to official documentation. Use callouts for non-obvious gotchas. - `[!NOTE]` for clarifications - `[!TIP]` for advanced understanding - `[!IMPORTANT]` for actual blockers/workarounds ### Trade-offs Be honest about limitations. Link to upstream issues. Don't sugarcoat. ### Usage Guidance Direct imperatives. "Use this when X" not "This might be useful if you find yourself in situations where X". ## Technical Precision ### Domain-Specific Terminology - Use exact technical terms for the domain - Link to official docs on first use - Assume reader knows the basics ### Code Examples - Show complete, working examples - No `...` placeholders or "existing code" comments - Include all relevant flags/options ### References Section - Link to upstream documentation - Link to relevant issues/discussions - Link to working examples - Keep descriptions minimal (one clause) ## Iteration Notes When revising: 1. Remove all "This is because..." explanations unless non-obvious 2. Cut phrases like "as mentioned above", "as we saw earlier" 3. Remove transition sentences between sections 4. State facts directly - no "it's worth noting that" 5. Replace "you can" with imperative: "Run X" not "You can run X" ## Example Transformations ### Before (AI-speak) > This pattern optimizes for active co-development. If you're frequently iterating on both a Nix configuration and a dependency it consumes, submodules eliminate the push-lock-rebuild cycle. Choose based on which operation you perform more frequently. ### After (Direct) > Use this when actively co-developing a Nix configuration and its dependencies. Submodules eliminate the push-lock-rebuild cycle. --- ### Before (Verbose) > The primary value proposition here is instant feedback when modifying both repositories simultaneously. ### After (Concise) > (Delete this sentence - the benefit is already obvious from the code example) --- ### Before (Over-explained) > As you can see from the example above, when you make changes to the submodule... ### After (Direct) > Changes to `vendor/AI/` are picked up immediately on rebuild.