Documentation Style Guide

Guidelines for writing and maintaining documentation.

Writing Principles

Clarity

• Use clear, simple language
• Avoid jargon when possible
• Explain technical terms
• Use examples

Consistency

• Follow consistent formatting
• Use consistent terminology
• Maintain consistent structure

Completeness

• Cover all aspects
• Include examples
• Provide context
• Link to related docs

Structure

Document Structure

# Title

Brief introduction (1-2 sentences)

## Table of Contents (for long docs)

## Section 1

Content here

### Subsection

More content

## Section 2

Content here

Section Headers

• Use # for main title
• Use ## for major sections
• Use ### for subsections
• Use #### for sub-subsections

Formatting

Code Blocks

// Use language tags
import Component from '@/components/Component';

function Example() {
  return <Component />;
}

Inline Code

Use backticks for inline code, file names, and technical terms.

Lists

Unordered Lists:

• Item 1
• Item 2
• Item 3

Ordered Lists:

1. Step 1
2. Step 2
3. Step 3

Emphasis

• Bold for important terms
• Italic for emphasis
• Code for technical terms

Links

• Use descriptive link text
• Link to related documentation
• Use relative paths for internal links

Code Examples

Good Examples

// Include comments
import { useForm } from '@/hooks/useForm';

function MyForm() {
  const { values, handleChange, handleSubmit } = useForm({
    initialValues: { email: '' },
    onSubmit: async (values) => {
      // Handle submission
      console.log(values);
    },
  });

  return (
    <form onSubmit={handleSubmit}>
      <input
        name="email"
        value={values.email}
        onChange={handleChange}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

Example Guidelines

• Include complete, working examples
• Add comments for clarity
• Show imports
• Include error handling when relevant

Terminology

Consistent Terms

• Use "component" not "widget"
• Use "hook" not "custom hook" (when clear from context)
• Use "API" not "endpoint" (when referring to the API)

Technical Terms

• Define terms on first use
• Link to glossary for complex terms
• Use consistent capitalization

Tone

Professional but Friendly

• Write in a professional tone
• Be friendly and approachable
• Avoid being overly formal
• Use "you" when addressing readers

Examples

Good: "You can use the useForm hook to handle form state."

Avoid: "One may utilize the useForm hook to handle form state."

Tables

Format

| Column 1 | Column 2 | Column 3 | |----------|----------|----------| | Value 1 | Value 2 | Value 3 | | Value 4 | Value 5 | Value 6 |

Guidelines

• Use tables for structured data
• Keep tables simple
• Align columns properly

Images and Diagrams

Guidelines

• Use descriptive alt text
• Keep images relevant
• Optimize image sizes
• Use consistent format (SVG preferred)

Alt Text

![Description of image](path/to/image.png)

Checklists

Format

• [ ] Task 1
• [ ] Task 2
• [x] Completed task

Warnings and Notes

Warning

⚠️ Warning: This action cannot be undone.

Note

💡 Note: This feature requires additional configuration.

Tip

💡 Tip: Use this shortcut to save time.

Cross-References

Internal Links

See [Component Guide](./COMPONENTS.md) for details.

External Links

See [Next.js Documentation](https://nextjs.org/docs) for more information.

Version Information

When to Include

• API changes
• Breaking changes
• New features
• Deprecations

Format

> **Version**: 1.0.0+
> **Since**: 1.0.0

Updating Documentation

When to Update

• Adding new features
• Changing APIs
• Fixing bugs
• Improving clarity

How to Update

1. Find relevant documentation
2. Make changes
3. Update examples if needed
4. Check cross-references
5. Review for clarity

Review Checklist

Before publishing:

• [ ] Spelling and grammar checked
• [ ] Code examples tested
• [ ] Links verified
• [ ] Formatting consistent
• [ ] Cross-references updated
• [ ] Examples complete
• [ ] Terminology consistent

Resources

• Markdown Guide
• Technical Writing
• Documentation Best Practices