Accurate and readable technical documentation for the systems and processes you support every day are imperative if you’re presenting the documentation for an ATO, and are extremely beneficial to non‐technical people as well. This isn’t always an easy task for an engineer because the documentation for the system you’re documenting must be accurate, and you need to be able to write the document so it can be understood (to a certain degree) by nearly anyone who reads that document.
A few days ago, after writing an AAR for a recent team effort to fix one of our sites, I concluded that I could take this document, modify it, and create a detailed technical document for every application we host in AFSOC Cloud/C2MS.
I/we came into an environment where we had very little documentation to begin with, and what we did have was inaccurate. Consequently, my team and I were faced with the daunting task of writing a mountain of documentation. If you’re familiar with this type of situation, keep reading.
Many of the applications we host are similar in technical design. Much of the infra‐structure is nearly identical from the outer perimeter of the cloud all the way down to the instance(s) hosting the application. If you remember “mad‐libs,” or if you’re familiar with standard HTML5 web forms and how fields are populated (manual or automated), the basis of this method of documentation is similar.
AWS has many readily available tools such as AWS Config, the CLI, CloudFormation, Trusted Advisor, and other non‐AWS tools where you extract every bit of technical information necessary to map out an application or infrastructure from start to finish. If you have a template with fields prepared to receive the information extracted from your environment, you have a win‐win situation where you’re saving time and money, and adding value to the overall project, not to mention keeping your ISSM happy. In short, create your template with generic verbiage and fields to receive information, extract the necessary information and assign a parameter value or variable to the fields in the document. Populate the document, check for accuracy, and adjust where necessary.
Obviously, there are a few glossed over details for this brief, but this method of documentation will be used by my team going forward. You could also take this approach and create a pipeline to create documentation. The possibilities are endless!
Written by Dave Nicholls, C2MS Systems Engineer
