Example Documentation Page

This page demonstrates how to structure a documentation page following all our guidelines. Use this as a template when creating new documentation.

Document Metadata

Field	Value
Version	1.0
Last Updated	January 19, 2025
Owner	documentation-team@getzeal.io
Status	✅ Current
Type	Guide

Overview

This example page shows you how to structure documentation that follows our guidelines. You can use this as a reference when creating new pages.

Prerequisites

Before you begin, ensure you have:

• Access to the documentation repository
• Basic knowledge of Markdown
• Understanding of our Documentation Guidelines

Step-by-Step Instructions

Step 1: Create the File

Create a new file using kebab-case naming convention:

# Good - kebab-case
docs/guides/my-new-guide.md

# Bad - avoid these
docs/guides/MyNewGuide.md        # PascalCase
docs/guides/my_new_guide.md      # snake_case
docs/guides/my new guide.md      # spaces

Step 2: Add Frontmatter

Every documentation file must start with frontmatter:

---
title: Your Page Title
description: Brief description for search and SEO.
sidebar_position: 1
---

Explanation:

• title: Appears in the browser tab and as the H1 heading
• description: Used in search results and meta tags
• sidebar_position: Controls order in sidebar (lower numbers appear first)

Step 3: Write the Content

Follow the structure appropriate for your document type:

For Guides (How-to)

# Guide Title

## Prerequisites
[What you need before starting]

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

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

## Verification
[How to confirm it worked]

## Troubleshooting
[Common issues and solutions]

For Processes

# Process Title

## Overview
[What this covers]

## Why This Process Exists
[Rationale]

## Process Flow
[Step-by-step workflow]

## Roles & Responsibilities
[Who does what]

For Standards

# Standard Title

## The Rule
[Clear statement]

## Rationale
[Why this exists]

## Examples

### ✅ Do
[Good example]

### ❌ Don't
[Bad example]

Step 4: Add Code Examples

Always include working code examples with proper language tags:

// Good - Language specified, comments explain logic
interface User {
  id: string;
  email: string;
  role: 'admin' | 'user';
}

const createUser = (email: string): User => {
  // Generate unique ID
  const id = crypto.randomUUID();
  
  // Default role is 'user'
  return { id, email, role: 'user' };
};

// Bad - No language tag, no comments
interface User {
  id: string;
  email: string;
  role: 'admin' | 'user';
}

const createUser = (email: string): User => {
  const id = crypto.randomUUID();
  return { id, email, role: 'user' };
};

Step 5: Use Visual Aids

Tables

Use tables for structured information:

Property	Type	Required	Description
name	string	Yes	Component name
props	object	No	Component props
children	ReactNode	No	Child elements

Diagrams

Use Mermaid for process flows:

graph LR
    A[Start] --> B[Create File]
    B --> C[Add Frontmatter]
    C --> D[Write Content]
    D --> E[Add Examples]
    E --> F[Review]
    F --> G[Publish]

Callouts

Use callouts for important information:

Pro Tip

Always test your code examples before including them in documentation!

Important

Never commit sensitive information like API keys or passwords.

Critical

This operation cannot be undone. Make sure you have backups.

Note

This feature requires Node.js version 22.x or higher.

Step 6: Add Internal Links

Link to related documentation:

For more information, see:
- [Environment Setup Guide](../guides/environment-setup.md)
- [Documentation Guidelines](./documentation-guidelines.md)
- [FE/BE Communication Process](../processes/fe-be-communication.md)

Step 7: Include Version Information

Add version metadata and change log:

## Change Log

| Version | Date | Changes | Author |
|---------|------|---------|--------|
| 1.0 | 2025-01-15 | Initial version | John Doe |

Verification

To verify your documentation is complete:

1. Check that all code examples work
2. Verify all internal links are correct
3. Ensure proper heading hierarchy (H1 → H2 → H3)
4. Confirm frontmatter is complete
5. Review against the Maintenance Checklist

Troubleshooting

Common Issues

Code example doesn't render correctly

Problem: Code block appears without syntax highlighting.

Solution: Ensure you've specified the language tag:

```typescript
// Your code here
```

Page doesn't appear in sidebar

Problem: New page isn't visible in navigation.

Solution: Update sidebars.ts to include your new page:

items: [
  'guides/your-new-page',
]

Internal links are broken

Problem: Links to other docs show 404 errors.

Solution: Use relative paths and verify file names match exactly:

[Link Text](../guides/environment-setup.md)

Examples in Practice

Example: Guide Structure

See Environment Setup Guide for a real-world example of a guide.

Example: Process Structure

See FE/BE Communication Process for a real-world example of a process document.

Example: Standard Structure

See ACL Protection Standards for a real-world example of a standards document.

Related Documentation

• Documentation Guidelines - Complete guidelines reference
• Environment Setup Guide - Example guide
• FE/BE Communication Process - Example process

---

Need Help?

If you have questions about documentation structure or style, reach out in #frontend-team on Slack or create a PR with your draft for review.