-
Notifications
You must be signed in to change notification settings - Fork 461
DOCUMENTATION PLAN
Thomas Mangin edited this page Nov 10, 2025
·
1 revision
Create comprehensive user documentation covering all tiers (beginner to advanced), organize 98 configuration examples within the wiki, and integrate everything with clear navigation.
Scope: All documentation lives in the wiki/ directory. The main README.md will be updated to link to the wiki. No separate etc/exabgp/README.md will be created - examples will be indexed in wiki/Reference/Examples-Index.md.
wiki/
├── Home.md # Wiki homepage with navigation
├── Getting-Started/
│ ├── Quick-Start.md # 5-minute getting started
│ ├── Installation-Guide.md # Detailed installation
│ ├── First-BGP-Session.md # Step-by-step first session
│ ├── Architecture-Overview.md # ExaBGP architecture explained
│ └── Common-Pitfalls.md # Troubleshooting for beginners
├── Configuration/
│ ├── Configuration-Syntax.md # File format & syntax
│ ├── Neighbor-Configuration.md # Neighbor settings reference
│ ├── Static-Routes.md # Route announcement
│ ├── Templates-and-Inheritance.md # Template system
│ ├── Environment-Variables.md # Complete env var reference
│ ├── Signal-Handling.md # Signal reference
│ └── Directives-Reference.md # A-Z directive listing
├── API/
│ ├── API-Overview.md # API concepts
│ ├── Text-API-Reference.md # Text format complete reference
│ ├── JSON-API-Reference.md # JSON format complete reference
│ ├── Writing-API-Programs.md # Best practices
│ ├── API-Commands.md # All commands documented
│ ├── Error-Handling.md # API error handling
│ └── Production-Best-Practices.md # Production deployment
├── Address-Families/
│ ├── IPv4-IPv6-Unicast.md # Basic unicast
│ ├── FlowSpec/
│ │ ├── FlowSpec-Overview.md # Introduction
│ │ ├── Match-Conditions.md # All match types
│ │ ├── Actions-Reference.md # All actions
│ │ └── DDoS-Mitigation.md # DDoS use case
│ ├── L3VPN/
│ │ ├── VPN-Overview.md # L3VPN introduction
│ │ ├── Route-Distinguishers.md # RD types explained
│ │ └── Route-Targets.md # RT usage
│ ├── EVPN/
│ │ ├── EVPN-Overview.md # EVPN introduction
│ │ ├── Route-Types.md # EVPN route types 1-5
│ │ └── MAC-IP-Advertisement.md # Practical guide
│ ├── BGP-LS/
│ │ ├── BGP-LS-Overview.md # Link-State introduction
│ │ ├── Topology-Collection.md # Receive-only mode
│ │ └── Attributes-Reference.md # BGP-LS attributes
│ ├── VPLS.md # VPLS/L2VPN guide
│ ├── MVPN.md # Multicast VPN guide
│ └── SRv6-and-MUP.md # Segment Routing
├── Use-Cases/
│ ├── DDoS-Mitigation.md # Complete DDoS walkthrough
│ ├── Anycast-Management.md # Anycast patterns
│ ├── Service-High-Availability.md # HA with healthcheck
│ ├── Cross-DC-Failover.md # Multi-DC patterns
│ ├── BGP-LS-Visualization.md # Topology collection
│ ├── CDN-Route-Injection.md # CDN use case
│ └── Traffic-Engineering.md # TE patterns
├── Features/
│ ├── Capabilities/
│ │ ├── ADD-PATH.md # Multi-path advertisement
│ │ ├── Graceful-Restart.md # GR implementation
│ │ ├── Route-Refresh.md # Route refresh
│ │ ├── Extended-Message.md # Large messages
│ │ └── Four-Byte-ASN.md # 4-byte ASN support
│ ├── Communities/
│ │ ├── Standard-Communities.md # RFC 1997
│ │ ├── Extended-Communities.md # RFC 4360
│ │ └── Large-Communities.md # RFC 8092
│ ├── Attributes/
│ │ ├── Well-Known-Attributes.md # Mandatory attributes
│ │ ├── Optional-Attributes.md # Optional attributes
│ │ └── Generic-Attributes.md # Generic attribute support
│ └── Route-Reflection.md # IBGP route reflection
├── Tools/
│ ├── Healthcheck-Module.md # Built-in healthcheck
│ ├── ExaBGP-CLI.md # CLI tool
│ ├── Message-Decoder.md # Decode tool
│ └── Configuration-Validator.md # Validation
├── Operations/
│ ├── Deployment-Patterns.md # Production deployment
│ ├── Monitoring-and-Metrics.md # Monitoring guide
│ ├── Performance-Tuning.md # Optimization
│ ├── Debugging-Guide.md # Debug methodology
│ ├── Log-Analysis.md # Log interpretation
│ ├── Security-Best-Practices.md # Security hardening
│ └── Capacity-Planning.md # Scaling guide
├── Integration/
│ ├── Docker-Deployment.md # Docker best practices
│ ├── Kubernetes.md # K8s deployment
│ ├── FRRouting-Integration.md # FRR integration
│ ├── BIRD-Integration.md # BIRD integration
│ ├── Prometheus-Grafana.md # Monitoring setup
│ └── Ansible-Automation.md # Automation examples
├── Development/
│ ├── Architecture.md # From CLAUDE.md
│ ├── Contributing.md # Contribution guide
│ ├── Testing.md # Test framework
│ ├── Code-Structure.md # Codebase layout
│ └── Extending-ExaBGP.md # Plugin development
├── Reference/
│ ├── Configuration-A-Z.md # All directives
│ ├── API-Commands-A-Z.md # All API commands
│ ├── Environment-Variables-A-Z.md # All env vars
│ ├── Error-Codes.md # Error reference
│ ├── RFC-Compliance.md # Link to RFC-SUPPORT.md
│ └── Examples-Index.md # Link to examples
└── Migration/
├── From-3.4-to-4.x.md # 3.4 migration
├── From-4.2-to-5.0.md # 5.0 migration (new)
├── Breaking-Changes.md # All breaking changes
└── Version-Comparison.md # Feature comparison
README.md # Update with doc links to wiki
- Create
wiki/Home.md- Main wiki homepage with complete navigation tree - Update main
README.md- Add "Documentation" section linking to wiki
-
wiki/Getting-Started/Quick-Start.md- 5-minute tutorial -
wiki/Getting-Started/Installation-Guide.md- Detailed installation -
wiki/Getting-Started/First-BGP-Session.md- First session walkthrough -
wiki/API/API-Overview.md- API architecture -
wiki/API/Text-API-Reference.md- Complete text API -
wiki/API/JSON-API-Reference.md- Complete JSON API -
wiki/API/API-Commands.md- All commands reference wiki/Address-Families/FlowSpec/FlowSpec-Overview.mdwiki/Address-Families/FlowSpec/Match-Conditions.mdwiki/Address-Families/FlowSpec/Actions-Reference.mdwiki/Configuration/Configuration-Syntax.mdwiki/Configuration/Directives-Reference.md
wiki/Use-Cases/DDoS-Mitigation.mdwiki/Use-Cases/Anycast-Management.mdwiki/Use-Cases/Service-High-Availability.mdwiki/Use-Cases/Cross-DC-Failover.mdwiki/Operations/Debugging-Guide.mdwiki/Operations/Log-Analysis.mdwiki/Getting-Started/Common-Pitfalls.mdwiki/Address-Families/EVPN/EVPN-Overview.mdwiki/Address-Families/EVPN/Route-Types.mdwiki/Address-Families/BGP-LS/BGP-LS-Overview.mdwiki/Address-Families/BGP-LS/Topology-Collection.mdwiki/Address-Families/SRv6-and-MUP.mdwiki/Address-Families/L3VPN/VPN-Overview.mdwiki/Tools/Healthcheck-Module.mdwiki/API/Writing-API-Programs.mdwiki/API/Error-Handling.mdwiki/API/Production-Best-Practices.mdwiki/Configuration/Neighbor-Configuration.mdwiki/Configuration/Templates-and-Inheritance.mdwiki/Configuration/Environment-Variables.md
35-44. Complete all remaining Address-Families documentation 45-51. Complete all Use-Cases documentation 52-59. Complete all Features documentation 60-64. Complete all Integration documentation 65-67. Complete all Migration documentation 68-69. Complete all Operations documentation
wiki/Reference/Configuration-A-Z.mdwiki/Reference/API-Commands-A-Z.mdwiki/Reference/Environment-Variables-A-Z.mdwiki/Reference/Error-Codes.md-
wiki/Reference/Examples-Index.md- Comprehensive index of 98 config examples -
wiki/Development/Architecture.md(adapted from CLAUDE.md)
- Clear table of contents
- Practical examples from etc/exabgp/
- Cross-references to related docs
- "See Also" section
- Code examples with explanations
- Common errors and solutions
- Home.md: Complete documentation tree
- Each section index links to subsections
- Breadcrumb references
- Related documents cross-linked
- README.md gateway to all docs
wiki/Reference/Examples-Index.md will categorize 98 config files by:
- User experience level (Beginner/Intermediate/Advanced)
- Use case (DDoS/Anycast/VPN/etc)
- Feature (FlowSpec/EVPN/BGP-LS/etc)
- Protocol family (IPv4/IPv6/VPN/etc)
- All examples link directly to the etc/exabgp/ directory in the repository
Add new "Documentation" section:
## Documentation
Complete documentation is available in the [ExaBGP Wiki](https://github.com/Exa-Networks/exabgp/wiki):
- **[Quick Start Guide](https://github.com/Exa-Networks/exabgp/wiki/Getting-Started/Quick-Start)** - Get running in 5 minutes
- **[API Reference](https://github.com/Exa-Networks/exabgp/wiki/API/API-Overview)** - Complete API documentation
- **[Configuration Guide](https://github.com/Exa-Networks/exabgp/wiki/Configuration/Configuration-Syntax)** - Configuration reference
- **[Use Cases](https://github.com/Exa-Networks/exabgp/wiki/Use-Cases)** - DDoS mitigation, anycast, HA, and more
- **[Address Families](https://github.com/Exa-Networks/exabgp/wiki/Address-Families)** - FlowSpec, EVPN, BGP-LS, L3VPN, SRv6
- **[Examples Index](https://github.com/Exa-Networks/exabgp/wiki/Reference/Examples-Index)** - Browse 98 configuration examples
- **[RFC Compliance](https://github.com/Exa-Networks/exabgp/wiki/Reference/RFC-Compliance)** - 55+ RFCs implemented- Total files: ~75 markdown files (all in wiki/)
- Total content: ~600-800 pages equivalent
- Examples covered: All 98 configuration files indexed and explained in wiki
- Cross-references: ~300+ internal links
✅ Complete documentation coverage (beginner to advanced) ✅ All 98 examples categorized and explained in wiki/Reference/Examples-Index.md ✅ API fully documented (text + JSON) ✅ Every address family has guide ✅ Every major use case has tutorial ✅ Clear navigation from README.md to wiki ✅ Cross-referenced throughout ✅ Practical examples in every doc ✅ Emphasis on "No RIB/FIB manipulation" throughout
This plan creates a comprehensive documentation system that:
- Guides new users from installation to first BGP session in minutes
- Provides complete API reference for the 90% of users who need it
- Covers all address families with practical examples
- Documents all major use cases with step-by-step tutorials
- Includes advanced topics for production deployments
- Makes all 98 configuration examples discoverable through wiki/Reference/Examples-Index.md
- Cross-references everything for easy navigation
- Links from main README.md for discoverability
- Clearly communicates that ExaBGP does NOT manipulate RIB/FIB
Getting Started
Configuration
- Configuration Syntax
- Neighbor Configuration
- Directives A-Z
- Templates
- Environment Variables
- Process Configuration
API
- API Overview
- Text API Reference
- JSON API Reference
- API Commands
- Writing API Programs
- Error Handling
- Production Best Practices
Address Families
- Overview
- IPv4 Unicast
- IPv6 Unicast
- FlowSpec
- EVPN
- L3VPN
- BGP-LS
- VPLS
- SRv6 / MUP
- Multicast
- RT Constraint
Features
Use Cases
Tools
Operations
Reference
- Architecture
- Design
- Attribute Reference
- Command Reference
- BGP State Machine
- Capabilities
- Communities
- Examples Index
- Glossary
- RFC Support
Integration
Migration
Community
External