DevOps: How do you automate updates to source code comments and system documentation?

The "Editor's note" Computer software is traditionally defined as: Software is another part of the computer system that is dependent on the hardware, and the software includes a complete set of programs, data, and related documents. In today's development, however, the compliance of documents is often overlooked. This article, written by Todd Waits, describes the 3 major challenges encountered in application documentation and is expanded below. This paper is a OneAPM combined efficient operation and maintenance compilation.

Typically, formal documentation (such as source code documents, system requirements and design documents, or various user documentation) is overlooked by the development team, and the philosophy of the process and documentation in DEVOPS can help mitigate this problem. Software documentation is typically divided into the following categories: code, requirements, design, system, and user documentation. One of the reasons that documents are often overlooked is that if they are not matched to the development tools they rely on, such as version control, problem tracking, wiki, and source code, standard document tools and processes will hinder the development team and slow down development.

This post explores the 3 main challenges of documentation: processes, annotation source code, and system documentation, and explains how DevOps-based documents can enable all stakeholders to access a common, trusted source of information to see the details of the project.

Problem flow

When creating and maintaining user documentation and system documentation, operators often use cumbersome binary documents (such as *. docx). In general, in the document collaboration system, also includes a long list of back-and-forth e-mails, or network-shared files, people use these forms to each other to transfer the updated version of the document. In addition, specialized formats (*. docx and generated PDFs) tend to be inconsistent across system operations, resulting in data corruption when working across teams, often due to different work environments.

Storing binaries in a version control system is a workaround, but managing multiple versions of binaries is still a challenge. There are also many problems with automating documentation and integrating them into the software development life cycle (SDLC): As the project progresses, these documents are often updated less or completely obsolete. A large number of documents is a negative (using improper means to solve the problem); Each team should find a balance between richness and simplicity.

Document Code "No Separation"

Ideally, the organization should maintain and compose the document through the source of the specification. When discussing a document, it is important to differentiate between objective information and material that has been processed subjectively. Information refers to the source of data or records, and the subjective material is an orderly organization of information produced by the available end products, this information can be read by the reader, may include system requirements documents, design documents, status reports and so on.

Information can be maintained in different sources, such as problem trackers, wikis, and code repositories, and information should be stored in real-world areas where people interact with or execute data. For example, when looking for a document that describes a specific feature, the document should be stored where the relevant functionality resides: next to the code.

If the functionality document does not exist with the code, once the functionality has changed, the engineer needs to update the code, as well as find the code-related documentation to update, the lack of documentation slows down the development process, and engineers need to maintain, manage, and take advantage of the information.

Once all the information has been stored, we can use tools to write documents that you can read and understand to provide information to the reader. Once generated, these materials are no longer changed to make reference information; The process of generating documents is a way to get the latest data. Uploading document material as a Web page is a perfect way to save such documents because the Web page displays always the latest version of the document.

Source

The ability to annotate code has long been part of the high-level practice of programming. Over the past decade, many tools have been developed to improve the documentation experience for a variety of languages. These tools allow developers to archive relevant information and help developers understand the code. Some of the tools mentioned below also allow programmers to add tests in their own documents in a readable manner. When the code is compiled, the tests in the document run automatically, and if the programmer modifies the code without updating the document, the build fails. Rapid feedback from a continuous integration environment can help programmers to ensure they follow the correct documentation policies.

The following tool is a boilerplate library that can generate readable document material directly from source code comments.

• Ruby: RDoc
• Python: Sphinx
• Java: Javadoc
• Ruby, Java,. NET, Flex: Cucumber
• C + +, etc.: Doxygen

Usually the manager may not be able to understand what documents should be required for the engineer. I have received this requirement more than once-writing the function of each line of code in a comment. Managers need to understand that such documents are cumbersome for programmers and can quickly destroy the ability of any programmer to deliver commercially valuable content within a reasonable time.

In DevOps, everything should be automated and find a balance between understandable and simplistic. Keeping the idea of "new objects should be documented", automatically documenting all new objects, is probably a good way to help programmers add comments to your code. However, if there is no document and no effect (such as a build failure), you will find that all objects are in an archive (or incorrectly archived with placeholder information), resulting in rework and the need to reorganize a large pile of documents.

Developers can use the tools listed above to verify that the document is out of date and that the practice works well. If you want to record the project at the end of a life cycle, you should open the tool in an important part. From the beginning of the project, when writing a document, look at each of the smallest available products: documenting the actual situation, not the process of drawing the solution.

System, design, and user documentation

Tools that compose systems, design and user documentation are rich in tools that do not annotate source code. Many times, companies need to develop their own common processes and infrastructure from scratch.

In a recent blog post, Red Hat's senior technical document writer, Mikey Ariel, advocates the use of continuous integration and unit test documentation. In this article, Ariel describes the process as being able to test whether the document adheres to the guidelines (for example, if the company is using backend or back-end) and the syntax (using a tool such as Hemingway or after the deadline with the interface). The idea of using unit test documents ensures that documents are standardized across the company's departments.

In Devopsdays NYC2015 's discussion of the document, Mike Rembestsy from Etsy described their process as "dynamic logging of the network infrastructure in the datacenter". Etsy uses chef to update their infrastructure, while the chef script dynamically updates Nagios, monitors instances and dynamically edits, and publishes network diagrams. By using DevOps in the documentation, Etsy engineers automate the process of updating documents so that they can complete the process as they complete their work. These concepts and practices also reflect the current state of the system while ensuring that the document is accurate.

Document as source control, making information versioned and allowing individuals to be able to maintain or automatically merge smaller data sources with various document materials. The processing of controllable data can reduce the adverse effects of context switching by effectively utilizing the arrangement. When you switch to a DEVOPS document process and workflow, you need to transform your ideas and consider what tools are most necessary for generating documents. The more automated the team is when information is generated, or the more effective it is in promoting information management, the higher the quality and usability of the document. Ultimately, a DEVOPS-based document will allow all stakeholders to access a common, trusted source of information to learn more about the project.

Original link: Three challenges to documentation for DEVOPS Teams

OneAPM is an emerging leader in application performance management, helping operations personnel with fault early warning and positioning, reducing the workload of business system maintenance, and providing traceable performance data to quantify the business value of the operations department. Want to say goodbye to overtime and stay up, welcome to the free registration experience!

DevOps: How do you automate updates to source code comments and system documentation?