preface

Some of the most painful things for programmers are :1. No one else writes documentation. 2. I need to write a document. 4. I need to write a comment. It’s a joke, but it also shows developers’ instinctive resistance to documentation. This paper introduces several ideas of agile document practice based on the author’s practice.

It’s a familiar story

Time: Project acceptance ETA two weeks Location: Centralized development office Story then unfolds, suddenly informed to have all deliverables ready next week, as usual in addition to the system itself there are some necessary documents, such as: manual, operation and maintenance manual, etc. The project manager was asked to check the delivery list for insurance, but that’s when the bad news came. The project leader said that in addition to the use and operation manual, a full set of software process documents should be delivered, namely: Requirements Specification, Outline Design, Detailed Design, Validation Test Plan, Validation Test Description, Validation Test Report, I believe those who know should know that this pile of software process documentation is by no means an easy task, leaving us only six days of practice. Nightmare start now, we immediately assembled in addition to handling all the effectives of emergency (3.5) into the document writing, but there are some slightly should be in the mind have several software engineering experience, a little bit big project demand, is set up, detailed set is what the size of the least 80 pages, although there are a lot of templates and die, But the required use-case diagrams, sketched sequence diagrams, and detailed class diagrams are essential, and it is impossible to complete them all in six days of high quality. So in order to delivery, we all know, although there is no official tutorial, all use of a variety of techniques, various kinds of simplified, all kinds of copy and paste, continuous fighting for six days later, finally in the end by the time the documents before sending out, but everyone don’t want to see any more of that document, as if both had a nightmare, forget just wrote something. You can only laugh at the quality of the documentation, not to mention the system compliance issues.

How to end this nightmare

First grab the project owner or manager and figure out two things: 1) why software process documentation is delivered; 2) Why is the time node not notified in advance? Secondly, ignoring the above, how to solve the problem of project management is beyond the scope of this article. We’re going to talk about what we can do to end this nightmare of software process documentation. Before we can wrap it up, let’s be clear: why document?

Why write a process document

The reason is simple, because the company requires it, and then why does the company require it? 1. For the inheritance of the company’s intellectual property, the company certainly does not want you to leave the company and no one else can understand the previous system or project. 2. In order to standardize the software development process and reduce the risk of development, the company certainly does not want to find that the interface or the system can only withstand one person’s operation only one day after it goes online. However, all of these reasons are problematic in practical projects. Here is the actual situation (for ordinary civilian fields) : 1. Most of the documentation does not reflect the design and development of the system, and I would be grateful if you could keep the documentation in sync after 186 upgrades. 2. Most of the documents reflecting the system design and development are supplemented after the completion of the project. Once we understand the difficulties and the purpose of the documentation, we can adapt the pattern of the process documentation to meet the company’s purpose. I’m sure most companies don’t care about the style on the pile of documents.

Documentation in Agile

In fact, I believe that many people who do not know agile will think that Agile = no documentation and no design, which is actually wrong. Agile thinking emphasizes doing valuable things. If the document is the final deliverable, then the Agile team will make complete and high-quality preparation of all the documents to deliver. But the truth is that users care more about the system they can use than they do about more than 200 pages of cold documentation. As a result, agile teams focus more on system development and user feedback, and less on documentation. We have been moving to Agile for more than 3 years and the most important documents of the past few years are: 1. System Prototype Interface 2. List of user stories 3. Architecture design 4. Data flow at the top level of the system 5. Our goal is to create value for our users, and if the value of high-quality documentation is high, then it must be delivered.

Our practice

With the right approach and the right tools we can document the process more efficiently and easily. Here’s a list of traditional document implementations. 1. Requirement Specification — dynamic prototype interface (if archived, it can be printed) + User story map (photographed and printed) 2. Outline Design — Interface document (RAP or Swagger management and export) + Data flow diagram + overall architecture diagram (printed and hung in the development environment) 3. Detailed Design — HTML (generated automatically through Javadoc, 4. Test Report – HTML (junit or Testng generated report) + HTML (Fitnesse for acceptance testing) Here are just some of the experiences that we validated, and you can also make suggestions. By the way, document generation code is a bit of a mystery…