blackroad-os-docs/docs/meta/DOCS_CONTRIBUTING.md

id, title, slug, description, tags, status

id	title	slug	description	tags	status
meta-docs-contributing	Docs Contributing Guide	/meta/docs-contributing	Specific guide for contributing to BlackRoad OS documentation	meta contributing documentation	stable

Docs Contributing Guide

📚 This is the detailed contributing guide specifically for the blackroad-os-docs repository.

For general contribution guidelines across all BlackRoad OS repositories, see the main Contributing Guide.

Documentation Structure

See the System Prompt for the complete philosophy and structure of BlackRoad OS documentation.

Quick Reference

Adding New Documentation

1. Choose the right location:

   • docs/overview/ - Architecture and high-level concepts
   • docs/services/ - Service-specific documentation
   • docs/agents/ - Agent ecosystem
   • docs/guides/ - How-to guides
   • docs/runbooks/ - Operational procedures
   • docs/reference/ - API and technical reference
   • docs/ops/ - Operations documentation
   • docs/meta/ - Documentation about documentation

2. Create the file:

   # Use kebab-case for filenames
   touch docs/guides/my-new-guide.md
   

3. Add frontmatter:

   ---
   id: guides-my-new-guide
   title: "My New Guide"
   slug: /guides/my-new-guide
   description: "Brief description"
   tags: ["guides", "topic"]
   status: stable  # or alpha, planned, deprecated
   ---
   

4. Update sidebar: Edit sidebars.ts to add your new page to navigation.

5. Build and verify:

   npm run build
   

Writing Standards

Follow the Style Guide for:

• Markdown conventions
• Heading hierarchy
• Code block formatting
• Link formatting
• Diagram creation

What NOT to Commit

Never commit:

• Binary images (PNG, JPEG, GIF, etc.)
• Secrets or credentials
• Large files
• Build artifacts
• IDE-specific files

See .gitignore for the complete list.

Testing Documentation Changes

Local Development

npm run start
# Visit http://localhost:3000

Production Build

npm run build
npm run serve
# Visit http://localhost:3000

Check for Broken Links

The build process will fail if there are broken links. Fix them before submitting.

Pull Request Process

1. Create a feature branch
2. Make your documentation changes
3. Test locally with npm run build
4. Update sidebar if adding new pages
5. Create PR with clear description
6. Request review

Documentation Types

Refer to the Style Guide for templates and conventions for:

• Architecture Docs
• Service Docs
• Runbooks
• How-To Guides
• Reference Docs

Cross-Linking

Use relative links for internal documentation:

See [Service API](../services/service-api.md)
See [Agent Ecosystem](../agents/agent-ecosystem.md)

Marking Planned Content

For planned but not yet written content:

> 📋 **Status:** This document is planned and will be developed.

Or mark links as planned:

See [Future Guide](./future-guide.md) _(planned)_

Questions?

• Check the System Prompt
• Review the Style Guide
• Look at existing docs for examples
• Open an issue for clarification

See Also

• System Prompt - Documentation philosophy
• Style Guide - Writing standards
• Contributing Guide - General contribution guide
• CONTRIBUTING.md - Quick reference in root