How to maintain documents in agile development

Transferred from: http://www.infoq.com/cn/news/2009/02/agile-documents/

There are many types of documents in a software project, including requirements documentation, design documentation, API documentation, bug reports, progress reports, handover documents, acceptance documents, and so on.

In traditional software project development, each team member spends a lot of time and effort to maintain documents and fill in various forms and reports. The second Agile Manifesto is "working software is better than detailed documentation", which many people take for granted that agile development does not attach importance to documentation. What's more, someone who avoids writing a document and excuses for Agile development does not need documentation to become so-called PAP (Pretty adventuresome programming). In fact, these people ignore the agile development has many practices (such as sitting together, on-site customers, test-driven development, customer testing, pairing programming, information-based work, etc.), agile with these practices to exchange information, play a role in the traditional software development of the document. This article explains why many documents are not needed in agile development by analyzing the types and roles of documents in project development.

First, you need to clarify the purpose of the document, which is used to communicate information. The key is whether the information sharing in the team is timely and accurate, which is not necessarily related to the number of documents. As James Shore points out in the "Document Puzzle" (http://jamesshore.com/Blog/The-Documentation-Myth.html), many people accuse agile development of a lack of documentation. In fact, they ignore the essence of the problem, "rich document is not necessarily good, can get the answer in time is good" (Myth:document is good; Reality:answer is good).

Expertise or information is divided into two main categories: can be collated, documented knowledge, generally only accounted for 30% of all knowledge. 70% of the implicit (Tacit) knowledge that exists in the human brain can only be shared through communication between people, word of mouth. Therefore, the promotion of communication between the team and the team is more effective in disseminating information.

There are usually three types of software project documents: Project documents, which are used for information exchange within the project team, such as requirements documents, design documents, progress reports, etc. Product documentation, often of business value, is required by the customer, such as user manuals or API documentation. Handing over documents, deliverables that are transferred between project handover or different phases of the project.

Product documentation is required by the customer, is part of the product, has business value, absolutely cannot be omitted. You should schedule a document task for it in the iteration.

From an agile perspective, many of the other two types of documents can be simplified or omitted.

In the agile development process, the entire team sits together, handing over documents becomes superfluous. Lean thought that handing over (transportation) was a big waste (see Mary Poppendieck, principles of Lean thinking http://www.poppendieck.com/papers/ Leanthinking.pdf), it takes a lot of effort to hand over the document first, and then much of the information is lost during the handover, and there is always some new information added at each stage. All team members (PO, Dev, QA, Doc) sit together and use the whiteboard for face-to-head communication, saving time and effort and being effective. (See Alistair Cockburn, communication  http://www.agilemodeling.com/essays/communication.htm in Agile projects) Product owner sits with the team, Always answer the questions of team members ' needs, is a live document. In a sprint planning meeting, the team chooses the user story to be completed (a small card on the sprint backlog) to form the sprint backlog, which is actually an iteration plan. In a release plan meeting, Product owner determines what is published and forms a story wall, which is a longer-term development plan. Dev and QA work together to design customer tests (typically with fit tools). Important user logic is designed as a customer test. This requirement (customer test) is operational and therefore never obsolete (if there is a problem, the continuous integration system will immediately alert you). This is much more effective than the traditional requirement document. Traditional documents have too many problems, such as very few people to test the correctness of the document, very few people to update the document in a timely manner, few people to check the requirements coverage (there is no way to check, many tools take for granted some from the requirements to the implementation of the tracking, but this is not a kind of metaphysics. ）。 The specific logic in development can be designed as a use case for TDD (or BDD, behavior-driven development http://behaviour-driven.org/), which acts as a detailed requirement document or design document. Developers use pair programming (many benefits, see "I like pairing programming"  http://www.nomachetejuggling.com/2009/02/21/i-love-pair-programming/, and " Pair programming: How important it is. "http://xprogramming.com/blog/2009/01/28/pair-programming-how-important-is-it/). Health ofThe architecture of the system should be dynamic and evolving. So if you fix it in a document, you'll get an outdated or incomplete problem. When designing specific modules, the team uses the whiteboard to design the general framework and determine the direction, which is then implemented by pairing programming. By pairing programming, you can share and evolve system architecture information in a team. The team reports progress, updates status, and issues encountered in the daily stand-up meeting, and all information is immediately reflected on the Sprint Backlog,burdown chart and on various charts, becoming part of the information-based work that the team can adjust accordingly. After each iteration, a self-improvement team can also design a variety of hand-drawn forms (Ron Jeffries gives some examples on the personal website, http://www.xprogramming.com/xpmag/ bigvisiblecharts.htm) to monitor the team's own problems. As a result, the traditional documentation of censorship and statistics becomes superfluous. The high-level requirements of agility are reflected in the vision document, which generally has only one page, which is unlikely to change and is easy to maintain. A high-level system architecture diagram is still necessary. This high-level system architecture changes the likelihood is also very small, the maintenance cost is also relatively low. The code is the document. Many agile gurus focus on architectural clarity and the readability of the code (such as Robert Martin's S.o.l.i.d principles, Robert Martin's Clean Code, and Kent Beck's "Implementation Model"). In a sense, the code we write is actually a design book that instructs the computer to do its job. Design books are meant to make it easy for others to read (or why not use binary to write programs and put them on the machine).

As James Shore concludes, there are many ways to get information.

The best means, the code is clear, the unit test complete, naming norms, so there is no need to ask;

Second, just ask the next person, or make a phone call, you can get the answer immediately, which is why agile encourages "sit together" and "Live Customer" R;

Again, Google to find the answer, which is also good;

......

Once, you can find the answer by reading a document. But to find the answer, the more documents you need to read, the worse the effect ...