Skip to main content

Contributing to Documentation

Overview​

Good documentation is essential for the success of BookWish. This guide explains how to contribute to our documentation site.

Documentation Structure​

The BookWish documentation is organized into several sections:

docs-site/docs/
├── introduction/          # Getting started, overview
├── features/             # Feature guides for users
├── developers/           # Developer documentation
│   ├── getting-started/  # Setup and quick start
│   ├── architecture/     # System architecture
│   ├── contributing/     # Contribution guidelines
│   └── deployment/       # Deployment guides
└── api/                  # API reference

Technology Stack​

Our documentation site is built with:

  • Docusaurus - Documentation framework
  • Markdown - Content format
  • React/MDX - For interactive components
  • TypeScript - Type-safe customizations

Writing Documentation​

File Format​

Documentation files use Markdown with frontmatter:

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

# Your Page Title

Your content here...

Frontmatter Fields​

FieldRequiredDescription
titleYesPage title shown in browser and sidebar
descriptionYesBrief description (150-160 characters)
sidebar_positionNoOrder in sidebar (lower numbers appear first)
sidebar_labelNoOverride sidebar text (defaults to title)
slugNoCustom URL path
tagsNoArray of tags for categorization

Markdown Style Guide​

Headings​

Use proper heading hierarchy:

# Page Title (H1) - One per page

## Main Section (H2)

### Subsection (H3)

#### Minor Section (H4)

Code Blocks​

Always specify the language:

```typescript
// TypeScript code
const example: string = 'Hello';
```

```dart
// Dart code
void main() {
  print('Hello');
}
```

Callouts​

Use Docusaurus admonitions for important information:

:::note
This is a note
:::

:::tip
This is a helpful tip
:::

:::info
This is informational
:::

:::warning
This is a warning
:::

:::danger
This is dangerous
:::

Use relative links for internal documentation:

See [Code Style Guide](./code-style) for more information.
See [Architecture Overview](../architecture/overview).

Use absolute links for external resources:

Learn more about [Docusaurus](https://docusaurus.io/).

Images​

Store images in the static/img/ directory:

![Alt text](/img/screenshots/feature-name.png)

Tables​

Use tables for structured data:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |

Content Guidelines​

Be Clear and Concise​

✅ Good:

To create a new wishlist, click the "Add Wishlist" button.

❌ Bad:

In order to go ahead and create a new wishlist, you would need to click on the button that says "Add Wishlist".

Use Active Voice​

✅ Good:

The system validates the user's credentials.

❌ Bad:

The user's credentials are validated by the system.

Write for Your Audience​

  • User documentation: Focus on tasks and outcomes
  • Developer documentation: Include technical details and code examples
  • API documentation: Provide complete parameter descriptions and examples

Include Examples​

Every concept should have at least one example:

## Authentication

BookWish uses JWT tokens for authentication. Here's how to authenticate a request:

\`\`\`typescript
const response = await fetch('/api/wishlist', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});
\`\`\`

Keep It Updated​

  • Update documentation when you change related code
  • Add a changelog entry for significant documentation changes
  • Mark deprecated features clearly

Local Development​

Prerequisites​

  • Node.js 18+
  • npm or yarn

Setup​

# Navigate to docs site
cd docs-site

# Install dependencies
npm install

# Start development server
npm start

The site will open at http://localhost:3000 with hot reload enabled.

Building​

# Build for production
npm run build

# Serve production build locally
npm run serve

Linting​

# Check for broken links and formatting issues
npm run lint

Making Documentation Changes​

1. Create a Branch​

git checkout -b docs/your-topic

2. Make Your Changes​

  • Add or edit Markdown files
  • Test locally with npm start
  • Check for broken links

3. Submit a Pull Request​

  • Ensure all links work
  • Check that images display correctly
  • Verify proper formatting
  • Add screenshots for UI changes
  • Follow our PR process

Documentation Types​

Tutorials​

Step-by-step guides for completing specific tasks:

# How to Set Up Your First Store

This tutorial walks you through creating your first bookstore on BookWish.

## Prerequisites

- BookWish account
- Email verification complete
- Business information ready

## Steps

### 1. Navigate to Store Setup

Click on the "Shop" tab...

### 2. Enter Business Details

Fill in your business information...

How-To Guides​

Problem-solving guides for specific issues:

# How to Fix Common API Errors

## 401 Unauthorized

This error occurs when...

**Solution:**
1. Check your API key
2. Verify token expiration
3. Ensure proper headers

Reference Documentation​

Complete technical specifications:

# Wishlist API Reference

## GET /api/wishlist/:id

Retrieves a specific wishlist by ID.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | Wishlist UUID |

**Response:**
\`\`\`json
{
  "id": "uuid",
  "name": "My Wishlist",
  "items": []
}
\`\`\`

Explanations​

Conceptual documentation that explains how things work:

# Understanding BookWish Architecture

BookWish uses a three-tier architecture...

## Frontend Layer

The Flutter app provides...

## API Layer

The Node.js backend handles...

## Database Layer

PostgreSQL stores...

Best Practices​

Do's​

✅ Include code examples ✅ Add screenshots for visual features ✅ Link to related documentation ✅ Keep paragraphs short (3-4 sentences) ✅ Use bullet points and numbered lists ✅ Test all code examples ✅ Update related documentation when changing features

Don'ts​

❌ Use jargon without explanation ❌ Include outdated screenshots ❌ Create orphan pages (pages with no links to them) ❌ Copy-paste without adapting to our style ❌ Leave placeholder text like "TODO" or "Coming soon" ❌ Include sensitive information (API keys, passwords)

Getting Help​

If you need help with documentation:

  1. Check the Docusaurus documentation
  2. Look at existing pages for examples
  3. Ask in the development chat
  4. Open an issue with the documentation label

Deployment​

Documentation is automatically deployed when changes are merged to main:

  • Preview deployments: Created for every PR
  • Production deployment: Automatic on merge to main
  • URL: docs.bookwish.io (or wherever hosted)

Maintenance​

Regular Reviews​

Documentation should be reviewed:

  • After major feature releases
  • Quarterly for accuracy
  • When user feedback indicates confusion

Deprecation​

When deprecating features:

:::warning[Deprecated]
This feature is deprecated as of version 2.0 and will be removed in version 3.0.
Use [New Feature](./new-feature) instead.
:::

Style Checklist​

Before submitting documentation:

  • Frontmatter is complete
  • Headings follow proper hierarchy
  • Code blocks specify language
  • Links are working
  • Images are optimized and display correctly
  • Examples are tested
  • Grammar and spelling are correct
  • Content is concise and clear
  • Related pages are linked

References​