Documentation Guidelines

This guide explains how to create and organize new documentation in this repository.

File Structure

The documentation is organized into several main categories:

pages/
├── ai/              # AI-related documentation
├── api/             # API documentation
├── backend/         # Backend development
├── business/        # Business-related docs
├── engineering/     # Engineering practices
├── frontend/        # Frontend development
├── git/            # Git-related guides
├── infrastructure/ # Infrastructure and DevOps
├── leadership/     # Leadership and management
├── mac/           # macOS-specific guides
├── other/         # Miscellaneous docs
├── private/       # Private documentation
└── programming/   # General programming guides

File Naming Convention

1. Use kebab-case for file names: my-new-document.mdx
2. Make names descriptive and URL-friendly
3. Use .mdx extension for all documentation files
4. Avoid spaces and special characters

Examples:

• ✅ how-to-setup-nginx.mdx
• ✅ gitlab-ci-server-deployment.mdx
• ❌ How to Setup Nginx.mdx
• ❌ setup_nginx.mdx

Document Structure

1. Metadata Registration

After creating a new document, register it in the _meta.json file of the corresponding directory:

{
  "my-new-document": "Human Readable Title",
  "existing-document": "Existing Document Title"
}

2. Document Template

Use this template for new documents:

# Document Title
 
Brief description of what this document covers.
 
## Overview
 
Key points or summary of what will be covered:
1. First point
2. Second point
3. Third point
 
## Prerequisites
 
List any requirements or prerequisites:
- Requirement 1
- Requirement 2
 
## Main Content
 
### Section 1
 
Content for section 1
 
### Section 2
 
Content for section 2
 
## Additional Resources
 
- [Resource 1](url)
- [Resource 2](url)

Writing Style Guidelines

1. Headers

   • Use Title Case for main title
   • Use sentence case for sections
   • Maximum of 3 levels of headers (# ## ###)

2. Code Blocks

   • Specify language for syntax highlighting

   # Example
   key: value
   • Use inline code `backticks` for:
     • File names
     • Commands
     • Variables
     • Paths

3. Content Guidelines

   • Start with a clear introduction
   • Use numbered lists for sequential steps
   • Use bullet points for unordered lists
   • Include examples where applicable
   • Add warning/note blocks for important information
   • End with additional resources when relevant

4. Formatting

   • Use bold for emphasis
   • Use blockquotes for notes/warnings:

     ⚠️ Warning: Important security note

   • Use tables for structured data
   • Include screenshots when helpful

Best Practices

1. Organization

   • Place documents in the most relevant category
   • Create new categories only when necessary
   • Keep the structure shallow (max 2 levels deep)

2. Content

   • Keep it concise but complete
   • Include practical examples
   • Update existing docs instead of creating duplicates
   • Remove outdated information

3. Maintenance

   • Review and update docs regularly
   • Remove deprecated content
   • Keep examples up to date
   • Fix broken links

Example Document

Here's a minimal example of a well-structured document:

# How to Deploy Node.js Application
 
This guide explains how to deploy a Node.js application to a production server.
 
## Overview
 
We'll cover:
1. Server preparation
2. Application deployment
3. Configuration setup
4. Monitoring setup
 
## Prerequisites
 
- Node.js 18 or higher
- PM2 process manager
- Nginx web server
 
## Server Setup
 
### Install Dependencies
 
\`\`\`bash
apt update
apt install nodejs npm
npm install -g pm2
\`\`\`
 
### Configure Nginx
 
\`\`\`nginx
server {
    listen 80;
    server_name example.com;
    # ... rest of config
}
\`\`\`
 
> ⚠️ **Note:** Remember to secure your server with SSL
 
## Additional Resources
 
- [Node.js Docs](https://nodejs.org/docs)
- [PM2 Documentation](https://pm2.io/docs)

Common Mistakes to Avoid

1. Not updating _meta.json
2. Inconsistent file naming
3. Missing prerequisites section
4. Unclear or missing examples
5. No additional resources
6. Outdated content
7. Poor formatting

Questions?

If you have questions about documentation guidelines, please reach out to the team or create an issue in the repository.