docs: align internal docs to enterprise standards
All checks were successful
CI / verify (push) Successful in 2m33s
All checks were successful
CI / verify (push) Successful in 2m33s
Add canonical operations/security/access/feature docs and fix path integrity to improve onboarding and incident readiness.
This commit is contained in:
Joseph Doherty
116
docs/README.md
116
docs/README.md
@@ -1,73 +1,45 @@
|
||||
# CBDDC Documentation
|
||||
|
||||
This folder contains the official documentation for CBDDC, published as GitHub Pages.
|
||||
|
||||
## Documentation Structure (v0.9.0)
|
||||
|
||||
### Getting Started
|
||||
- **[Getting Started](getting-started.md)** - Installation, setup, and first steps with CBDDC
|
||||
|
||||
### Core Documentation
|
||||
- **[Architecture](architecture.md)** - Hybrid Logical Clocks, Gossip Protocol, mesh networking
|
||||
- **[API Reference](api-reference.md)** - Complete API documentation with examples
|
||||
- **[Querying](querying.md)** - Data querying patterns and LINQ support
|
||||
|
||||
### Persistence & Storage
|
||||
- **[Persistence Providers](persistence-providers.md)** - SQLite, EF Core, PostgreSQL comparison
|
||||
- **[Deployment Modes](deployment-modes.md)** - Single-cluster deployment strategy
|
||||
|
||||
### Networking & Security
|
||||
- **[Security](security.md)** - Encryption, authentication, secure networking
|
||||
- **[Conflict Resolution](conflict-resolution.md)** - LWW and Recursive Merge strategies
|
||||
- **[Network Telemetry](network-telemetry.md)** - Monitoring and diagnostics
|
||||
- **[Dynamic Reconfiguration](dynamic-reconfiguration.md)** - Runtime configuration changes
|
||||
- **[Remote Peer Configuration](remote-peer-configuration.md)** - Managing remote peers and tracking lifecycle
|
||||
- **[Upgrade: Peer-Confirmed Pruning](upgrade-peer-confirmed-pruning.md)** - Rollout notes and adoption checklist
|
||||
# CBDDC Documentation Index
|
||||
|
||||
### Deployment & Operations
|
||||
- **[Deployment (LAN)](deployment-lan.md)** - Platform-specific deployment guide
|
||||
- **[Production Hardening](production-hardening.md)** - Configuration, monitoring, best practices
|
||||
- **[Peer Deprecation & Removal Runbook](peer-deprecation-removal-runbook.md)** - Operational workflow for de-tracking and removal
|
||||
|
||||
## Building the Documentation
|
||||
|
||||
This documentation uses Jekyll with the Cayman theme and is automatically published via GitHub Pages.
|
||||
|
||||
### Local Development
|
||||
|
||||
```bash
|
||||
# Install Jekyll (requires Ruby)
|
||||
gem install bundler jekyll
|
||||
|
||||
# Serve documentation locally
|
||||
cd docs
|
||||
jekyll serve
|
||||
|
||||
# Open http://localhost:4000
|
||||
```
|
||||
|
||||
### Site Configuration
|
||||
|
||||
- **_config.yml** - Jekyll configuration and site metadata
|
||||
- **_layouts/default.html** - Main page layout with navigation and styling
|
||||
- **_includes/nav.html** - Top navigation bar
|
||||
- **_data/navigation.yml** - Sidebar navigation structure per version
|
||||
|
||||
## Version History
|
||||
|
||||
The documentation supports multiple versions:
|
||||
- **v0.9** (current) - Latest stable release
|
||||
- **v0.8** - ASP.NET Core hosting, EF Core, PostgreSQL support
|
||||
- **v0.7** - Brotli compression, Protocol v4
|
||||
- **v0.6** - Secure networking, conflict resolution strategies
|
||||
|
||||
## Contributing to Documentation
|
||||
|
||||
1. **Fix typos or improve clarity** - Submit PRs directly
|
||||
2. **Add new guides** - Create a new .md file and update navigation.yml
|
||||
3. **Test locally** - Run Jekyll locally to preview changes before submitting
|
||||
|
||||
## Links
|
||||
|
||||
- [Main Repository](https://github.com/CBDDC/ZB.MOM.WW.CBDDC.Net)
|
||||
- [NuGet Packages](https://www.nuget.org/packages?q=CBDDC)
|
||||
This folder contains operational and engineering documentation for CBDDC.
|
||||
|
||||
## Core Documentation
|
||||
|
||||
- [Architecture](architecture.md)
|
||||
- [Deployment](deployment.md)
|
||||
- [Runbook](runbook.md)
|
||||
- [Security](security.md)
|
||||
- [Access and Permissions](access.md)
|
||||
- [Troubleshooting](troubleshooting.md)
|
||||
|
||||
## Feature Documentation
|
||||
|
||||
- [Feature Inventory](features/README.md)
|
||||
- [Selective Collection Sync](features/selective-collection-sync.md)
|
||||
- [Peer-to-Peer Gossip Sync](features/peer-to-peer-gossip-sync.md)
|
||||
- [Secure Peer Transport](features/secure-peer-transport.md)
|
||||
- [Peer-Confirmed Pruning](features/peer-confirmed-pruning.md)
|
||||
|
||||
## Additional Technical References
|
||||
|
||||
- [Getting Started](getting-started.md)
|
||||
- [API Reference](api-reference.md)
|
||||
- [Conflict Resolution](conflict-resolution.md)
|
||||
- [Persistence Providers](persistence-providers.md)
|
||||
- [Network Telemetry](network-telemetry.md)
|
||||
- [Dynamic Reconfiguration](dynamic-reconfiguration.md)
|
||||
- [Remote Peer Configuration](remote-peer-configuration.md)
|
||||
- [Upgrade: Peer-Confirmed Pruning](upgrade-peer-confirmed-pruning.md)
|
||||
- [Peer Deprecation and Removal Runbook](peer-deprecation-removal-runbook.md)
|
||||
- [Database Sync Manager Design](database-sync-manager-design.md)
|
||||
|
||||
## Deployment-Specific Guides
|
||||
|
||||
- [Deployment Modes](deployment-modes.md)
|
||||
- [Deployment (LAN)](deployment-lan.md)
|
||||
- [Production Hardening](production-hardening.md)
|
||||
|
||||
## Documentation Conventions
|
||||
|
||||
- Use lowercase kebab-case for markdown files.
|
||||
- Keep canonical operational docs at the top level under `docs/`.
|
||||
- Store major feature documentation in `docs/features/` and keep `docs/features/README.md` updated.
|
||||
|
||||
Reference in New Issue
Block a user