Getty Images/iStockphoto
How to approach and instate automated IT documentation
Automation can improve workflows, even when it comes to documentation. However, the process isn't foolproof. Here's what you need to know to get started.
As a coder, code documentation is often hated and avoided. It is easy to focus on the actual code and feel it will speak for itself in the future, or that you will go back and put the documentation in at the end.
At a code level, one move toward self-documentation is to use meaningful names, such as customer_name, customer_code and customer_street_address. But this rarely happens, and when changes are required, the new coders performing updates are left looking at information that makes little to no sense, and then they fail to document their own changes.
Luckily, documentation systems have matured, and newer approaches mean that manual documentation -- or forced documentation -- is not always required.
Choose the right tool
Computer-aided software engineering (CASE) tools often come with a degree of self-documenting capabilities. These revolve around the capability to produce:
- data flow and entity models;
- a top-level design document;
- a requirement/model relationship document;
- a functional and process description;
- a set of test cases; and
- system admin documentation.
Do not view documentation as something to write and forget. Keep each as an up-to-date, living document.
Along with this set of technical documents, there should also be:
- cost documentation
- timelines
- reports and metrics
- help desk documentation
- end-user documentation
CASE tools must fit into how organizations approach tool development. The days of physical monolithic applications are passing, as the new world of highly virtualized, cloud-based platforms operating with VMs and microservices takes over.
Cascade, or waterfall, approaches to project management have morphed through agile into the DevOps world of continuous development and delivery along with continuous improvement. This makes the continued updates of documentation both more difficult and necessary. Organizations must ensure any tools in consideration fit with their own approaches to the software development lifecycle. Admins must understand which parts of the documentation process can be automated and what will require manual intervention.
DevOps documentation automation
Modern DevOps systems create documents covering most of the first set of bullet points above -- apart from the test cases and the system admin documents. Few will even try to create the second set of documents. This is where there remains a role for technical authors -- people who can go through code and processes with a fine-tooth comb to create documentation fit for purpose.
End-user documentation should be readable and understandable by an end user; it should not be couched in technical terms. The documentation should not be in the form of multiple volumes of bound hard copies or online read-only PDFs. It must be available where it is needed -- directly within the application, just a single contextual click away for users.
Most DevOps tools that offer a visual environment -- such as Chef and Puppet -- enable drag-and-drop approaches to design a top-level model. The tools create the data flow and entity models along with the functional and process flows. Orchestration tools, such as those from HashiCorp, BMC and Stonebranch, provide additional functions with deeper capabilities to map API interfaces.
Cloud platforms, such as AWS and Azure, tend to have front ends that help to create and maintain the basics required to document a DevOps environment.
However, do not depend solely on the tools to provide rock-solid documentation. IT admins must check everything manually. Basic automated documentation should eliminate the need to create such tomes from scratch, but also prompt checks with human eyes to ensure the foundational stones -- user, admin and help desk documentation -- don't lead to a domino effect of problems due to a single substandard automation project at an early stage.
Capture and analyze collaboration across DevOps teams. Look to collaboration systems -- such as GitHub, Slack or chat-capture systems within the underlying DevOps packages -- and project management capabilities of packages, like Atlassian's Jira. These create the required documentation from simple visual inputs.
DevOps documentation automation is still early in its journey, but the first steps are in motion. IT organizations must ensure they do not choose tools that do not integrate with each other. This leads to pockets of poorly linked documentation that becomes difficult to maintain. Look to flexible tools that enable the simplest approach with visual front ends and collaborative capture, with a capacity for decentralized access by system admins and help desk staff.
