playbooks

home / skills / toilahuongg / shopify-agents-kit / technical-writing

technical-writing skill

/.claude/skills/technical-writing

This skill helps you write clear internal documentation (READMEs, ADRs, contribution guides) that explains why, front-loads context, and guides future

npx playbooks add skill toilahuongg/shopify-agents-kit --skill technical-writing

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.4 KB
---
name: technical-writing
description: Guide for creating effective internal technical documentation (READMEs, ADRs, Contribution Guides). Use this skill when the user asks to write, refactor, or improve internal project documentation.
---

# Technical Writing for Developers

This skill provides best practices and templates for writing clear, maintainable internal documentation.

## Core Principles

1.  **Audience Awareness**: Write for your teammates (and your future self). Assume they know *how* to code, but not *why* this specific code exists.
2.  **Active Voice**: Use active voice for instructions.
    *   *Bad*: "The server should be started by running..."
    *   *Good*: "Run `npm start` to start the server."
3.  **Single Source of Truth**: Don't duplicate code logic in comments. Explain *why*, not *what*.
4.  **Front-Load Context**: Put the most important information (what is this? how do I run it?) at the top.

## Common Artifacts & Templates

### 1. README.md (Root or Component)

Every significant directory should have a README.

```markdown
# [Project/Component Name]

[One-sentence description of what this is].

## Prerequisite

*   Node.js >= 20
*   [Other dependency]

## Quick Start

```bash
npm install
npm run dev
```

## Architecture

[Brief explanation of how it works. Diagrams are great.]

## Key Concepts

*   **Concept A**: Definition...
*   **Concept B**: Definition...
```

### 2. Architecture Decision Record (ADR)

Use for significant technical decisions.

```markdown
# [Short Title]

*   **Status**: [Proposed | Accepted | Deprecated]
*   **Date**: YYYY-MM-DD
*   **Deciders**: [List names]

## Context

[Describe the problem and constraints.]

## Decision

[Describe what we are doing.]

## Consequences

*   [Positive consequence]
*   [Negative consequence / Trade-off]
```

## Style Guide

*   **Headers**: Use Sentence case for headers (e.g., "Getting started" not "Getting Started").
*   **Code Blocks**: Always specify the language for syntax highlighting (e.g., \`\`\`typescript).
*   **Lists**: Use bullet points for options, numbered lists for steps.
*   **Links**: Use relative links `[Link](./path/to/file)` so they work in the repo browser.

## Review Checklist

Before committing documentation:

- [ ] **Completeness**: did I cover "how to run" and "how to test"?
- [ ] **Freshness**: Did I actually run the commands in a fresh terminal?
- [ ] **Links**: Do all internal links work?
- [ ] **Grammar**: Is it readable? (Use a spell checker).

Overview

This skill guides engineers to create effective internal technical documentation like READMEs, ADRs, and contribution guides. It focuses on clarity, maintainability, and ensuring teammates can quickly understand purpose, setup, and decisions. The guidance is practical and ready to apply to project directories or components.

How this skill works

The skill inspects documentation needs and provides templates, style rules, and a review checklist tailored to internal developer audiences. It recommends what to include at the top of a file, how to structure decision records, and how to keep docs up to date without duplicating code. Use it to draft, refactor, or validate documentation for repositories and components.

When to use it

  • Creating a new project or adding a major component and you need a clear README.
  • Documenting a significant architectural decision that should be tracked over time.
  • Improving an existing README to reduce developer onboarding time.
  • Writing contribution or setup guides for internal collaborators.
  • Preparing documentation for handoff or post-release maintenance.

Best practices

  • Write for your teammates and future you: explain why, not just what.
  • Front-load context: put purpose and quick-start steps at the top.
  • Use active voice and short, actionable commands.
  • Keep a single source of truth: avoid copying code into docs.
  • Use consistent header sentence case and language-specified code blocks.
  • Run commands in a fresh environment before publishing to ensure accuracy.

Example use cases

  • A root README that explains project purpose, prerequisites, quick start, and architecture.
  • A component-level README that describes responsibilities, public API, and local dev steps.
  • An ADR to record choosing a database, including context, decision, and trade-offs.
  • A CONTRIBUTING guide for internal contributors with branching, testing, and PR rules.
  • A checklist run before merging: completeness, links, freshness, and grammar.

FAQ

How long should a README be?

Keep it as short as possible while covering purpose, prerequisites, quick start, and where to find deeper docs; link to detailed topics rather than embedding everything.

When should I create an ADR?

Create an ADR for significant, non-trivial decisions that affect architecture, long-term maintenance, or cross-team constraints; record context, the decision, and consequences.