·Individuals and interactions are higher than the processes and tools

·Working software outperforms comprehensive documentation

·Customer collaboration is higher than the contract negotiation

·Response to changes rather than follow the plan

It seems to foresee that this simplicity could cause misunderstanding, and the Agile Declaration clarified: " That is, while things on the right are valuable, but we value things on the left more.” 

Even so, the industry's misunderstanding and confusion about agile development methods still exist. "Over" was replaced by "Instead of", originally <<Agile Declaration>> intended to "better focus more attention on software rather than spend time on overly detailed up-stage documentation" and now seems to be " let's abandon the document altogether and hope we remember everything we have discussed.”

Source: azalead.com

Agile myth: "Document does not matter"

Teams using the traditional IT project approach define and document requirements in the early stages of the project. These requirements will then be submitted to the developer, who then carry out it immediately.

While the Agile development approach was created as an alternative to this document-driven development process, it is not intended to eliminate internal documentation entirely. Since software development is dynamic in nature, agile development focuses more on working software than comprehensive documentation.

Nothing in the Agile Development method prevents the team from creating the required documentation for the project. In fact, in some cases, documentation is absolutely needed: adding user stories to the to-do lists, creating flowcharts, making meeting notes, etc. Agile is just —— Agile just suggests that the team should be smarter in this regard.

The document should be "just right." Too complicated or over comprehensive documentation will waste time, and developers rarely believe in detailed documentation as it is usually out of sync with the actual code. On the other hand, experience shows that a little documentation is always the source of problems troubling communication, learning, and knowledge sharing. 

Reasons for investing in Agile documents

The creation and maintenance of agile documents is an "inevitable disaster" for some people, but for others, it’s a pleasant task. Same thing, there will be some reasonable reasons to believe that it is worth spending time in agile documents:

·Project stakeholders need it. Fundamentally, creating documents is a business decision, where teams put stakeholders' resources into document development, so they should have right to speak in whether to spend their money in this way.

·Support for communication with external teams. It is impossible for development teams to always stay at the same position and neither of keep stakeholders on standby. Shared documents are often part of a solution combined with occasional face-to-face discussions, conference calls, email, and collaboration tools.Nor is it possible to always keep the project stakeholders on call. Shared documents, often combined with occasional face-to-face discussions, teleconference, email, and collaboration tools, are part of the solution.

·Support for organizational memory. One of the principles of agile modeling is that "reaching the next step is your secondary goal," which means being balanced with the principle that "working software is your primary goal". This means when the team develop the software, they also needs to develop the supported documentation, which needed to use, operate, support, and maintain the software.

·Think about things clearly. The act of writing ideas on paper can help you consolidate them and find problems in your way of thinking. Things that seem clear and direct in your mind tend to prove to be much complicated, so you can write it down at first.

While all of the above reasons may be justifications for documentation, we always ask ourselves the question: What is the minimum deliverable volume that we currently need? 

How to write documents in Agile

Principles for Agile Documents

Documentation in Agile is "variable" and requires collaborative maintenance of the entire team. To make the most of the time we invest in the documentation, we can follow some simple principles:

·Make sure that it is always "just right." Keep in mind that any documents created must be maintained later. It is easier to understand and update if the document is simple, uncomplicated, and less detailed.

·Write with "just in time". Waiting patiently before recording, it is the best way to avoid accumulating erroneous and outdated information. Rate documents when needed, not before needed.

·Place the document in an easily accessible place. Documents are only useful if accessible, storing product documents where they can be easily found by team members.

·Cooperate with the team. Within an agile team, maintaining documentation is a collaborative process that each team member should be encouraged to contribute to.

When to record

The iterate delivery of working software in Agile has effectively replaced many (although not all) comprehensive upfront demanded documentation. The idea is to keep the document as simple as possible, especially in the early stages of the project. So when is it worth spending time in the document?

A common Agile practice is to postpone the creation of all deliverable documents as much as possible, creating documents before they actually need to be delivered. For example, the system overview and supported documentation are best written at the end of the Software Development life cycle (SDLC). In essence, this method is to capture the information until it is finalized.

Source: azalead.com

Another strategy for Agile documentation is continuous documentation. Write deliverable documents throughout the project and renew the documents while updating code. This approach fits with the Agile approach, which means consistently generating potentially deliverable solutions.

However, as demand may evolve in the course of the project, considerable time will be needed to keep deliverable documents up to date. From an Agile point of view, this is another "heavy burden".

In practice, Agile usually postpone writing documents until they have time to do so, in fact, even if they initially decide to continue updating the document, they will gradually turn to the later practice of the document.

Source: azalead.com

What to record

Examples of documents that may be used in Agile documents include case studies, charts, tables, and site maps. Here are some documents considered creating in the course of the project:

·Product Vision: It is a description of the core of the product and a summary of current cost estimates, expected earnings, risks, staffing estimates, and planned milestones. The requirements of Agile document are: keep short and straight.

·Project Overview: This is a summary of the key information related to the project, such as the primary users’ contact information, technology, and tools used to build the system. Use it as a starting point for new team members and maintain it throughout development.

·Design Decision: This is an overview of the design and architecture-related critical decisions the team makes throughout the project.

·Operation Documentation: This is usually a description of the dependencies involved in the system, a reference to the backup process, troubleshooting guidelines, etc. Operation departments may have a standard format for such documents.

·Requirements documentation: It is an overview of system features, including user cases, user stories, or basic user interface prototypes. It designed to capture requirements as executable specifications.

·Support documentation: This includes training materials, troubleshooting guidelines specifically for the support team. Like the operation departments, the support team may have standard templates or examples to use.

·System Documentation: Provides an overview of the system, including technical systems, business architectures, and other advanced requirements. System documentation helps to ensure the retention of critical information.

·User documentation: It includes the user reference manual and the support guide. The requirement of this documentation is to keep it simple and easy to understand. Solution documentation design will be flawed if extensive training needs to be used to teach the user how to use the product.

Conclusion

"We accept documents, but do not accept hundreds of tomes that are never maintained and rarely used.”

— Jim Highsmith

Agile development methods are by no means anti-documented. It just reminds the team not to write extra documentation and to keep it as simple as possible while it is necessary. By finalizing a certain format and detail, allowing to change and deliver documents of sufficient value to keep the team moving in the right direction.

--

Author bio

Chen Qi, a senior agile test consultant, as a team member of ZenTao, a well-known domestic project management software, is mainly responsible for the open-source automated test management framework- the development of ZTF. With more than ten years of practical experience in the agile process, he is now committed to the practice and research in test automation and DevOps.