Documentation Writing Standards
Windsurf.windsurfrulesCoding
Rules for writing clear technical docs: README structure, JSDoc, inline comments, and ADRs.
Get this skill
Add the skill file with the CLI, by hand, or over MCP.Save this to your project or home directory so Windsurf can load it.
npx goodprompts add documentation-writing-standardsSaves to
./.windsurfrulesnpx goodprompts add documentation-writing-standardsSaves to
./.windsurfrulesSkill file
.windsurfrules1,507 characters# Documentation Standards
## README Structure
Every project README must include (in order):
1. Project name + one-line description
2. Quick start (3 commands max to get running)
3. Prerequisites (runtime, tools, env vars)
4. Architecture overview (high-level diagram or description)
5. Development workflow (build, test, deploy)
6. Contributing guidelines (or link to CONTRIBUTING.md)
## Code Comments
- Comment WHY, never WHAT. The code says what; comments say why.
- Delete commented-out code. Git remembers.
- Use TODO with a ticket number: `// TODO(GP-123): handle pagination`.
- Use JSDoc for public APIs: params, returns, throws, examples.
- No comments on self-explanatory code. `// increment counter` on `count++` is noise.
## API Documentation
- Document every public endpoint with: description, params, response, errors.
- Include request/response examples with realistic data.
- Document rate limits, auth requirements, and pagination.
- Keep docs next to code (co-location), not in a separate wiki.
## Architecture Decision Records (ADRs)
When making a significant technical decision:
```markdown
# ADR-NNN: Title
## Status: Accepted | Deprecated | Superseded by ADR-XXX
## Context
What situation or problem prompted this decision?
## Decision
What did we decide and why?
## Consequences
What are the positive and negative effects?
```
## Changelog
- Use Keep a Changelog format.
- Categories: Added, Changed, Deprecated, Removed, Fixed, Security.
- Link to PRs/issues for traceability.