1. What is a “document”

Before we look at documentation in agile development, we need to understand what “documentation” is.

As Wikipedia explains it:

It has three basic attributes, namely: knowledge, record and materiality. It has the function of storing knowledge, transmitting and communicating information.

From this definition, we can know that “document” can be understood as any material, tangible or intangible, that can store knowledge, facilitate communication, and transmit information.

Once the concept of “documentation” is clear, we can move on to analyzing documentation in agile development.

Agile Documentation ≠ Not Documenting

Many teams have seen this statement in the Agile Manifesto:

Working software over detailed documentation

This raises the question: since software is more important than documentation, is it okay for agile development not to write documentation?

Let’s assume that it’s possible not to write any documentation during software development, so our daily work scenario might look like this:

  • At the iteration planning meeting, without any written Backlog, the PO dictates the requirements to everyone and starts development directly;
  • There are no design diagrams, no interface documentation, no test cases, no bug records… ;
  • There is no Kanban at the daily standup, everyone dictates what they did yesterday and what they are going to do today, but no one has a clear idea of how many features they need to do in total, how many features they have done, and how many features are left.
  • Requirements change by oral notice, leave or absent from the meeting of the people all by guess;
  • When the PO accepted the story, because there was no visual documentation, the development team did not do what he wanted at all and kept reworking;
  • In the review meeting, because of too many bugs, the new function demonstration frequently overturned, the customer parted in displeasure;
  • At the retrospective meeting, SM found that there was no objective data to review, so everyone chatted about some innocuous topics and broke up.
  • The project is barely online, no user manual, no operation and maintenance documentation, no one can use, no one can maintain;
  • The project.

After reading the above description, do some scenes seem to be familiar? Do you think there are some documents that are still necessary?

It’s not appropriate to write a lot of detailed documentation, but it’s even less appropriate to write no documentation at all!

Documentation not only enables us to communicate more smoothly in the development process, make progress more transparent, change traceability, and record bugs, but also enables us to deliver products easier to maintain, use and modify, which can effectively extend the life of products. It’s no exaggeration to say that documentation is part of the product!

Given that documentation is so important, how much documentation do we need to write in agile development?

Agile documents = documents that create value

I had been struggling with the question of how much documentation agile development should have until I read the Scrum Guide for the NTH time and saw the definition of Scrum:

Scrum is a lightweight framework that helps people, teams, and organizations create value by providing adaptive solutions to complex problems. — Scrum Guide 2020

The latest version of the Scrum Guide has changed the purpose of Scrum from “the highest value product” to “creating value.” As we know from the previous section, documentation is part of agile development, but does the documentation we write in agile development “create value”?

The value we gain from documentation might look something like Figure 1: Ideally, when there is no documentation at all, the more we write (expense), the more we gain (revenue), and the higher the value we gain (profit) (profit = revenue – expense).

But beyond a certain peak in value, when we write more documents (additional investments), there may be no discernable return (additional investments generated income < additional investments), and when we write new documents that are no longer “creating value,” the total value we receive starts to decline. At this point, if we continue to write, we eventually reach a break-even point, where all the documents we deliver are no longer of any value, and the revenue we get from writing them is equal to our expenses.

If a document is already at its peak value (or past its peak value), writing more documents is no longer “creating value.” This is obviously wasteful, and investing in a document once it has achieved its intended goal is simply gilding the lily.

Let’s take the product document as an example: when we are planning a new product, a product vision document is very necessary, because it can clearly indicate the product positioning and future development direction; It would also be useful to compile a user story map based on the product vision document, because it would be helpful for user portrait, function module division, function iteration planning, etc. But if we go further, according to the user story map wrote a detailed product design documents, the document includes a detailed description of all known demand, prototype design of the page, jump logic, release date and the function of the corresponding list, etc., this work is a bit well enough alone, because we now have only one to verify the product vision, We are not sure whether the direction of the product is right, whether the user profile is accurate, whether the requirements can meet the needs of the end customer, etc., so we made such a detailed design document at this time, it is very likely that it is not useful. Even if we force the use of the document, later maintenance costs will be very high, and it will be one of those documents that does not “create value,” resulting in a lower total value of the documents we deliver. If we contact a publisher to edit and print the detailed product design document after we have completed it, the total value (actual benefit – input cost) we have gained from this series of product documents may be almost zero!

