Documentation as Code for Network Automation
Building documentation that actually gets used in complex network automation projects
Documentation in network automation isn't just about checking boxes, it's about creating a system that scales with your infrastructure and actually helps your team operate more effectively. Drawn from a recent conversation among seasoned engineers in the NAF community, here are some practical insights that should help when you're knee-deep in a complex project with "lots of moving parts."
The Documentation-as-Code Revolution
The most compelling trend emerging in network automation documentation is treating docs the same way we treat infrastructure: as code. This isn't just philosophical; it's practical. When your network configurations are version-controlled, your documentation should be too.
Jose Miguel Izquierdo's AutoCon2 presentation on using Mermaid for "Documentation as Code" highlights a key insight: your network diagrams and documentation should be generated from the same source of truth as your configurations. This eliminates the classic problem of documentation becoming stale the moment it's written.
Practical Implementation:
Store documentation in the same repositories as your automation code
Use tools like Mermaid to generate network diagrams from structured data
Implement automated documentation builds in your CI/CD pipelines
Version your docs alongside your infrastructure changes
The Diátaxis Framework: Structure That Actually Works
One of the most actionable recommendations from the discussion centers on the Diátaxis framework. This isn't theoretical, it's a systematic approach that addresses the core problem most network automation teams face: documentation that tries to be everything to everyone and ends up helping no one.
Diátaxis organizes documentation into four distinct categories:
Tutorials - Learning-oriented content that gets new team members productive quickly
How-to guides - Problem-solving oriented content for specific tasks
Technical reference - Information-oriented content for when you need precise details
Explanation - Understanding-oriented content that provides context and background
Why This Matters for Network Automation: Your Ansible playbooks need reference documentation, but your new engineer needs a tutorial on how to use your CI/CD pipeline. Your troubleshooting guides are how-to content, while your architectural decision records are explanations. Trying to mix these creates cognitive overhead that slows your team down.
The Backstage Experiment: Centralizing the Chaos
Perhaps the most intriguing development discussed is Spotify's Backstage platform and its application to infrastructure teams. Stuart Clark (bigevilbeard) from Spotify provided firsthand insights into how Backstage can "unify all your infra tooling, services, and your docs to create a nice streamlined development environment."
The Promise: Instead of remembering "which repo has my network docs," you find documentation through a centralized service catalog. TechDocs, Backstage's documentation component, builds using the same MkDocs process you're likely already familiar with, but centralizes discovery and access.
The Reality Check: John Howard's experience reveals the nuanced truth: Backstage excels for software engineering teams but requires more effort to adapt for traditional network documentation. The value proposition depends heavily on your team's structure and workflow.
When Backstage Makes Sense:
You have infrastructure-as-code engineers who think like software developers
Your team already uses service catalogs or similar abstractions
You're willing to invest in the integration work upfront
You have multiple repositories and struggle with documentation discoverability
When It Might Be Overkill:
Your team is small and documentation discovery isn't a major pain point
You're primarily focused on traditional network documentation
You don't have the development resources to customize and maintain the platform
Tools That Actually Get Used
The conversation reveals some practical tool choices that work in real environments:
MkDocs + Kroki.io - A lightweight combination for generating documentation with embedded diagrams. Kroki.io supports multiple diagram types (PlantUML, Mermaid, GraphViz) through a simple API, making it easy to keep visual documentation in sync with your code.
UML C4 Models - For architectural documentation that needs to communicate structure clearly to both technical and non-technical stakeholders.
Y-Statements for Architectural Decisions - A structured way to document why specific technical choices were made, which becomes invaluable when those decisions need to be revisited months or years later.
The Data Integration Gap
One of the most interesting technical challenges mentioned is the gap between network automation tools and documentation systems. The idea of connecting Backstage to your CMDB/DCIM/IPAM/etc. to automatically maintain documentation sections based on filtered data represents the holy grail: documentation that stays current because it's generated from your network “source of truth.”
This highlights a broader opportunity in the network automation space: we need better "glue code" that connects our various tools. The mention of wanting NetBox MCP (Model Context Protocol) integration with draw.io for on-demand diagram generation points to where the tooling ecosystem needs to evolve.
Starting Simple: The Nautobot Docs Approach
Cristian Sirbu's approach with docs.nautobot.com offers a pragmatic middle ground. By creating a documentation aggregator that pulls together different project docs, you get many of the benefits of centralization without the complexity of a full platform like Backstage.
This approach works particularly well when:
You have multiple related projects that need unified documentation
Your team is comfortable with existing tools like MkDocs
You want better discoverability without major tooling changes
You're inspired by successful examples like docs.ansible.com
Practical Recommendations
Based on the collective wisdom from this discussion, here's a prioritized approach to network automation documentation:
Phase 1: Foundation
Adopt the Diátaxis framework to structure your content
Move documentation into version control alongside your code
Implement basic automation for diagram generation (start with Mermaid)
Phase 2: Integration
Evaluate tools like MkDocs + Kroki.io for your documentation pipeline
Create architectural decision records using Y-statements
Build automated documentation generation into your CI/CD process
Phase 3: Advanced Integration
Consider Backstage if you have the resources and the centralization need
Invest in custom integrations between your network automation tools and documentation systems
Build feedback loops to keep documentation current with your infrastructure changes
The UI/UX Reality Check
Dave Kempe's tongue-in-cheek observation that "having your users read documentation is a sign of UI/UX failure" contains a kernel of truth that network automation teams should consider. The best documentation systems are those that surface information when and where it's needed, not systems that require users to go hunting for answers.
This suggests that as we build network automation workflows, we should think about how to embed contextual help and guidance directly into our tools rather than relying solely on external documentation.
Moving Forward
The future of “full-stack” network documentation lies in tight integration with our automation tools and workflows. The most successful teams will be those that treat documentation as a first-class citizen in their automation pipeline, not an afterthought.
The key insight from this discussion is that there's no one-size-fits-all solution. The right approach depends on your team size, technical sophistication, and existing toolchain. Start with proven frameworks like Diátaxis, embrace documentation-as-code principles, and gradually build toward more integrated solutions as your needs and capabilities evolve.
The goal isn't perfect documentation; it's documentation that makes your team more effective at building and maintaining the complex systems we call networks. Sometimes that means investing in sophisticated platforms like Backstage. Sometimes it means starting with MkDocs and a good organizational framework. The key is starting somewhere and iterating based on real usage patterns and feedback from your team.
This post is based on community discussions and represents the collective experience and opinions of individual practitioners, including: Gabriel Lacerda, Constantin VURLI, Urs Baumann, Christian Mas, Dave Kempe, John Howard, Ryan Shaw, Mark Prosser, Rajiv Gupta, Stuart Clark, Cristian Sirbu. Approaches should be evaluated and adapted based on your specific network environment and requirements.
The conversation continues in the Network Automation Forum community – find us on Slack or LinkedIn.
