Contributing to Documentation

How to Update Documentation

Adding JSDoc Comments

When writing TypeScript/React code, add JSDoc comments:

/**
 * Suggests the best driver for a shipment based on availability and workload.
 * 
 * @param shipments - Array of shipment insights
 * @param drivers - Array of driver insights
 * @param options - Optional configuration
 * @returns Suggestion result with driver ID, score, and reason
 * 
 * @example
 * ```ts
 * const suggestion = suggestDriver(shipments, drivers, { targetZoneId: 'zone-1' });
 * if (suggestion.id) {
 *   assignDriver(suggestion.id);
 * }
 * ```
 */
export function suggestDriver(
  shipments: ShipmentInsight[],
  drivers: DriverInsight[],
  options?: { targetZoneId?: string | null }
): SuggestionResult {
  // ...
}

Documenting Components

Add JSDoc comments to React components:

/**
 * Barcode scanner component using device camera.
 * 
 * @example
 * ```tsx
 * <BarcodeScanner
 *   active={isOpen}
 *   onDetected={(value) => handleScan(value)}
 *   onError={(error) => console.error(error)}
 * />
 * ```
 */
export function BarcodeScanner({ active, onDetected, onError }: BarcodeScannerProps) {
  // ...
}

Documenting Props

Define props interfaces with comments:

interface BarcodeScannerProps {
  /** Toggle the scanner on/off from parent component */
  active: boolean;
  /** Called every time a barcode is decoded */
  onDetected: (value: string) => void;
  /** Notified when the user denies the camera or another error occurs */
  onError?: (message: string) => void;
}

Updating Database Documentation

Database documentation is auto-generated from SQL migrations. To update:

1. Add comments in SQL migration files:

-- Creates driver_locations table for GPS tracking
-- Stores real-time driver positions with lat/lng coordinates
CREATE TABLE driver_locations (
  driver_id UUID PRIMARY KEY REFERENCES profiles(id),
  lat DECIMAL(10, 8) NOT NULL,
  lng DECIMAL(11, 8) NOT NULL,
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

2. Run documentation generator:

npm run docs:generate:database

Adding New Documentation Pages

1. Create markdown file in appropriate directory:

   • docs/ - Main documentation
   • docs/api/ - API documentation
   • docs/components/ - Component documentation
   • docs/database/ - Database documentation

2. Add to navigation in .vitepress/config.ts:

sidebar: {
  '/api/': [
    {
      text: 'API Reference',
      items: [
        { text: 'New Page', link: '/api/new-page' }
      ]
    }
  ]
}

3. Commit and push changes

Workflow

Before Committing

1. Generate documentation:

   npm run docs:generate

2. Preview changes:

   npm run docs:dev

3. Verify formatting:

   • Check markdown syntax
   • Verify code examples work
   • Test links

After Committing

Documentation is automatically:

• Generated on push to main
• Published to GitHub Pages
• Available at https://your-org.github.io/lager-guru/

Documentation Standards

Markdown Format

• Use proper heading hierarchy (h1 → h2 → h3)
• Include code blocks with language tags
• Add tables for structured data
• Use lists for step-by-step instructions

Code Examples

Always include working code examples:

```tsx
import { useAuth } from '@/contexts/AuthContext';

function MyComponent() {
  const { user } = useAuth();
  return <div>Hello {user?.email}</div>;
}
```

Links

Use relative links within documentation:

[Architecture](./architecture.md)
[API Reference](./api/)

Images

Place images in docs/public/ and reference:

![Architecture Diagram](./public/architecture.png)

Best Practices

1. Keep it updated - Documentation should match code
2. Be clear - Write for developers who don't know the codebase
3. Include examples - Show, don't just tell
4. Test examples - Ensure code examples work
5. Review regularly - Update docs when code changes

Questions?

• Check existing documentation for examples
• Review VitePress docs
• Ask in GitHub Discussions