Skip to main content

Best Practices

This guide outlines best practices for creating, maintaining, and improving documentation using our platform.

📝 Writing Guidelines​

Content Structure​

Use clear hierarchies with proper heading levels:

# Main Topic (H1)

## Subtopic (H2)

### Details (H3)

#### Specific Points (H4)

Keep introductions brief and get to the point quickly:

<!-- Good -->

This guide explains how to set up authentication for the API.

<!-- Avoid -->

In this comprehensive guide, we will walk you through the detailed process of setting up and configuring authentication for our API system, which is an essential security feature...

Use consistent formatting across all documents:

  • Bold for UI elements and important terms
  • Code for inline code, filenames, and commands
  • Italic for emphasis (use sparingly)

Writing Style​

Write in active voice:

<!-- Good -->

Run the following command to install dependencies.

<!-- Avoid -->

The following command should be run to install dependencies.

Be concise and clear:

<!-- Good -->

Set the API key in your environment variables.

<!-- Avoid -->

You should make sure to set the API key value in your environment variables configuration.

Use parallel structure in lists:

<!-- Good -->

- Install dependencies
- Configure settings
- Start the server

<!-- Avoid -->

- Install dependencies
- Configuration of settings
- Starting the server

Code Examples​

Always include working examples:

// Good: Complete, runnable example
import { ApiClient } from "@peack/api-client"

const client = new ApiClient({
  apiKey: process.env.API_KEY,
  baseURL: "https://api.example.com",
})

const movies = await client.movies.search("inception")
console.log(movies)

Explain what the code does:

# Create a new ML client instance
client = MLClient(api_key='your-key')

# Get recommendations for a specific user
# This returns a list of movie objects with scores
recommendations = client.get_recommendations(
    user_id='user123',
    limit=10
)

Show expected output when helpful:

$ npm install @peack/sdk
✓ Installing dependencies...
✓ Package installed successfully

🏗️ Document Organization​

File Structure​

Use descriptive filenames:

Good:
- api-authentication.md
- user-management-guide.md
- troubleshooting-common-errors.md

Avoid:
- auth.md
- users.md
- help.md

Group related content logically:

docs/
├── getting-started/
│   ├── installation.md
│   ├── quick-start.md
│   └── first-project.md
├── api-reference/
│   ├── authentication.md
│   ├── endpoints/
│   └── examples/
└── guides/
    ├── deployment.md
    └── troubleshooting.md

Use category files for better navigation:

// _category_.json
{
  "label": "API Reference",
  "position": 2,
  "description": "Complete API documentation and examples"
}

Frontmatter Standards​

Include all relevant metadata:

---
sidebar_position: 1
title: "Authentication Guide"
description: "Learn how to authenticate with our API using various methods"
tags: [api, authentication, security, guide]
keywords: [oauth, jwt, api key, authentication]
---

Use consistent tagging:

# Consistent tag categories
tags: [api, frontend, backend, guide, reference, tutorial]

# Avoid inconsistent tags
tags: [API, front-end, BE, howto, docs, ref]

🎨 Visual Elements​

Images and Diagrams​

Optimize images for web:

  • Use WebP format when possible
  • Keep file sizes under 500KB
  • Include alt text for accessibility
![API Flow Diagram](./images/api-flow.webp "Overview of API authentication flow")

Use diagrams for complex concepts:

graph LR
    A[User] --> B[Frontend]
    B --> C[API Gateway]
    C --> D[ML Service]
    D --> C
    C --> B
    B --> A

Provide captions for complex visuals:

![Architecture Diagram](./architecture.png)
_Figure 1: High-level system architecture showing data flow between components_

Code Blocks​

Always specify the language:

<!-- Good -->

```javascript
const result = await api.call()
```
const result = await api.call();

**Use meaningful titles:**

