alextiannus/markdown-writer

Markdown Writer

Overview

Generate well-structured technical documentation in Markdown format. Covers READMEs, API docs, how-to guides, changelogs, and any structured technical content using documentation best practices.

Instructions

When a user asks you to write documentation or Markdown content, follow these steps:

Step 1: Determine the document type

| Type | Purpose | Audience | |------|---------|----------| | README | Project introduction, setup, usage | New users and contributors | | API docs | Endpoint reference with parameters and responses | Developers integrating the API | | How-to guide | Step-by-step walkthrough for a specific task | Users solving a problem | | Tutorial | Learning-oriented, progressive complexity | Beginners | | Reference | Complete technical specification | Experienced users | | Changelog | Version history with changes | All users | | ADR | Architecture decision record | Team members |

Step 2: Gather information

Before writing, collect:

• Read the codebase to understand what the project does
• Check existing docs for tone and style
• Identify the target audience (beginner, intermediate, expert)
• Note any prerequisites or dependencies
• Find code examples that demonstrate real usage

Step 3: Write using these templates

README template:

# Project Name

One-line description of what this project does.

## Installation

\`\`\`bash
npm install project-name
\`\`\`

## Quick Start

\`\`\`javascript
const lib = require('project-name');
lib.doSomething();
\`\`\`

## Usage

### Feature One
Explain the feature with a code example.

### Feature Two
Explain the feature with a code example.

## API Reference

### `functionName(param1, param2)`
- `param1` (string): Description
- `param2` (number, optional): Description. Default: `10`
- Returns: `Promise<Result>`

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `port` | number | `3000` | Server port |
| `debug` | boolean | `false` | Enable debug logging |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT

API endpoint documentation:

### Create a User

\`\`\`
POST /api/users
\`\`\`

**Request body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Full name |
| `email` | string | Yes | Email address |
| `role` | string | No | Default: `"user"` |

**Example request:**
\`\`\`bash
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "[email protected]"}'
\`\`\`

**Response (201 Created):**
\`\`\`json
{
  "id": 42,
  "name": "Jane Doe",
  "email": "[email protected]",
  "role": "user",
  "created_at": "2024-03-15T10:30:00Z"
}
\`\`\`

**Error responses:**
| Status | Description |
|--------|-------------|
| `400` | Invalid request body |
| `409` | Email already exists |

How-to guide template:

# How to Deploy to Production

## Prerequisites
- Docker 20+ installed
- AWS CLI configured with credentials

## Steps

### 1. Build the image
\`\`\`bash
docker build -t myapp:latest .
\`\`\`

### 2. Push to registry
\`\`\`bash
docker tag myapp:latest ecr.example.com/myapp:latest
docker push ecr.example.com/myapp:latest
\`\`\`

### 3. Deploy
\`\`\`bash
aws ecs update-service --cluster prod --service myapp --force-new-deployment
\`\`\`

## Troubleshooting

**Build fails with "out of memory":**
Increase Docker memory limit to at least 4GB in Docker Desktop settings.

**Deployment times out:**
Check that the health check endpoint returns 200 within 30 seconds.

Step 4: Review and polish

Checklist before delivering:

• [ ] Title clearly states what the document covers
• [ ] Code examples are copy-paste ready (no placeholders that would break)
• [ ] Tables are used for structured data instead of long prose
• [ ] Headings follow a logical hierarchy (H1 > H2 > H3)
• [ ] Links are included for external references
• [ ] Prerequisites are listed before steps that require them

Examples

Example 1: Generate a README for a CLI tool

User request: "Write a README for my Node.js CLI tool that converts images"

Output structure:

# img-convert

Fast image format conversion from the command line.

## Installation
  npm install -g img-convert

## Usage
  img-convert input.png output.webp
  img-convert --quality 80 --resize 800x600 photo.jpg photo.webp
  img-convert --batch src/*.png --format webp --outdir dist/

## Options (table with flag, type, default, description)

## Supported Formats (table)

## Examples (3-4 real usage scenarios)

## Contributing

## License

Example 2: Document an existing API from code

User request: "Generate API docs from my Express routes"

Process:

1. Read all route files to identify endpoints
2. Extract HTTP method, path, middleware, request/response types
3. Generate one section per endpoint with method, path, parameters, body, response, and example

Output structure:

# API Reference

Base URL: `https://api.example.com/v1`
Authentication: Bearer token in Authorization header

## Users
### GET /users - List all users
### GET /users/:id - Get a user
### POST /users - Create a user
### PUT /users/:id - Update a user
### DELETE /users/:id - Delete a user

## Orders
### GET /orders - List orders
### POST /orders - Create an order

Each endpoint includes parameters table, example request, and example response.

Guidelines

• Write for the reader, not yourself. Assume the reader has never seen this project.
• Start with the most common use case, not edge cases.
• Every code example must be complete enough to run. Do not leave out imports or setup.
• Use tables for anything with more than 3 key-value pairs. Tables are faster to scan than paragraphs.
• Keep paragraphs short (3-4 sentences max). Use bullet points for lists of items.
• Link to related documents rather than duplicating content.
• Use consistent formatting: backticks for code, bold for UI elements, italics sparingly.
• For API docs, always include at least one complete request/response example per endpoint.
• Version documentation alongside code. If the API changes, the docs must change.
• Do not document obvious things. "The name field is the name" adds no value.