Chapter 9 Dynamic Intent-Based Documentation
For diagrams, tables, or exact code formatting, .
Chapter 9 Dynamic Intent-Based Documentation “Incorrect documentation is often worse than no documentation.” - Bertrand Meyer Now that the network has been converted to code the data models can be used to create dynamic, automated, documentation. All the intent-based variables in the data models can be manipulated to create documentation files for each network device on the network. An Ansible playbook is created to build automated documentation based on intent and data models: documentation.yml. Network documentation is automated as part of the configuration management phase. The output includes:
Dynamically generated intent-based configuration per-device:
o Representative of the running-configuration on the device. o Offline version used for comparison against online running-configuration (coverage, syntax). o Updated as data models or logic changes.
Dynamically generated Markdown files:
o Display data in a different format. o Automated tabular view of custom user written format that is dynamically updated. o .MD file format. Markdown Format As part of the enterprise network automation, generate dynamic documentation in Markdown format. These templates are easy to write reusing much of the template code that has already been written. These Markdown files can present full running-configurations or individual components, such as VLANs, VRFs, routes, port-channels, or physical interface configurations. These automatically generated documents scale with the network and are stored with their own history and version control in TFS.
What is Markdown Format? Markdown is a text-to-HTML conversion tool that allows for easy to read and easy to write friendly format. Output is also very web friendly and well presented in browsers. By using much of the same logic, commands, and syntax a lot of the template code exists to create these documentation templates in Jinaj2.
For more about Markdown please visit: https://daringfireball.net/projects/markdown/ Examples of Dynamic Documentation: Core Documentation