```javascript title="src/utils/apiClient.js"
export class ApiClient {
  constructor(options) {
    this.apiKey = options.apiKey;
    this.baseURL = options.baseURL;
  }
}

Highlight important lines:

const client = new ApiClient({
  apiKey: process.env.API_KEY, // highlight-next-line
  baseURL: "https://api.example.com",
})

Callouts and Admonitions​

Use callouts for important information:

:::tip
Use environment variables to store sensitive information like API keys.
:::

:::warning
Never commit API keys to version control.
:::

:::danger
This operation cannot be undone. Make sure to backup your data first.
:::

:::info
This feature is available in version 2.0 and later.
:::

🔗 Linking Best Practices​

Use relative paths for internal links:

<!-- Good -->

See the [API Reference](../api/overview.md) for more details.

<!-- Avoid -->

See the [API Reference](/docs/api/overview) for more details.

Link to specific sections:

For authentication details, see [API Keys](./authentication.md#api-keys).

Use descriptive link text:

<!-- Good -->

Learn how to [configure environment variables](./setup.md#environment-variables).

<!-- Avoid -->

[Click here](./setup.md#environment-variables) for environment variable configuration.

Open external links in new tabs when appropriate:

Check out the [official React documentation](https://reactjs.org/docs){:target="\_blank"} for more information.

Verify external links regularly to prevent broken links.

📊 SEO and Discoverability​

Meta Information​

Write compelling descriptions:

---
title: "Getting Started with Our API"
description: "Learn how to integrate our movie recommendation API in just 5 minutes with this step-by-step guide"
---

Use relevant keywords naturally:

# Movie Recommendation API Documentation

This guide covers movie recommendation algorithms, API integration, and best practices for implementing personalized movie suggestions in your application.

Search Optimization​

Use headings strategically:

# Main Topic

## How to Get Started

### Prerequisites

### Installation Steps

## Advanced Configuration

### Environment Variables

### Custom Settings

Include searchable keywords in content:

When implementing movie recommendations, consider factors like user preferences, collaborative filtering, content-based filtering, and machine learning algorithms.

🔄 Maintenance Practices​

Regular Updates​

Keep dependencies current:

# Check for outdated packages
npm outdated

# Update packages
npm update

Review and update content quarterly:

  • Check for broken links
  • Update code examples
  • Verify API references
  • Refresh screenshots

Quality Assurance​

Use automated checks:

# .github/workflows/docs-quality.yml
name: Documentation Quality

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint markdown
        run: markdownlint docs/**/*.md
      - name: Check spelling
        run: cspell "docs/**/*.md"
      - name: Validate links
        run: markdown-link-check docs/**/*.md

Review checklist for new content:

  • Proper frontmatter included
  • All code examples tested
  • Images optimized and have alt text
  • Links work correctly
  • Spelling and grammar checked
  • Follows style guide
  • Tagged appropriately

Version Control​

Use meaningful commit messages:

# Good
git commit -m "docs: add authentication examples for Python SDK"
git commit -m "docs: update API endpoint documentation for v2.1"

# Avoid
git commit -m "update docs"
git commit -m "fix stuff"

Use pull requests for major changes:

  • Create feature branches for new documentation
  • Request reviews from team members
  • Include screenshots for UI changes
  • Test locally before submitting

🚀 Performance Optimization​

Build Performance​

Optimize images:

# Use imagemin to compress images
npx imagemin docs/images/*.png --out-dir=docs/images/optimized --plugin=pngquant

Minimize external dependencies:

// Avoid heavy external widgets
// Use lightweight alternatives when possible
import LightWidget from "light-widget"
// instead of
import HeavyWidget from "heavy-widget-with-many-deps"

Loading Performance​

Use lazy loading for images:

![Large Diagram](./large-diagram.png){loading=lazy}

Split large documents:

<!-- Instead of one huge file -->

# Everything About Our API (500+ lines)

<!-- Create multiple focused files -->

# API Overview

See detailed guides:

- [Authentication](./authentication.md)
- [Endpoints](./endpoints.md)
- [Examples](./examples.md)

🎯 User Experience​

Design clear sidebar structure:

// sidebars.ts
const sidebars = {
  docs: [
    "intro",
    {
      type: "category",
      label: "Getting Started",
      collapsed: false, // Keep important sections expanded
      items: ["installation", "quick-start", "first-project"],
    },
    {
      type: "category",
      label: "Advanced Topics",
      collapsed: true, // Collapse advanced sections by default
      items: ["performance", "security", "deployment"],
    },
  ],
}

Use breadcrumbs effectively:

  • Keep navigation paths logical
  • Ensure users can always find their way back
  • Use descriptive category names

Accessibility​

Include alt text for all images:

![API Flow Diagram](./api-flow.png "Diagram showing the flow of API requests from frontend to backend services")

Use semantic HTML in custom components:

// Good
<section role="main">
  <h1>API Documentation</h1>
  <nav aria-label="API sections">
    <ul>
      <li>
        <a href="#auth">Authentication</a>
      </li>
      <li>
        <a href="#endpoints">Endpoints</a>
      </li>
    </ul>
  </nav>
</section>

Ensure good color contrast:

/* Ensure text meets WCAG contrast guidelines */
.custom-callout {
  background-color: #f0f8ff;
  color: #003366; /* High contrast ratio */
  border: 2px solid #0066cc;
}

📈 Analytics and Feedback​

Content Analytics​

Track popular content:

// Google Analytics 4 configuration
gtag("config", "GA_MEASUREMENT_ID", {
  custom_map: {
    custom_parameter_1: "documentation_section",
  },
})

// Track documentation interactions
gtag("event", "doc_interaction", {
  section: "api-reference",
  action: "code_copy",
})

Monitor search queries:

  • Review site search analytics
  • Identify content gaps
  • Improve based on user searches

Feedback Collection​

Add feedback widgets:

// Feedback component
function PageFeedback() {
  return (
    <div className="page-feedback">
      <p>Was this page helpful?</p>
      <button onClick={() => trackFeedback("helpful")}>Yes</button>
      <button onClick={() => trackFeedback("not-helpful")}>No</button>
    </div>
  )
}

Include contact information:

## Need Help?

- **Issues**: [GitHub Issues](https://github.com/org/repo/issues)
- **Questions**: [Discord Community](https://discord.gg/community)
- **Email**: support@peack.com

🔒 Security Considerations​

Sensitive Information​

Never include credentials in documentation:

<!-- Good -->

Set your API key:

```bash
export API_KEY="your_api_key_here"
```
export API_KEY="sk_live_abcd1234xyz"

**Use placeholders for sensitive data:**

```json
{
  "api_key": "YOUR_API_KEY",
  "database_url": "postgresql://username:password@localhost:5432/dbname"
}

