preface
Some of the most painful things for programmers are :1. No one else writes documentation. 2. Write a document. 4. Write comments. I talked about this in my last blog post, but when it comes to forcing programmers to do the same, I’m sure 99% of them will choose to write comments instead of documentation. After all, comments are still part of the program, and you don’t have to open that damned Word. Instead of discussing why developers have such resistance to documentation, this article will focus on solving one of the most difficult and often most useless software process documents — the Software Design specification. Of course, this is not only a technical issue but also a management issue. If your immediate boss won’t agree to change the template, then the method of this article is not implementable.
Why are detailed design specifications useless
General software process documentation includes: Requirements specification -> Outline Design -> Detailed Design -> Confirmation test plan -> Confirmation test Description -> Confirmation test Report -> Summary From this sequence, it can be seen that the purpose of processing detailed design itself is to guide specific development efforts, But at this time I believe that in addition to the company or organization in the field of rare is not in accordance with the standard waterfall process development, blindfolded, after all, make things is can’t use in most of the time, when the demand first, then generalized again a detailed set of processes is too heavy, relative to the requirements specification for tracking function demand, guidance of conceptual design for the architecture, Detailed design is a near zero guide to code. Therefore, the business value of detailed design is almost zero, but the corresponding scale of hundreds of pages is too large for an average person to read. Even if you finish it, you’re unlikely to remember the first 100 pages. This is why detailed design is one of the most frustrating documents developers have to deal with.
Improve the premise of detailed design specification
I believe that most traditional companies will have their own detailed design specification template, these templates should be similar. For us to automate the specification, we need the development team to be able to propose changes to the template by adapting it to a style that can be automatically generated.
We detail the improvement practices of the design specification
Train of thought
Through Javadoc and complete a series of tools according to the code automatically generated documentation, and will automatically generate a document as the main part of the detailed design specifications, then the profile design of architecture, data flow, interface core parts such as duplicated as indicating that some of the detailed design is completed in the detailed specifications of writing.
To persuade
The documents of the company cannot be changed just by saying that we want to make our improvement legal and reasonable. Our route is as follows: 1. First of all, we need to analyze the company template and determine the core content. 2. Collect the labor and time cost data of the original template’s detailed design specification. 4. Find relevant stakeholders, direct leaders, QA and other people, show data differences and automatically generated samples, and obtain approval. 5. Experiment with a small project to verify maturity and feasibility. 6. Improve and promote.
How to Automate
1. Javadoc automatically generates related documents. We generally use IntelliJ Idea to generate, as shown in the figure below.
If character set problems occur, add -encoding UTF-8 -charset UTF-8
Generated automatically by Javadoc, we typically see this result in the output directory
Open index.html and you’ll see something like this
Generally, if you only want the electronic version, this step is ok but if you want the paper version, you need to go to the next step.
2. Convert the Javadoc to another printable format
2.1 to CHM
Javadoc-generated HTML can be converted into CHM documents using the JD2CHm tool, which I use in version 0.34
Start the JD2CHm, and the following command line interface appears
After following the prompts to set the Javadoc path and other basic configurations to generate the CHM file, the Javadoc folder will look like this on success
The CHM file is the last one generated. CHM printing is possible, but one problem with this approach is that Javadoc must use a specific template, which is not possible by default.
2.2 HTML to merge
Use the htmlDoc tool to merge the generated HTML files into a single DOC or PDF so that they can be easily saved and printed.
1) Download and install this tool, url:Github.com/michaelrswe…
2) Open the program and add the HTML to be generated
3) Configure the output path
4) Click generate
The disadvantage of this scheme is that it is not well supported in Chinese and may have garbled characters
2.3 Self-developed conversion tools
The conversion process is not that complicated, and generating the desired formats and templates can take some effort to develop automated conversion tools.
conclusion
This article discusses how to design automation in detail. In fact, it is mainly a matter of management awareness. If the boss still blindly asks to write according to the existing template, then follow your heart. There are many problems with this approach, so if you are interested in practicing it, you might as well refer to our route to avoid going too far.