writing

whyleonardo's avatarfrom whyleonardo

Guidelines for clear technical writing and documentation.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 8, 2026
[Technical Writing]

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for high-quality technical documentation and software engineering communication. It streamlines the creation of clear, concise, and professional content by offering standardized guidelines for READMEs, API documentation, commit messages, and PR descriptions, ultimately improving project maintainability and team collaboration.

Use Cases

  • Standardizing project documentation: Use the structured templates to create professional README files and API references that are easy for developers to navigate.
  • Improving code maintainability: Apply the 'why, not what' commenting philosophy to ensure codebase logic is understandable for future contributors.
  • Streamlining development workflows: Implement the conventional commit message format and PR description standards to facilitate smoother code reviews and automated changelogs.
  • Enhancing technical communication: Utilize general writing principles like active voice and audience-centricity to transform complex technical concepts into accessible documentation.
namewriting
descriptionGuidelines for clear technical writing and documentation.

Technical Writing Standards

General Principles

  • Be concise - every word should earn its place
  • Write for your audience (developer, user, stakeholder)
  • Use active voice over passive voice
  • Front-load important information
  • One idea per paragraph

Documentation Structure

  • Start with a brief summary/overview
  • Use headers to create scannable structure
  • Include practical examples
  • End with next steps or related resources
  • Keep docs close to the code they describe

Code Comments

  • Explain "why", not "what"
  • Comment on non-obvious decisions
  • Keep comments up-to-date with code
  • Use TODO/FIXME with context and ticket numbers
  • Avoid commented-out code (use version control)

Commit Messages

Format:

<type>(<scope>): <subject>

<body>

Types: feat, fix, docs, style, refactor, test, chore

  • Subject: imperative mood, max 50 chars, no period
  • Body: wrap at 72 chars, explain what and why

PR Descriptions

  • Summarize the change in 1-2 sentences
  • List what changed and why
  • Include testing instructions
  • Link to related issues/tickets
  • Add screenshots for UI changes

README Structure

  1. Project name and brief description
  2. Quick start / Installation
  3. Usage examples
  4. Configuration options
  5. Contributing guidelines
  6. License

API Documentation

  • Document all public endpoints/methods
  • Include request/response examples
  • Specify required vs optional parameters
  • Document error responses
  • Keep examples up-to-date and tested