Good documentation helps users succeed. This guide covers practical techniques for writing documentation that is clear, findable, and useful — whether you're documenting an API, a product, or an internal tool.

Know Your Audience

Before writing, identify who you're writing for and what they need:

Write for one audience per page. A quickstart guide for beginners and an advanced configuration reference should be separate pages, not one page trying to serve both.

Structure Your Documentation

Use the Four Documentation Types

Organize content into four categories based on what the reader needs:

Learning-oriented. Walk the reader through completing a task step-by-step. Example: "Build your first API integration." Task-oriented. Solve a specific problem. Assumes the reader already has basic knowledge. Example: "Configure SSO authentication." Information-oriented. Describe the system accurately and completely. Example: "API endpoint reference" or "Configuration options." Understanding-oriented. Explain concepts, decisions, and architecture. Example: "How the caching system works."

Page Structure

Every documentation page should follow a consistent structure:

1. Title — what the page covers (clear and specific) 1. Opening paragraph — what the reader will learn or accomplish 1. Prerequisites (if applicable) — what the reader needs before starting 1. Main content — organized with clear headings 1. Next steps — links to related pages

Writing Style

Be Direct

Write in active voice. Get to the point.

| Instead of | Write | | --- | --- | | "It should be noted that the configuration file needs to be updated" | "Update the configuration file" | | "The API can be used to retrieve user data" | "Use the API to retrieve user data" | | "In order to deploy your application..." | "To deploy your application..." |

Use Second Person

Address the reader as "you." It's clearer and more engaging than passive voice.

``markdown The project can be created by navigating to the dashboard.

Go to the dashboard and create a new project. `

Keep Sentences Short

Aim for one idea per sentence. Break up long paragraphs. Use lists for multiple related items.

Show, Don't Just Tell

Include code examples, screenshots, and practical demonstrations. Readers learn faster from examples than from abstract descriptions.

`markdown The CLI supports creating projects with custom templates. Create a project using the SDK template:

inkloom projects create --name "My API Docs" --template sdk-api-docs `

Using Components Effectively

InkLoom provides components that improve readability when used appropriately.

Callouts

Use callouts sparingly for information that the reader must not miss:

  • Info — helpful context that adds value
  • Tip — shortcuts or best practices
  • Warning — potential pitfalls or common mistakes
  • Danger — actions that could cause data loss or breaking changes

Don't overuse callouts. If every paragraph has a callout, none of them stand out. Reserve them for genuinely important information.

Steps

Use the component for sequential instructions. Each step should be a single action with a clear outcome.

`mdx

Run npm install -g @inkloom/cli to install the InkLoom CLI globally.

Run inkloom auth login and follow the browser prompt.

`

Code Blocks

  • Always specify the language for syntax highlighting
  • Add a title when the filename matters
  • Keep examples minimal — show only what's needed

Tabs

Use tabs to show platform-specific or language-specific variations of the same concept:

`mdx

npm install @inkloom/cli

yarn add @inkloom/cli

pnpm add @inkloom/cli

``

Organizing Navigation

Group by Task, Not Feature

Organize docs around what users want to do, not how your product is structured internally.

| Instead of | Write | | --- | --- | | "Authentication Module" | "Set Up Authentication" | | "Webhook System" | "Receive Real-Time Updates" | | "Template Engine" | "Customize Your Site" |

Keep Navigation Shallow

Aim for no more than two levels of nesting. Deep navigation makes content hard to find. If you have deeply nested sections, consider flattening them or splitting into separate groups.

Use Descriptive Page Titles

Titles should tell the reader exactly what they'll find:

| Vague | Specific | | --- | --- | | "Overview" | "How Deployments Work" | | "Configuration" | "Configure Custom Domains" | | "Advanced" | "Rate Limiting and Quotas" |

Maintaining Documentation

Keep Docs Close to Code

Update documentation whenever you change the feature it describes. Outdated docs are worse than no docs — they actively mislead users.

Review Regularly

Use Version Control

InkLoom supports branches and version history for documentation. Use branches when making large changes and merge when ready.

Complete MDX syntax reference

Optimize your docs for search engines