Contributing to Docs

Work in Progress

This documentation is actively maintained alongside the Rax platform. Features may change frequently.

This guide explains how to add or update documentation for the Rax platform.

Running Locally

cd docs-site
npm install
npm start

This opens the docs at http://localhost:3000.

File Structure

docs-site/
├── docs/
│   ├── getting-started/    # Platform overview, access, roles
│   ├── Development/            # Development app features
│   ├── Operations/            # Operations app features
│   ├── Production/           # Legacy sales app features
│   ├── intro.md            # Landing page
│   └── contributing.md     # This file
├── blog/                   # Changelog entries (renders at /changelog)
├── src/                    # Custom pages and CSS
├── static/img/             # Images and logos
├── docusaurus.config.ts    # Site configuration
└── sidebars.ts             # Sidebar navigation

Adding a New Feature Page

1. Identify the correct app folder (Development/, Operations/, or Production/)
2. Create a new .md file in the relevant subfolder
3. Add frontmatter with sidebar_label and sidebar_position
4. Required: Include the Work in Progress admonition at the top:

:::warning[Work in Progress]
This documentation is actively maintained alongside the Rax platform. Features may change frequently.
:::

5. Write the content in plain language (the audience is company employees, not developers)
6. Run npm run build to verify there are no broken links

Adding a Changelog Entry

Changelog entries live in docs-site/blog/ and track breaking changes and updates.

1. Create a new file: blog/YYYY-MM-DD-short-title.md
2. Add frontmatter:

---
title: "Short description of the change"
authors: [your-name]
tags: [breaking-change, Development]
---

3. Describe what changed, why, and what users need to do differently
4. Use <!--truncate--> to separate the summary from the full details

Capturing Screenshots

Screenshots are stored in docs-site/static/img/screenshots/{app}/{role}/ where:

• {app} is development, operations, or production
• {role} is admin, dep-lead, team-lead, or member

Process

1. Start the target app on localhost:3013 (only one app at a time)
2. Use the playwright-testing skill in Claude Code to coordinate Playwright instances
3. Log in with the test account for each role (all passwords: rax@1234)
4. Navigate to each page, wait for data to load, and take a 1440×900 PNG screenshot
5. Save to the correct {app}/{role}/ directory with a descriptive filename

Re-capturing Screenshots

Re-capture screenshots after significant UI changes. The apps share roles:

Role	Development	Operations	Production
admin	Yes	Yes	Yes
dep_lead	Yes	Yes	Yes
team_lead	Yes	Yes	Yes
member	Yes	Yes	Yes
sales_lead	—	—	Yes

Adding Role-Specific Content

Use Docusaurus Tabs with groupId="user-role" to show role-specific content:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs groupId="user-role" queryString="role">
  <TabItem value="admin" label="Admin">
    Admin-specific content here.
  </TabItem>
  <TabItem value="dep_lead" label="Department Lead">
    Department lead content here.
  </TabItem>
  <TabItem value="team_lead" label="Team Lead">
    Team lead content here.
  </TabItem>
  <TabItem value="member" label="Member">
    Member content here.
  </TabItem>
</Tabs>

The queryString="role" parameter makes the selected role persist in the URL, so users can share role-specific links.

Directory Naming Conventions

App Code	Documentation Name	Folder
rax-dev	Development	docs/development/
rax-ops	Operations	docs/operations/
rax-prod	Production	docs/production/

Always use the human-readable name in documentation text (e.g., "Development", not "rax-dev").

Conventions

• Every page must have the "Work in Progress" admonition banner
• Use simple, non-technical language where possible
• Use screenshots or step-by-step instructions for complex workflows
• Keep pages focused on one feature or topic
• Use admonitions (:::tip, :::info, :::warning, :::danger) for callouts

Building for Production

npm run build

This generates static files in build/. Fix any errors before committing.