Getting started with documentation New

Writing clear and effective documentation is essential for any project. When you create content that others will read and use, proper formatting makes all the difference. Good documentation helps users understand complex concepts quickly and efficiently.

Documentation is a love letter that you write to your future self.

The foundation of great documentation starts with understanding your audience and their needs. Along the way you'll reach for a handful of inline elements: highlights to draw the eye, an HTML tag for terms that deserve a definition, and outdated advice replaced with the current recommendation. Formulas read naturally too, like H₂O or 2¹⁰.

As The Elements of Style puts it, omit needless words — the same rule applies to interfaces and to the docs that explain them.

A quick glossary

Prose

Long-form, readable content — articles, changelogs, help center entries.

Markdown

A plain-text format that compiles down to the same HTML this page uses.

Style guide

A shared reference so every writer on the team formats things the same way.

Adding code examples

Inline code looks like console.log("Hello") and uses monospace styling. For anything longer, drop it into a code block, and mention shortcuts with Ctrl + C style keys:

function add(a, b) {
  return a + b;
}

Structuring steps and points

Use an ordered list to walk through a process:

1. Start with the most important information.
2. Provide context before technical details.
3. Include practical examples.

And an unordered list for related points that don't have a specific order:

• Write clear, concise list items.
• Keep the structure consistent.
• Avoid overly long items.

Nesting related items

Lists can nest, with indentation and spacing handled automatically:

• Editing
  • Undo and redo
  • Cut, copy, and paste
• Formatting
  • Bold and italic
  • Headings and lists
• Sharing

A visual checklist

For a status readers can scan at a glance, drop in the steps component instead of a plain list:

• Draft
• Review
• Publish
• Announce

---

Supporting images

Images should support the text and provide useful context, not just decorate the page.

Comparing data in tables

Tables work best for comparing related data points, like votes on a proposal:

Name	Up-votes	Down-votes
Alice	10	11
Bob	4	3
Charlie	7	9
Totals	21	23