Contributing to Documentation

Welcome! We appreciate your interest in improving the zero-sources documentation. This guide will help you understand how to contribute effectively.

Thank you! Every contribution, no matter how small, helps make zero-sources better for everyone.

Why Contribute?

Contributing to documentation helps:

Improve clarity - Make complex concepts easier to understand
Fill gaps - Add missing information or examples
Keep content current - Update docs to match code changes
Share knowledge - Help others learn from your experience
Build community - Join a collaborative open-source project

Ways to Contribute

1. Fix Issues

The easiest way to start:

Fix typos and grammar errors
Correct outdated information
Fix broken links
Improve code examples

2. Improve Existing Content

Make good documentation great:

Add missing examples
Clarify confusing sections
Add diagrams or illustrations
Expand brief explanations
Add cross-references

3. Write New Content

Share your expertise:

Create how-to guides
Write tutorials
Document use cases
Add troubleshooting tips
Create reference material

4. Review and Feedback

Help maintain quality:

Review pull requests
Test examples and instructions
Provide feedback on clarity
Suggest improvements

Getting Started

1. Fork the repository

Visit zero-sources on GitHub and click Fork.

2. Clone your fork

git clone https://github.com/YOUR-USERNAME/zero-sources.git
cd zero-sources

3. Install dependencies

pnpm install

4. Start the docs server

pnpm --filter docs dev

Visit http://localhost:3000 to see your local documentation site.

5. Create a branch

git checkout -b docs/your-improvement-name

6. Make your changes

Edit files in apps/docs/content/docs/ and see changes live in your browser.

7. Commit and push

git add .
git commit -m "docs: describe your changes"
git push origin docs/your-improvement-name

8. Open a pull request

Go to GitHub and open a pull request from your branch.

What to Contribute

Writing Documentation

Learn MDX authoring and our documentation structure

Style Guide

Follow our content standards and formatting rules

Quick Tips

Finding What to Work On

Check GitHub Issues - Look for issues labeled documentation or good first issue
Read existing docs - Note anything confusing or incomplete
Use the product - Document problems you encounter
Ask in discussions - See what others find unclear

Writing Great Documentation

Know your audience - Write for developers familiar with TypeScript
Be concise - Get to the point quickly
Show examples - Code examples are worth a thousand words
Test your examples - Make sure code actually works
Use clear language - Avoid jargon or explain terms

Before Submitting

Content Guidelines

Types of Documentation

Getting Started Guides

Help new users get up and running quickly.

Structure:

Brief introduction
Prerequisites
Step-by-step instructions
Verification steps
Next steps

How-To Guides

Task-oriented guides for specific goals.

Structure:

Goal statement
Prerequisites
Steps to complete
Expected results
Troubleshooting

Reference Documentation

Complete API and configuration reference.

Structure:

Overview
API listing
Parameters and types
Examples
Related references

Conceptual Documentation

Explain how things work and why.

Structure:

Introduction
Key concepts
How it works
When to use
Related topics

Writing Style

Do:

Use active voice: "Create a file" not "A file should be created"
Address the reader: "You can configure..."
Be specific: "Set timeout to 30 seconds" not "Set an appropriate timeout"
Use examples: Show, don't just tell

Don't:

Use jargon without explanation
Make assumptions about prior knowledge
Write long paragraphs without breaks
Leave examples untested

Working with MDX

Basic Syntax

MDX combines Markdown with JSX:

---
title: Page Title
description: Page description
---

# Heading

Regular markdown text.

<Callout>
  Custom component in JSX
</Callout>

```typescript
// Code block
const example = "code";
```

Custom Components

We provide several custom components:

<Callout type="info">
  Information callout
</Callout>

<Cards>
  <Card title="Title" href="/link" description="Description" />
</Cards>

<Tabs items={['Tab 1', 'Tab 2']}>
  <Tab value="Tab 1">Content 1</Tab>
  <Tab value="Tab 2">Content 2</Tab>
</Tabs>

<Steps>
### Step 1
Content for step 1

### Step 2
Content for step 2
</Steps>