As a programmer, code documentation is often hated and shunned. It’s easy to focus on the actual code and hear that it will speak for itself in the future, or that you will go back and put the documentation in at the end.
Programmatically, one move towards self-documentation is to use meaningful names, for example Client’s name, client code And customer_street_address. But this rarely happens, and when changes are needed, new programmers doing the updates are left looking for information that makes little or no sense and therefore fails to document their changes.
Fortunately, documentation systems have matured and newer approaches mean that manual documentation, or forced documentation, is not always necessary.
Choose the right tool
Computer-aided software engineering (CASE) tools often have some degree of self-documenting capability. These revolve around the ability to produce:
- data flows and entity models;
- a high-level design document;
- a requirement / model relationship document;
- a functional and process description;
- a series of test cases; And
- system administrator documentation.
Don’t see documentation as something to write and forget. Keep each as an up-to-date and alive document.
Along with this series of technical documents, there should also be:
- cost documentation
- reports and metrics
- help desk documentation
- end user documentation
CASE tools must adapt to the way organizations approach tool development. The days of monolithic physical applications are passing, as the new world of highly virtualized and cloud-based platforms working with VMs and microservices takes over.
Cascading, or cascading, approaches to project management have transformed through agile in the DevOps world of continuous development and delivery along with continuous improvement. This makes continual documentation updates more difficult and necessary. Organizations must ensure that all tools considered are suitable for their approaches to the software development lifecycle. Administrators need to understand which parts of the documentation process can be automated and which parts require manual intervention.
Automation of DevOps documentation
Modern DevOps systems create documents that cover most of the first set of bullet points above, aside from test cases and system administrator documents. Few will even try to create the second set of documents. This is where a role remains for technical authors: people who can go through code and processes with a fine-toothed comb to create documentation fit for purpose.
The end user documentation should be readable and understandable by an end user; it should not be expressed in technical terms. Documentation should not be in the form of multiple volumes of hard-bound hard copies or read-only PDFs online. It needs to be available where it is needed, directly within the application, in a single contextual click to users.
Most DevOps tools that offer a visual environment, such as Chef and Puppet, allow for drag-and-drop approaches to designing 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 for mapping API interfaces.
Cloud platforms, such as AWS and Azure, tend to have front ends that help build and maintain the basics needed to document a DevOps environment.
However, don’t depend solely on tools to provide robust documentation. IT administrators have to check everything manually. The basic automated documentation should eliminate the need to create such tomes from scratch, but also require human-eye checks to ensure that the basics – user documentation, administrator, and help desk – do not lead to a domino effect of single project problems. poor automation at an early stage.
Capture and analyze collaboration between DevOps teams. Look for collaboration systems, such as GitHub, Slack, or chat capture systems within the DevOps packages below, and package project management capabilities, such as Atlassian’s Jira. These create the required documentation from simple visual inputs.
Automation of DevOps documentation is still at the beginning of its journey, but the first steps are in motion. IT organizations need to make sure they don’t choose tools that don’t integrate with each other. This leads to pockets of poorly connected documentation that become difficult to maintain. Look for flexible tools that allow for the simplest approach with visual front ends and collaborative capture, with decentralized access capability by system administrators and help desk staff.