technical-writing

The technical-writing skill provides a structured framework for creating high-quality, professional software engineering content. It is designed for developers, QA professionals, and technical leads who need to communicate complex concepts, report bugs effectively, or publish long-form technical articles. By adhering to a rigorous set of core principles, this skill ensures that documentation is not just readable, but actionable and value-driven, acting as a force multiplier for knowledge sharing within software teams.

• Principles-based drafting: Lead with value, demonstrate with concrete evidence, and structure content for rapid scanning.

• Content optimization: Utilize built-in editing checklists to remove corporate speak, hedge words, and unnecessary fillers.

• Targeted communication: Tailor technical narratives specifically for developer, QA/QE, and leadership audiences to ensure optimal impact.

• Standardized formatting: Implement proven structures for blog posts, documentation, and technical tutorials to maintain consistency.

• Seamless integration: Automate documentation generation and quality reviews using connected agents like the qe-quality-analyzer and qe-api-contract-validator.

• Markdown efficiency: Leverage consistent document templates and memory namespaces for long-term project knowledge storage.

• When writing, always prioritize the reader's takeaways: what will they learn or gain by reading this piece?

• Always support technical claims with real-world examples, metrics, code snippets, or logs rather than abstract descriptions.

• Ruthlessly cut sentences that do not serve a specific purpose or provide additional insight.

• Be transparent regarding technical trade-offs; acknowledge that every architectural decision has consequences and document them honestly.

• Use the provided before-and-after transformation patterns to refine draft content into high-impact, professional technical communication.

• Ensure all technical examples, especially code blocks, are verified for correctness before final publication to maintain trust.

• Consider audience context: developers need implementation details and code; QA teams need strategies and heuristics; leadership needs business impact and metrics.