Documentation Guidelines

These guidelines are designed to help us maintain high-quality, consistent, and useful documentation for the Zeal Frontend team. By following these standards, we ensure that our docs remain a valuable resource for onboarding, knowledge sharing, and daily development.

Guiding Principles

• Docs as Code: Treat documentation like code. It lives in the repo, goes through PR reviews, and is versioned.
• Single Source of Truth: Avoid duplication. If information exists elsewhere (e.g., in a specific tool's official docs), link to it rather than copying it.
• Up-to-Date: Outdated documentation is worse than no documentation. Update docs in the same PR that changes the functionality.
• User-Centric: Always write with the reader in mind. What do they need to know to solve their problem?

Writing Style

Voice and Tone

• Voice: Use the second person ("You") to address the reader directly.
  • Good: "You can configure the router..."
  • Bad: "The user can configure the router..."
• Tone: Be professional, encouraging, and clear. Avoid jargon where simple language suffices.
• Active Voice: Use active voice for clarity and impact.
  • Good: "The build script generates the assets."
  • Bad: "The assets are generated by the build script."
• Conciseness: Keep sentences short and to the point. Use bullet points to break down complex information.

Example: Voice and Tone

<!-- Good Example -->
You can configure the router by editing the `routes.ts` file. The router will automatically reload when you save changes.

<!-- Bad Example -->
The router can be configured by editing the routes.ts file. Changes will be automatically reloaded by the router when saved.

Structure & Formatting

Headings

Use proper hierarchy for headings. The file title is H1 (#). Use H2 (##) for main sections and H3 (###) for subsections. Avoid skipping levels.

Example:

# Main Title (H1 - only one per file)

## Section One (H2)

### Subsection 1.1 (H3)

### Subsection 1.2 (H3)

## Section Two (H2)

Code Blocks

Always specify the language for syntax highlighting. Use code comments to explain complex logic within the snippet.

Example:

// Good - Language specified, comments explain logic
const calculateTotal = (items: Item[]): number => {
  // Filter out items with zero quantity
  const validItems = items.filter(item => item.quantity > 0);
  
  // Sum up the prices
  return validItems.reduce((sum, item) => sum + item.price, 0);
};

// Bad - No language specified, no comments
const calculateTotal = (items) => {
  const validItems = items.filter(item => item.quantity > 0);
  return validItems.reduce((sum, item) => sum + item.price, 0);
};

File Naming

Use kebab-case for all file and directory names.

Examples:

• ✅ environment-setup.md
• ✅ fe-be-communication.md
• ✅ api-authentication.md
• ❌ EnvironmentSetup.md (PascalCase)
• ❌ fe_be_communication.md (snake_case)
• ❌ fe be communication.md (spaces)

Links

• Internal Links: Use relative paths to other documentation pages.

  [Environment Setup Guide](../guides/environment-setup.md)

• External Links: Ensure they are reliable and stable. Consider using permalinks or archived versions for critical external resources.

Frontmatter

Every documentation file must start with frontmatter (YAML between --- markers) that includes:

• title: The page title (appears in browser tab and as H1)
• description: Brief description for SEO and search results
• sidebar_position: Number for ordering in sidebar (lower numbers appear first)

Example:

---
title: Component Development Guide
description: Learn how to create and maintain React components in our codebase.
sidebar_position: 2
---

Document Types

We categorize our documentation to help readers find what they need quickly. Each type has a specific purpose and structure.

1. Guides (Tutorials & How-to)

Focused on helping the user complete a specific task or setup.

• Goal: Competence - reader can perform the task after reading.
• Example: "Environment Setup", "Creating a new Component".
• Structure:
  1. Prerequisites (what you need before starting)
  2. Step-by-step instructions (numbered or clear sequence)
  3. Verification/Outcome (how to confirm it worked)
  4. Troubleshooting (common issues and solutions)

Example Structure:

# Guide Title

## Prerequisites

- Node.js 22.x installed
- Access to the repository

## Step 1: Initial Setup

[Detailed instructions...]

## Step 2: Configuration

[Detailed instructions...]

## Verification

Run this command to verify:
```bash
npm run verify

Troubleshooting

[Common issues...]

### 2. Processes (Explanations)

Explains *how* and *why* we work the way we do.

-   **Goal**: Understanding - reader understands the reasoning and workflow.
-   **Example**: "FE-BE Communication", "Release Process".
-   **Structure**:
    1.  Overview (what this process covers)
    2.  The "Why" (rationale and context)
    3.  Detailed Process Flow (step-by-step workflow)
    4.  Roles & Responsibilities (who does what)
    5.  Examples (real-world scenarios)

**Example Structure:**
```markdown
# Process Title

## Overview

[What this process covers...]

## Why This Process Exists

[Rationale and context...]

## Process Flow

### Step 1: [Action]
[Description...]

### Step 2: [Action]
[Description...]

## Roles & Responsibilities

| Role | Responsibility |
|------|---------------|
| Developer | [What they do] |
| Reviewer | [What they do] |

## Examples

[Real-world scenarios...]

3. Standards (Reference)

Hard rules and agreements that must be followed.

• Goal: Compliance & Consistency - reader knows what rules to follow.
• Example: "ACL Protection", "Coding Standards", "Naming Conventions".
• Structure:
  1. Rule/Standard (clear statement)
  2. Rationale (why this rule exists)
  3. Examples (Do's and Don'ts)
  4. Enforcement (how this is checked)

Example Structure:

# Standard Title

## The Rule

[Clear statement of the rule...]

## Rationale

[Why this rule exists...]

## Examples

### ✅ Do

```typescript
// Good example

❌ Don't

// Bad example

Enforcement

[How this is checked/enforced...]

## Versioning and Change Management

### Document Versioning

Each document should include version information in its frontmatter or metadata section. This helps track changes and ensures readers know when content was last updated.

**Example:**
```yaml
---
title: API Authentication Guide
description: How to authenticate API requests.
sidebar_position: 1
---

:::info[Document Metadata]
| Field | Value |
|-------|-------|
| **Version** | 2.1 |
| **Last Updated** | January 15, 2025 |
| **Owner** | john.doe@getzeal.io |
| **Status** | ✅ Current |
:::

Version Numbering

Use semantic versioning for significant changes:

• Major version (X.0.0): Breaking changes, major rewrites, or fundamental changes to the process
• Minor version (0.X.0): New sections, additional examples, or clarifications
• Patch version (0.0.X): Typo fixes, minor corrections, or formatting improvements

Example:

• Version 1.0.0 → 2.0.0: Complete rewrite of the authentication process
• Version 2.0.0 → 2.1.0: Added new section on OAuth2 flow
• Version 2.1.0 → 2.1.1: Fixed typo in code example

Change Log

For documents with multiple versions, include a change log section:

## Change Log

| Version | Date | Changes | Author |
|---------|------|---------|--------|
| 2.1 | 2025-01-15 | Added OAuth2 flow section | John Doe |
| 2.0 | 2024-12-01 | Complete rewrite | Jane Smith |
| 1.0 | 2024-10-01 | Initial version | John Doe |

Updating Documentation

When updating documentation:

1. Update in the same PR: If code changes require doc updates, include them in the same pull request.
2. Update version: Increment the version number appropriately.
3. Update date: Change the "Last Updated" date.
4. Add to change log: Document what changed and why.

Example PR Description:

## Changes
- Updated authentication flow to use OAuth2
- Added new environment variables

## Documentation
- Updated `api-authentication.md` (v2.0 → v2.1)
- Added OAuth2 flow section
- Updated code examples

Metadata and Organization

Document Metadata

Include metadata at the top of important documents using Docusaurus callouts:

:::info[Document Status]
| Field | Value |
|-------|-------|
| **Status** | ✅ Approved |
| **Version** | 1.0 |
| **Owner** | john.doe@getzeal.io |
| **Last Reviewed** | January 15, 2025 |
:::

Categories and Tags

Use the sidebar structure to organize documents. Each category should have a _category_.json file:

{
  "label": "Category Name",
  "position": 1,
  "collapsed": false
}

Visual Aids

Code Examples

Always include working, tested code examples:

// Good - Complete, working example
import { useState } from 'react';

export const Counter = () => {
  const [count, setCount] = useState(0);
  
  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
};

Diagrams

Use Mermaid diagrams for process flows, architecture, or relationships:

graph TD
    A[Start] --> B{Is authenticated?}
    B -->|Yes| C[Load Dashboard]
    B -->|No| D[Redirect to Login]
    C --> E[End]
    D --> E

Tables

Use tables for structured information:

Property	Type	Required	Description
userId	string	Yes	Unique user identifier
email	string	Yes	User email address
role	'admin' | 'user'	No	User role (defaults to 'user')

Callouts

Use Docusaurus callouts for important information:

:::tip[Pro Tip]
Use TypeScript for better type safety!
:::

:::warning[Important]
Never commit API keys to the repository.
:::

:::danger[Critical]
This operation cannot be undone!
:::

:::info[Note]
This feature is available in version 2.0+.
:::

Maintenance Checklist

Before merging a PR that affects documentation:

• Have I adhered to the writing style (second person, active voice)?
• Are all code examples tested and working?
• Did I update the sidebar (sidebars.ts) if I added a new file?
• Did I remove any obsolete information?
• Did I update the version number and change log?
• Did I update the "Last Updated" date?
• Are all internal links working?
• Did I use proper heading hierarchy?
• Are code blocks properly formatted with language tags?
• Did I add appropriate metadata (frontmatter)?

Examples

See the Example Documentation Page for a complete example that follows all these guidelines.