Contributing to Documentation

Thank you for helping improve our documentation! This guide shows you how to edit docs without any technical setup using GitHub's web editor.

Who Can Edit?

Team members with GitHub access
Community contributors (requires approval)
Anyone who spots a mistake or improvement

Quick Edit Guide (Non-Technical)

Step 1: Find the Page to Edit

Navigate to the documentation page you want to edit
Look for the "Edit on GitHub" link (usually at the bottom or top)
Click it to open GitHub

Step 2: Make Your Changes

GitHub will open the file in a web editor that looks like a text editor.

What You'll See:

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

# Main Heading

Your content here...

Don't worry about the --- section at the top! This is metadata. You can edit it, but focus on the content below the second --- line.

Step 3: Edit Using Markdown

Markdown is like simplified rich text. Here are the basics:

Headers

# Big Title (H1)

## Section Title (H2)

### Subsection (H3)

Text Formatting

**Bold text**
_Italic text_
~~Strikethrough~~
`Code or technical term`

Links

[Link text](https://example.com)
[Link to another doc](/docs/help/shops)

Lists

- Bullet point
- Another point
  - Nested point

1. Numbered item
2. Another numbered item

Images

![Image description](/path/to/image.png)

Callouts (Special Boxes)

<Callout type="info">
  This is an information box
</Callout>

<Callout type="warning">
  This is a warning box
</Callout>

<Callout type="success">
  This is a success box
</Callout>

Code Blocks

```
Regular code block
```

```javascript
// Code with syntax highlighting
const greeting = "Hello";
```

Step 4: Preview Your Changes

Click the Preview tab at the top
Check how your content looks
Switch back to Edit to make adjustments

Step 5: Save Your Changes

Scroll to the bottom of the page
Find "Commit changes" section
Write a short description like:
- "Fix typo in shop creation guide"
- "Update pricing information"
- "Add troubleshooting steps"
Choose one of:
- Commit directly (if you have permission)
- Create a new branch (creates a proposal for review)
Click Commit changes or Propose changes

Common Editing Tasks

Fixing a Typo

Click "Edit on GitHub"
Find the typo
Fix it
Commit with message: "Fix typo in [section name]"

Adding a New Section

## New Section Title

Your content here...

Updating Information

Find the outdated information
Update it with current details
Commit with message: "Update [what you changed]"

Adding an Image

Upload image to /public/docs/images/
Reference it in your doc:

![Alt text](/docs/images/your-image.png)

File Organization

Our docs live in src/content/docs/:

src/content/docs/
├── index.mdx                 # Homepage
├── getting-started.mdx       # Getting started guide
├── help/                     # Help Center
│   ├── index.mdx
│   ├── shops/
│   │   ├── index.mdx
│   │   ├── create-shop.mdx
│   │   └── ...
│   ├── staff/
│   └── ...
├── api/                      # API Documentation
└── guides/                   # Advanced Guides

Creating a New Article

Method 1: Using GitHub Web UI

Go to [repository]/src/content/docs
Navigate to the correct folder (e.g., help/shops/)
Click Add file > Create new file
Name your file: my-article.mdx
Add frontmatter and content:

---
title: My Article Title
description: Brief description of the article
icon: IconName
---

# My Article Title

Content goes here...

Commit the file

Method 2: Ask a Developer

If you're not comfortable with GitHub:

Write your article in a Google Doc or Word
Share it with the team
A developer will add it for you

Frontmatter Explained

The section between --- at the top of each file:

---
title: Page Title # Shows in browser tab and page heading
description: Short desc # Shows in search results
icon: IconName # Icon in sidebar (optional)
---

Available Icons

Common icons you can use:

Home, House
Store, Building
Users, User
Calendar, Clock
Settings, Cog
HelpCircle, Info
Book, BookOpen
Tag, Tags
BarChart, TrendingUp
Plug, Link

Browse all icons at Lucide

Navigation is controlled by meta.json files in each folder:

{
  "title": "Section Name",
  "pages": [
    "index",
    "article-1",
    "article-2",
    "---Separator Label",
    "article-3"
  ]
}

Careful! Editing meta.json incorrectly can break navigation. Ask for help if unsure.

Best Practices

✅ Do

Write clearly: Use simple language
Be specific: Include step numbers and screenshots
Test steps: Verify instructions work before publishing
Use callouts: Highlight important info with callout boxes
Add examples: Show real examples of concepts
Update outdated info: Keep content current

❌ Don't

Don't assume knowledge: Explain technical terms
Don't skip steps: Include every step, even obvious ones
Don't use jargon: Or explain it if you must
Don't leave broken links: Test all links before committing

Content Style Guide

Voice and Tone

Friendly but professional
Direct and clear
Helpful and supportive

Good Examples

✅ "Click the Create Shop button to get started"

✅ "Your booking link will be: yourdomain.com/book/your-slug"

✅ "Note: This action cannot be undone"

Bad Examples

❌ "Utilize the create functionality"

❌ "The URL will be generated based on the slug parameter you specified in the configuration"

❌ "Be careful!" (too vague)

Getting Help

Before You Edit

📖 Read this guide
👀 Look at existing articles for examples
💬 Ask the team if unsure

While Editing

🔍 Use GitHub's preview
📝 Keep commits small and focused
✏️ Write clear commit messages

After Editing

✅ Check your changes live on the site
🐛 Report any issues you notice
🎉 Celebrate your contribution!

Questions?

GitHub help: GitHub Docs
Markdown guide: Markdown Guide
Team Slack: #documentation channel
Email: docs@bookd.com

Thank you for contributing! Every improvement, no matter how small, helps our users. 🎉

Contributing to Documentation

On this page