tomevault-io Documentation Writer
When to use this skill
- Writing or improving a README
- Documenting API endpoints
- Creating architecture or design docs
- Writing setup/installation guides
- Adding JSDoc/docstrings to code
- Creating migration guides for breaking changes
README structure
A good README answers: What is this? How do I use it? How do I contribute?
# Project Name
Brief description (1-2 sentences). What does it do and who is it for?
## Quick Start
\`\`\`bash
npm install project-name
\`\`\`
\`\`\`typescript
import { something } from 'project-name';
const result = something('hello');
\`\`\`
## Features
- Feature one — brief explanation
- Feature two — brief explanation
- Feature three — brief explanation
## Installation
\`\`\`bash
# npm
npm install project-name
# yarn
yarn add project-name
\`\`\`
### Prerequisites
- Node.js >= 18
- PostgreSQL >= 14
## Usage
### Basic usage
[Code example with explanation]
### Configuration
[Configuration options with defaults]
### Advanced usage
[More complex examples]
## API Reference
### `functionName(param1, param2)`
Description of what the function does.
**Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| `param1` | `string` | — | Description |
| `param2` | `number` | `10` | Description |
**Returns:** `Promise<Result>` — Description
**Example:**
\`\`\`typescript
const result = await functionName('hello', 5);
\`\`\`
## Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DATABASE_URL` | Yes | — | PostgreSQL connection string |
| `PORT` | No | `3000` | Server port |
| `LOG_LEVEL` | No | `info` | Logging level |
## Development
\`\`\`bash
git clone https://github.com/org/repo.git
cd repo
npm install
npm run dev
\`\`\`
### Running tests
\`\`\`bash
npm test
npm run test:coverage
\`\`\`
## Contributing
[Brief contribution guidelines or link to CONTRIBUTING.md]
## License
[License type] — see [LICENSE](LICENSE)
API documentation
OpenAPI / Swagger
paths:
/users:
post:
summary: Create a new user
tags: [Users]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [name, email]
properties:
name:
type: string
example: "Alice"
email:
type: string
format: email
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description: Validation error
Inline API docs (JSDoc)
/**
* Creates a new user account.
*
* @param input - User creation data
* @returns The created user with generated ID
* @throws {ValidationError} If input fails validation
* @throws {ConflictError} If email already exists
*
* @example
* ```typescript
* const user = await createUser({ name: 'Alice', email: 'alice@example.com' });
* console.log(user.id); // "usr_abc123"
* ```
*/
async function createUser(input: CreateUserInput): Promise<User> {
Python docstrings
def create_user(name: str, email: str) -> User:
"""Create a new user account.
Args:
name: The user's display name (1-100 characters).
email: A valid email address. Must be unique.
Returns:
The created User object with generated ID.
Raises:
ValidationError: If name or email is invalid.
ConflictError: If email already exists.
Example:
>>> user = create_user("Alice", "alice@example.com")
>>> print(user.id)
'usr_abc123'
"""
Documentation principles
- Write for your audience: Beginner guide ≠ API reference
- Start with examples: Show, then explain
- Keep it current: Outdated docs are worse than no docs
- Be concise: Short paragraphs, bullet points, tables
- Use code blocks: Always specify the language for syntax highlighting
- Document the why: Comments explain why, not what
When to add inline comments
// GOOD: Explains non-obvious business logic
// Orders placed after 2pm EST ship next business day
const cutoffHour = 14;
// GOOD: Explains workaround
// setTimeout(0) needed because DOM hasn't updated yet after React state change
setTimeout(() => scrollToBottom(), 0);
// BAD: Restates the code
// Set count to 0
let count = 0;
// BAD: Explains obvious code
// Loop through users
for (const user of users) { ... }
Checklist
- README has quick start, installation, usage, and API sections
- Code examples are tested and work
- Environment variables documented
- Public API functions have JSDoc/docstrings
- Complex logic has explanatory comments (why, not what)
- Setup instructions are complete (a new developer can follow them)
- Breaking changes have migration guides
- No stale/outdated documentation
Source: asgarovf/locusai — distributed by TomeVault.