1845e069e0
- Add SYSTEM_PROMPT.md with full documentation philosophy - Add STYLE_GUIDE.md with detailed writing standards - Create services/ directory with docs for API, Operator, Core, Web, Prism, Infra - Create agents/ directory with agent ecosystem documentation - Create guides/ directory with getting-started and contributing guides - Create runbooks/ directory with incident playbook and deployment runbooks - Create reference/ directory with API reference placeholder - Update sidebars.ts to include all new sections - Update CONTRIBUTING.md to reference new comprehensive guides - Update .gitignore to exclude binary assets per system prompt requirements - All documentation builds successfully with no broken links Co-authored-by: blackboxprogramming <118287761+blackboxprogramming@users.noreply.github.com>
151 lines
3.6 KiB
Markdown
151 lines
3.6 KiB
Markdown
---
|
|
id: meta-docs-contributing
|
|
title: "Docs Contributing Guide"
|
|
slug: /meta/docs-contributing
|
|
description: "Specific guide for contributing to BlackRoad OS documentation"
|
|
tags: ["meta", "contributing", "documentation"]
|
|
status: 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](guides/contributing.md).
|
|
|
|
## Documentation Structure
|
|
|
|
See the [System Prompt](meta/SYSTEM_PROMPT.md) 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:**
|
|
```bash
|
|
# Use kebab-case for filenames
|
|
touch docs/guides/my-new-guide.md
|
|
```
|
|
|
|
3. **Add frontmatter:**
|
|
```yaml
|
|
---
|
|
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:**
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
## Writing Standards
|
|
|
|
Follow the [Style Guide](meta/STYLE_GUIDE.md) 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
|
|
```bash
|
|
npm run start
|
|
# Visit http://localhost:3000
|
|
```
|
|
|
|
### Production Build
|
|
```bash
|
|
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](meta/STYLE_GUIDE.md) for templates and conventions for:
|
|
- Architecture Docs
|
|
- Service Docs
|
|
- Runbooks
|
|
- How-To Guides
|
|
- Reference Docs
|
|
|
|
## Cross-Linking
|
|
|
|
Use relative links for internal documentation:
|
|
|
|
```md
|
|
See [Service API](../services/service-api.md)
|
|
See [Agent Ecosystem](../agents/agent-ecosystem.md)
|
|
```
|
|
|
|
## Marking Planned Content
|
|
|
|
For planned but not yet written content:
|
|
|
|
```md
|
|
> 📋 **Status:** This document is planned and will be developed.
|
|
```
|
|
|
|
Or mark links as planned:
|
|
```md
|
|
See [Future Guide](./future-guide.md) _(planned)_
|
|
```
|
|
|
|
## Questions?
|
|
|
|
- Check the [System Prompt](meta/SYSTEM_PROMPT.md)
|
|
- Review the [Style Guide](meta/STYLE_GUIDE.md)
|
|
- Look at existing docs for examples
|
|
- Open an issue for clarification
|
|
|
|
## See Also
|
|
|
|
- [System Prompt](meta/SYSTEM_PROMPT.md) - Documentation philosophy
|
|
- [Style Guide](meta/STYLE_GUIDE.md) - Writing standards
|
|
- [Contributing Guide](guides/contributing.md) - General contribution guide
|
|
- [CONTRIBUTING.md](https://github.com/BlackRoad-OS/blackroad-os-docs/blob/main/CONTRIBUTING.md) - Quick reference in root
|