A few months ago I wrote a post about Documentation as Code which was an extension of a proof of concept (POC) I put together at work. Simply put, build some awesome gold templates for your documentation in a mark up/mark down format of your choice [1], check it into the SCM [2] of your choice and then have a system collect information for you and fill in the blanks.
There seems to be a bit of interest regarding automatically updating documentation on https://networktocode.slack.com #cicd channel, so, I thought I’d post a few more musings.
[1] POC was using AsciiDoc and AsciiDoctor
[2] POC was using Git
Documentation as Code System (DACS)
Lacking a more creative name, DACS seem to portray what was trying to achieve.
The idea was to create a few containers/microservices to carry tasks to produce documentation. Some distinct functions that come to mind:
- Webfront end (basic, to start a new project and start builds)
- Source Control (external, or, interchangeable). Contains:
- Gold templates
- Clone templates which become live artifacts
- CMDB – Define systems to be documented
- Hostname
- IP details
- Credentials / access method
- Data gathering
- Filling the gaps (substituting) data into the templates (and checking into repo)
- Could also build the learnt CI CMDB and relationships between configuration items here
- Documentation builders (acsiidoctor in POC, but, interchangeable if other mark up/mark down formats desired)
- Building the HTML/PDF/desired format
- Delivering the outputted documentation
- Uploading to various locations (SCP/FTP/Sharepoint/Documentation store)
- Emailing to end user
The Dream
Architects building a solution pick from gold templates and create a new solution.
- Consider building gold templates for Business Service Catalogues (BSC) and Technical Service Catalogues (TSC) items.
Build engineers build the solution and add the devices to DACS. DACS audits the environment and fills in the documentation blanks. Repositories and end users updated with freshly minted documentation.
Future changes in the environment are then captured and documentation updated by:
- Scheduled periodic tasks to ensure documentation is up-to-date
- Triggered by CI/CD pipelines when a change is made in the environment
- Manually triggered by the change implementer
Diagrams could also be built with the CMDB and relationship information we’ve gathered during data gathering, with, diagrams inserted into the documentation repository/end document.
No more decaying documentation lying around. 🙂
Data flow
Trying to map out the data flow….