Content Security​

Review public information:

  • Don't expose internal architecture details unnecessarily
  • Avoid sharing debug information
  • Keep security-related information appropriately restricted

🌐 Internationalization​

Multi-language Support​

Structure for translations:

docs/
├── en/
│   ├── intro.md
│   └── guide.md
├── es/
│   ├── intro.md
│   └── guide.md
└── fr/
    ├── intro.md
    └── guide.md

Use translation-friendly writing:

  • Keep sentences concise
  • Avoid idioms and colloquialisms
  • Use simple, clear language
  • Include context for translators
<!-- Good -->

Click the "Save" button to save your changes.

<!-- Harder to translate -->

Hit the save button when you're ready to commit your changes.

📋 Checklist Templates​

New Document Checklist​

  • Descriptive filename chosen
  • Frontmatter completed with title, description, tags
  • Content follows style guide
  • Code examples tested and working
  • Images optimized and have alt text
  • Internal links use relative paths
  • External links verified
  • Spelling and grammar checked
  • Added to appropriate sidebar
  • Preview looks correct locally

Monthly Review Checklist​

  • Check for broken links
  • Update outdated information
  • Review analytics for popular content
  • Check for new feedback or issues
  • Update dependencies
  • Verify all examples still work
  • Review and update tags
  • Check image optimization

Release Documentation Checklist​

  • All new features documented
  • Breaking changes highlighted
  • Migration guides provided
  • API changes documented
  • Version bumped appropriately
  • Changelog updated
  • Examples updated for new version

Need more specific guidance? Check our troubleshooting guide or reach out to the documentation team!