Of course, the above diagram is a little idealistic. Writing documents is like exploring a customer’s needs, and we may go through a lot of detours and unnecessary writing before reaching the highest value, but for the sake of illustration, I’ll assume that from the beginning we are writing documents that “create value.”

So how can we make sure that we don’t get sidetracked and that we’re always writing the documents that create value?

How to write an Agile document that creates value

Whether a document can create value for the product can be determined by the following 5W1H:

4.1 Who – Who needs documentation?

When we do product planning, we always do a user portrait to determine which customers our product will serve. A user portrait can help the team shift from “function centric” to “user centric” product design.

The same is true when we write a document. Before we decide to write a document, we should first consider who is the user of the document. Is it a customer, a user, a product person, a developer, or a company leader? Depending on the role, the requirements for documents may vary, so only by identifying the users of the documents can we write documents that meet the needs of our customers and create value.

Here’s a concept to keep in mind: we want to identify the “user” of the document, not the “producer.” What’s the difference between the two? I believe we have all heard the saying: “your mother thinks you are cold”, the author of the document can be likened to the mother, and the user of the document can be likened to the child — the child is cold, only the child can know.

4.2 What – What documentation is required?

When someone comes to you with a request for documentation, it must be because some of his needs are not being met. What kind of documentation do we need to provide to meet the customer’s needs? Here are four principles to keep in mind.

  • First of all, the documentation you provide should capture the pain point of the client, otherwise the client is sure to keep asking for more documentation.
  • Second, ask the customer to be very specific about his requirements for documentation, and must not accept the need to talk in generalities. For example, when a customer says, “I want a product doc,” this is too general, but saying, “I want a product prototype,” is much more specific.
  • Third, you need to determine the format of the document. Is it Word, is it an Axure source, or is it HTML?
  • Finally, tell the client how much work it takes to document, and that any time you spend on the document could have been spent on new features. Make sure the client is aware of this, so that they don’t keep coming back with endless documentation requests.

One recommended approach is to include documentation as a requirement in the Backlog. By treating documentation as a requirement, you can make the effort available to stakeholders (perhaps not just users of the document) to determine whether or not to write and to what extent. Ultimately, investing in documentation is a business decision, not a technical one: Documentation should not be created for processes or regulations, but for your stakeholders.

PS. If your organization does document processes, then open the Scrum Guide, turn to the section “Scrum Master serves the organization in many ways”, and tell the Scrum Master that this is the time to make a difference! Note, however, that the Scrum Guide only states that the Scrum Master is to serve his own organization. If another organization imposes unreasonable demands on your organization, such as if you, as Party B, are working on a project for Party A and Party A forces you to provide a stack of documents at each milestone, This is beyond the control of the Scrum Master.

4.3 Why – Why is it needed?

Why write this document? Documentation must be in order to repay (value) : may be to sell the product (user manual, service guide, etc.), it is possible that in order to reduce the communication cost (product prototype document, interfaces, document, etc.), may also be purely for through a process (such as you, as the party b to party a’s acceptance). Either way, before writing any type of document, it’s important to understand the reasons behind it: how the customer is doing now, why they need the new document, how they expect to use the new document, and what the benefits will be when they have the new document. It is important to note here that no matter what the real needs of customers are, in most cases, we write documents for the purpose of communication, and the main purpose of communication is to understand! Knowing this logic, we may not be so obsessed with perfect, beautiful documents, because documents are just a tool, communication and understanding is the goal!

After reading the first three: “who-what-why”, do you feel that this structure is a little familiar? Yes, the three elements of the user story: As a [role (Who)], I want [function (What)], so that [business value (Why)].

A user story is a valuable feature based on these three elements. Is it possible to write a document based on these three elements alone?

A user story only needs three elements to make a story clear, because there are several implicit conditions for a user story: The solution to the software was brainstormed by the Scrum team and stakeholders at the Sprint Planning meeting (How), the users were using the software through the APP or the web (Where), and everything that happened in the software was happening during use or expected time (such as alarm clock) (When). Documentation in agile development, however, does not have these implicit conditions, so we need to explore the remaining three elements of 5W1H.

4.4 HOW- How to provide?

As we talked in the last video, the purpose of providing documentation is to communicate and understand. What can we do to better achieve this goal? In his book Integrating Knowledge with Action: Realizing Value-Driven Agile and Lean Development, Professor Cong Bin gives a model of communication heat and its effectiveness, as shown in the figure below:

Can be seen from above, “have a problem to clarify link” means of communication (E-mail, phone, white board discussion, etc.) in the aspect of heat and effective communication are significantly higher than the “no clear link” (audio, video, text, etc.) way of communication, so we should give preference to “has the problem clear link” communication, communication is complete, at the same time Produce appropriate documents (e.g. phone recordings, whiteboard photos, etc.) according to customer needs. But is the “no-question-clarifying” approach to communication a bad idea? Not necessarily. In some situations, such as when the distance between individuals (whether physical or time) is large, “no question clarification” communication may be a better choice, which requires extensive text, voice, or video documentation.

4.5 WHEN- When is it available?

A common strategy for requirements management in agile development is to defer decisions. This strategy also applies to the creation of agile documents. We want to delay the creation of all documents as long as possible, as shown in the figure below, and only create them when we actually need to. For example, system profile documentation is best written at the end of a release’s development, because only then do you know what you’re actually building. Also, most operational support documentation is best written towards the end of the project lifecycle. However, this does not mean that all documents should be left to the end. The team should document the material for the final delivery throughout the development process so that you don’t lose key information. It is best to document only bits and pieces of information during development, since there is no need to polish the documentation carefully before final delivery.

By waiting until the project information is stable, you can effectively reduce the costs and risks associated with the documentation: costs are lower because you don’t waste time modifying the information in the documentation that has changed; The risk is reduced because your existing documents are much less likely to become obsolete. If you have written the document ahead of time, but the information contained in the document is still just a plan, you are at risk of modifying or even rewriting the document if the information changes. In other words, you shouldn’t spend a lot of time early in the project documenting planned ideas, such as requirements, design, etc. Instead, it’s better to wait until later in the project, when the system has taken shape and you’ve determined what information will be truly useful to you.

An extreme of this practice is to wait until your system is up and running before writing documentation. The main advantage of this approach is that you are writing known, stable content (the software you have already released). However, there are several obvious drawbacks to this approach:

  • You may have forgotten the reasons behind certain decisions, which can be a serious problem if they are important to you.
  • You may not have the right people to write documentation because they may have moved on to other projects.
  • You may not have the budget to do this.
  • The will to write documentation may no longer exist.

So we should delay agile documentation as long as possible, but don’t put it off until the end of the project, and keep track of useful material throughout the project.

4.6 Where – Where to Start?

Having said all this, many people may still be wondering where to start with agile documentation. Even though I drew this picture in the front:

But this is just an example, and I’m not suggesting that everyone should follow the “agile development” formula. Since each company may have different project types, management practices, and rules and regulations, there is no standard way to practice this. My advice is to start with the status quo! Some people might look at this answer and laugh: we’re writing a bunch of useless documents right now. You want me to start with the status quo?

Let me explain what I mean by “as is” : “as is” isn’t what you’re writing, it’s what you’re using. For example, if you use blueprints, interface documentation, etc., during your daily development and are updated throughout the project, this is a good indication that this information is valuable project information and should be documented around it. For documents that are not kept up to date or that have been largely ignored since they were updated, it is likely that they were written for the sake of the process, and there is no value in continuing to write such documents.

So what it means to start with the status quo is that you can start with the project information that the team has been using, and then iterate over your documentation as you iterate through agile iterations.

Five, the summary

If agile documentation could be summed up in one sentence, it would be this: find the right people at the right time, explore the right requirements, use the right approach, and produce the right documentation!

The little boat brother is quick

Author: adoudou

Disclaimer: The article was forwarded on IDCF public account (devopshub) with the authorization of the author. Quality content to share with the technical partners of the Sifou platform, if the original author has other considerations, please contact Xiaobian to delete, thanks.

Every Thursday in July at 8 PM, “Dong Ge has words” R & D efficiency tools special, public account message “R & D efficiency” can be obtained address

  • “Azure DevOps Toolchain” by Zhou Wenyang (July 8)
  • July 15, Chen Xun, “Effectiveness Improvement Practices in Complex R&D Collaboration Models”
  • July 22, Yang Yang “Infrastructure is code automation test exploration”
  • July 29, Xianbin Hu, “Automated Test, How to” Attack and Defend “?