tomevault-io Technical Writing
This skill provides comprehensive guidance for creating clear, effective technical documentation that helps users and developers.
Documentation Structure
The Four Types of Documentation
1. Tutorials (Learning-oriented)
- Goal: Help beginners learn
- Format: Step-by-step lessons
- Example: "Build your first API"
2. How-to Guides (Problem-oriented)
- Goal: Solve specific problems
- Format: Numbered steps
- Example: "How to deploy to production"
3. Reference (Information-oriented)
- Goal: Provide detailed information
- Format: Systematic descriptions
- Example: API reference, configuration options
4. Explanation (Understanding-oriented)
- Goal: Clarify concepts
- Format: Discursive explanations
- Example: Architecture decisions, design patterns
README Structure
# Project Name
Brief description of what the project does (1-2 sentences).
[](link)
[](link)
[](link)
## Features
- Feature 1
- Feature 2
- Feature 3
## Quick Start
```bash
# Installation
npm install project-name
# Usage
npx project-name init
Prerequisites
- Node.js 18+
- PostgreSQL 14+
- Redis 7+
Installation
Using npm
npm install project-name
Using yarn
yarn add project-name
From source
git clone https://github.com/user/project.git
cd project
npm install
npm run build
Configuration
Create a .env file:
DATABASE_URL=postgresql://user:password@localhost:5432/db
API_KEY=your_api_key
Usage
Basic Example
import { createClient } from 'project-name';
const client = createClient({
apiKey: process.env.API_KEY,
});
const result = await client.doSomething();
console.log(result);
Advanced Example
[More complex example with explanations]
API Reference
See API.md for complete API documentation.
Contributing
See CONTRIBUTING.md for guidelines.
License
MIT © [Author Name]
Support
- Documentation: https://docs.example.com
- Issues: https://github.com/user/project/issues
- Discussions: https://github.com/user/project/discussions
## Clear Writing Principles
### Use Active Voice
```markdown
❌ Passive: The data is validated by the function.
✅ Active: The function validates the data.
❌ Passive: Errors should be handled by your application.
✅ Active: Your application should handle errors.
Use Simple Language
❌ Complex: Utilize the aforementioned methodology to instantiate a novel instance.
✅ Simple: Use this method to create a new instance.
❌ Jargon: Leverage our SDK to synergize with the API ecosystem.
✅ Clear: Use our SDK to connect to the API.
Be Concise
❌ Wordy: In order to be able to successfully complete the installation process,
you will need to make sure that you have Node.js version 18 or higher installed
on your system.
✅ Concise: Install Node.js 18 or higher.
❌ Redundant: The function returns back a response.
✅ Concise: The function returns a response.
Use Consistent Terminology
❌ Inconsistent:
- Create a user
- Add an account
- Register a member
(All referring to the same action)
✅ Consistent:
- Create a user
- Update a user
- Delete a user
Code Example Best Practices
Complete, Runnable Examples
// ❌ BAD - Incomplete example
user.save();
// ✅ GOOD - Complete example
import { User } from './models';
async function createUser() {
const user = new User({
email: 'user@example.com',
name: 'John Doe',
});
await user.save();
console.log('User created:', user.id);
}
createUser();
Show Expected Output
// Calculate fibonacci number
function fibonacci(n: number): number {
if (n <= 1) return n;
return fibonacci(n - 1) + fibonacci(n - 2);
}
console.log(fibonacci(10));
// Output: 55
Highlight Important Parts
// Authenticate user with JWT
app.post('/api/auth/login', async (req, res) => {
const { email, password } = req.body;
const user = await User.findOne({ email });
if (!user) {
return res.status(401).json({ error: 'Invalid credentials' });
}
// 👇 Important: Always use bcrypt for password comparison
const isValid = await bcrypt.compare(password, user.passwordHash);
if (!isValid) {
return res.status(401).json({ error: 'Invalid credentials' });
}
const token = generateToken(user);
res.json({ token });
});
Provide Context
// ❌ BAD - No context
await client.query('SELECT * FROM users');
// ✅ GOOD - With context
// Fetch all active users who logged in within the last 30 days
const activeUsers = await client.query(`
SELECT id, email, name, last_login
FROM users
WHERE status = 'active'
AND last_login > NOW() - INTERVAL '30 days'
ORDER BY last_login DESC
`);
Tutorial Structure
Learning Progression
1. Introduction (2-3 sentences)
- What will users learn?
- Why is it useful?
2. Prerequisites
- Required knowledge
- Required tools
- Time estimate
3. Step-by-Step Instructions
- Number each step
- One concept per step
- Show results after each step
4. Next Steps
- Links to related tutorials
- Advanced topics
- Additional resources
Tutorial Example
# Building a REST API with Express
In this tutorial, you'll build a REST API for managing a todo list.
You'll learn how to create routes, handle requests, and connect to a database.
**Time**: 30 minutes
**Level**: Beginner
## Prerequisites
- Node.js 18+ installed
- Basic JavaScript knowledge
- Code editor (VS Code recommended)
## Step 1: Set Up Project
Create a new project directory and initialize npm:
```bash
mkdir todo-api
cd todo-api
npm init -y
Install Express:
npm install express
You should see express added to your package.json.
Step 2: Create Basic Server
Create index.js:
const express = require('express');
const app = express();
app.get('/', (req, res) => {
res.json({ message: 'Hello, World!' });
});
const PORT = 3000;
app.listen(PORT, () => {
console.log(`Server running on http://localhost:${PORT}`);
});
Run the server:
node index.js
Visit http://localhost:3000 in your browser. You should see:
{ "message": "Hello, World!" }
Step 3: Add Todo Routes
[Continue with more steps...]
What You Learned
- How to set up an Express server
- How to create REST API routes
- How to connect to a database
Next Steps
## API Documentation Patterns
### Endpoint Documentation
```markdown
## Create User
Creates a new user account.
**Endpoint**: `POST /api/v1/users`
**Authentication**: Not required
**Request Body**:
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User's email address (must be valid) |
| password | string | Yes | Password (min 8 characters) |
| name | string | Yes | User's full name (max 100 characters) |
**Example Request**:
```bash
curl -X POST https://api.example.com/v1/users \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePass123",
"name": "John Doe"
}'
Success Response (201 Created):
{
"id": "user_abc123",
"email": "user@example.com",
"name": "John Doe",
"createdAt": "2025-10-16T10:30:00Z"
}
Error Responses:
400 Bad Request - Invalid input:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid email address",
"field": "email"
}
}
409 Conflict - Email already exists:
{
"error": {
"code": "EMAIL_EXISTS",
"message": "Email address already registered"
}
}
Rate Limit: 5 requests per minute
### Function/Method Documentation
```typescript
/**
* Calculates the total price of items including tax.
*
* @param items - Array of items to calculate total for
* @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
* @returns Total price including tax
*
* @throws {Error} If items array is empty
* @throws {Error} If taxRate is negative
*
* @example
* ```typescript
* const items = [
* { price: 10, quantity: 2 },
* { price: 15, quantity: 1 }
* ];
* const total = calculateTotal(items, 0.08);
* console.log(total); // 37.80
* ```
*/
function calculateTotal(
items: Array<{ price: number; quantity: number }>,
taxRate: number
): number {
if (items.length === 0) {
throw new Error('Items array cannot be empty');
}
if (taxRate < 0) {
throw new Error('Tax rate cannot be negative');
}
const subtotal = items.reduce(
(sum, item) => sum + item.price * item.quantity,
0
);
return subtotal * (1 + taxRate);
}
Changelog Best Practices
Keep a Changelog Format
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Added
- New feature X for Y use case
### Changed
- Improved performance of Z operation
### Fixed
- Fixed bug where A caused B
## [2.1.0] - 2025-10-16
### Added
- User profile avatars (#123)
- Email notification settings (#125)
- Two-factor authentication support (#130)
### Changed
- Updated UI for settings page (#124)
- Improved API response times by 40% (#128)
### Deprecated
- `oldFunction()` will be removed in v3.0 - use `newFunction()` instead
### Fixed
- Fixed memory leak in session management (#126)
- Corrected timezone handling in reports (#129)
### Security
- Updated dependencies to patch security vulnerabilities (#127)
## [2.0.0] - 2025-09-01
### Added
- Complete redesign of dashboard
- GraphQL API support
### Changed
- **BREAKING**: Renamed `create_user` to `createUser` for consistency
- **BREAKING**: Changed date format from `DD/MM/YYYY` to ISO 8601
### Removed
- **BREAKING**: Removed deprecated v1 API endpoints
[Unreleased]: https://github.com/user/project/compare/v2.1.0...HEAD
[2.1.0]: https://github.com/user/project/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/user/project/releases/tag/v2.0.0
Version Numbering
Semantic Versioning (MAJOR.MINOR.PATCH):
- MAJOR: Breaking changes (2.0.0 → 3.0.0)
- MINOR: New features, backwards compatible (2.0.0 → 2.1.0)
- PATCH: Bug fixes, backwards compatible (2.0.0 → 2.0.1)
Markdown Formatting
Headers
# H1 - Main title
## H2 - Section
### H3 - Subsection
#### H4 - Sub-subsection
Emphasis
**Bold text** or __bold__
*Italic text* or _italic_
***Bold and italic***
~~Strikethrough~~
`Inline code`
Lists
Unordered list:
- Item 1
- Item 2
- Nested item
- Another nested item
- Item 3
Ordered list:
1. First item
2. Second item
1. Nested item
2. Another nested item
3. Third item
Task list:
- [x] Completed task
- [ ] Incomplete task
Links and Images
[Link text](https://example.com)
[Link with title](https://example.com "Title text")
Code Blocks
Inline code: `const x = 5;`
Code block:
```javascript
function greet(name) {
console.log(`Hello, ${name}!`);
}
```
With line highlighting:
```javascript {2}
function greet(name) {
console.log(`Hello, ${name}!`); // This line is highlighted
}
```
Tables
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1 | Data | More |
| Row 2 | Data | More |
Alignment:
| Left | Center | Right |
|:-----|:------:|------:|
| L | C | R |
Blockquotes
> Single line quote
> Multi-line
> quote with
> several lines
> **Note**: Important information
Admonitions
> **⚠️ Warning**: This action cannot be undone.
> **💡 Tip**: Use keyboard shortcuts to speed up your workflow.
> **🚨 Danger**: Never commit secrets to version control.
> **ℹ️ Info**: This feature requires Node.js 18+.
Diagrams and Visuals
When to Use Diagrams
Use diagrams for:
- System architecture
- Data flow
- Process flows
- Component relationships
- Complex concepts
Don't use diagrams for:
- Simple concepts (text is better)
- Things that change frequently
- Content that can be code
Mermaid Diagrams
```mermaid
graph TD
A[User Request] --> B{Authenticated?}
B -->|Yes| C[Process Request]
B -->|No| D[Return 401]
C --> E[Return Response]
```
```mermaid
sequenceDiagram
Client->>API: POST /users
API->>Database: INSERT user
Database-->>API: User created
API->>Email: Send welcome email
API-->>Client: 201 Created
```
ASCII Diagrams
┌─────────────┐ ┌──────────────┐ ┌──────────┐
│ Client │─────▶│ API Server │─────▶│ Database │
│ (Browser) │◀─────│ (Express) │◀─────│ (Postgres)│
└─────────────┘ └──────────────┘ └──────────┘
Progressive Disclosure
Start Simple, Add Details
## Installation
Install via npm:
```bash
npm install package-name
Install from source
git clone https://github.com/user/package.git
cd package
npm install
npm run build
npm link
Install specific version
npm install package-name@2.1.0
Install with peer dependencies
npm install package-name react react-dom
Organize by Skill Level
## Quick Start (Beginner)
Get up and running in 5 minutes:
[Simple example]
## Advanced Usage
For experienced users:
[Complex example]
## Expert Topics
Deep dive into internals:
[Very advanced example]
User-Focused Language
Address the Reader
❌ Impersonal: The configuration file should be updated.
✅ Personal: Update your configuration file.
❌ Distant: One must install the dependencies.
✅ Direct: Install the dependencies.
Use "You" Not "We"
❌ We: Now we'll create a new user.
✅ You: Now you'll create a new user.
❌ We: We recommend using TypeScript.
✅ You: We recommend you use TypeScript.
Be Helpful
❌ Vague: An error occurred.
✅ Helpful: Connection failed. Check your network and try again.
❌ Blaming: You entered invalid data.
✅ Helpful: The email field requires a valid email address (e.g., user@example.com).
Avoiding Jargon
Define Technical Terms
❌ Assumes knowledge:
"Use the ORM to query the RDBMS."
✅ Explains terms:
"Use the ORM (Object-Relational Mapping tool) to query the database.
An ORM lets you interact with your database using code instead of SQL."
Use Common Words
❌ Technical jargon:
"Leverage the API to facilitate data ingestion."
✅ Plain English:
"Use the API to import data."
Version Documentation
Document Version Changes
## Version Compatibility
| Version | Node.js | Features |
|---------|---------|----------|
| 3.x | 18+ | Full feature set |
| 2.x | 16+ | Legacy API (deprecated) |
| 1.x | 14+ | No longer supported |
## Upgrading from 2.x to 3.x
### Breaking Changes
**1. Renamed functions**
```typescript
// v2.x
import { create_user } from 'package';
// v3.x
import { createUser } from 'package';
2. Changed date format
Dates now use ISO 8601 format:
- Old:
01/15/2025 - New:
2025-01-15T00:00:00Z
Migration Guide
Update imports:
# Run this command to update your code npx package-migrate-v3Update date handling:
// Before const date = '01/15/2025'; // After const date = '2025-01-15T00:00:00Z';Test thoroughly before deploying.
## Documentation Checklist
**Before Writing**:
- [ ] Who is the audience (beginner/intermediate/expert)?
- [ ] What do they need to accomplish?
- [ ] What do they already know?
**While Writing**:
- [ ] Use active voice
- [ ] Use simple language
- [ ] Be concise
- [ ] Provide examples
- [ ] Show expected output
**After Writing**:
- [ ] Read it aloud
- [ ] Have someone else review it
- [ ] Test all code examples
- [ ] Check all links
- [ ] Spell check
## When to Use This Skill
Use this skill when:
- Writing project READMEs
- Creating API documentation
- Writing tutorials
- Documenting code
- Creating user guides
- Writing changelogs
- Contributing to open source
- Creating internal documentation
- Writing blog posts about technical topics
- Training others on technical writing
---
**Remember**: Good documentation is empathetic. Always write for the person reading your docs at 2 AM who just wants to get their code working. Be clear, be helpful, and be kind.
---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/webdevtodayjason) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-12 -->