DOCUMENTATION PLAN

ExaBGP Complete Documentation Overhaul Plan

Overview

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.

File Structure to Create

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

Execution Steps

Phase 1: Setup & Infrastructure (Files 1-2)

1. Create wiki/Home.md - Main wiki homepage with complete navigation tree
2. Update main README.md - Add "Documentation" section linking to wiki

Phase 2: Tier 1 Critical Documentation (Files 3-14)

3. wiki/Getting-Started/Quick-Start.md - 5-minute tutorial
4. wiki/Getting-Started/Installation-Guide.md - Detailed installation
5. wiki/Getting-Started/First-BGP-Session.md - First session walkthrough
6. wiki/API/API-Overview.md - API architecture
7. wiki/API/Text-API-Reference.md - Complete text API
8. wiki/API/JSON-API-Reference.md - Complete JSON API
9. wiki/API/API-Commands.md - All commands reference
10. wiki/Address-Families/FlowSpec/FlowSpec-Overview.md
11. wiki/Address-Families/FlowSpec/Match-Conditions.md
12. wiki/Address-Families/FlowSpec/Actions-Reference.md
13. wiki/Configuration/Configuration-Syntax.md
14. wiki/Configuration/Directives-Reference.md

Phase 3: Tier 2 Important Documentation (Files 15-34)

15. wiki/Use-Cases/DDoS-Mitigation.md
16. wiki/Use-Cases/Anycast-Management.md
17. wiki/Use-Cases/Service-High-Availability.md
18. wiki/Use-Cases/Cross-DC-Failover.md
19. wiki/Operations/Debugging-Guide.md
20. wiki/Operations/Log-Analysis.md
21. wiki/Getting-Started/Common-Pitfalls.md
22. wiki/Address-Families/EVPN/EVPN-Overview.md
23. wiki/Address-Families/EVPN/Route-Types.md
24. wiki/Address-Families/BGP-LS/BGP-LS-Overview.md
25. wiki/Address-Families/BGP-LS/Topology-Collection.md
26. wiki/Address-Families/SRv6-and-MUP.md
27. wiki/Address-Families/L3VPN/VPN-Overview.md
28. wiki/Tools/Healthcheck-Module.md
29. wiki/API/Writing-API-Programs.md
30. wiki/API/Error-Handling.md
31. wiki/API/Production-Best-Practices.md
32. wiki/Configuration/Neighbor-Configuration.md
33. wiki/Configuration/Templates-and-Inheritance.md
34. wiki/Configuration/Environment-Variables.md

Phase 4: Tier 3 Enhancement Documentation (Files 35-69)

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

Phase 5: Reference & Polish (Files 70-75)

70. wiki/Reference/Configuration-A-Z.md
71. wiki/Reference/API-Commands-A-Z.md
72. wiki/Reference/Environment-Variables-A-Z.md
73. wiki/Reference/Error-Codes.md
74. wiki/Reference/Examples-Index.md - Comprehensive index of 98 config examples
75. wiki/Development/Architecture.md (adapted from CLAUDE.md)

Key Content Features

Every Document Will Include:

• 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

Navigation Strategy:

• Home.md: Complete documentation tree
• Each section index links to subsections
• Breadcrumb references
• Related documents cross-linked
• README.md gateway to all docs

Examples Index Strategy:

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

README.md Updates

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

Estimated Scope

• 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

Success Criteria

✅ 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

Implementation Notes

This plan creates a comprehensive documentation system that:

1. Guides new users from installation to first BGP session in minutes
2. Provides complete API reference for the 90% of users who need it
3. Covers all address families with practical examples
4. Documents all major use cases with step-by-step tutorials
5. Includes advanced topics for production deployments
6. Makes all 98 configuration examples discoverable through wiki/Reference/Examples-Index.md
7. Cross-references everything for easy navigation
8. Links from main README.md for discoverability
9. Clearly communicates that ExaBGP does NOT manipulate RIB/FIB