Suggestions for writing design documents

1. Prevent writing into an intelligent puzzle
Many documents are written as toys similar to smart puzzles, and many different definitions and contents are scattered in different places of the documents.
. The reader will not predict whether there will be further instructions elsewhere in the document. To read such a document
We need to keep everything in our minds. The puzzle is to put together small pieces scattered everywhere, but the human brain is hard to do this.
A little.
Remember that any large document has different levels of intellectual puzzles, but our task is to reduce intellectual puzzles.
The number of blocks. Do not let readers make inferences about the information block they see in one place, but find this block in another place.
Understanding is wrong, which is very dangerous.
The principle of organizing documents is to prevent intellectual puzzles in most cases. If necessary
The definition and description of a name are all found and placed in a fixed and unique position. If necessary, you can
To create a glossary. If you cannot concentrate the relevant information in one chapter, you need to add a reference page so that the reader can
Not confused.
The preparation of this course handout is a document process. Apart from clearly defining the problem domain, the entire course
Cheng's thinking is based on problems, research countermeasures, and solutions, rather than on what someone says
What is the standard (What's more, the standard is changing ). In terms of writing methods, the reader is the center, and strives to be easy to understand, internal
Coherent and clear. In the content organization, we try to reduce unnecessary jigsaw puzzles and reduce unnecessary pre-and post-view information.
Similar concepts and terms, as long as each chapter tries to form its own logical system, make it easier to read and clear.
Note these features during document writing.
2. Prevent writing duck files
Some documents are written. Why are you reluctant to read them? Why does it seem clear that I have already described
Does the reader feel obscure and difficult to read? Let's take a look at the following description: "ticket booking data verification letter
The ticket booking data should be verified ". What does this sentence mean? How to test
It? This makes it easy for people to think of a duck as a kind of speech. It is monotonous, gentle, mediocre, and compliant with official standards.
It seems that there are many descriptions, but nothing is actually described.
Read out the sentences you have written. If you find that you have written a lot of unquestionable sentences, you just want to cater to them.
To meet the standard requirements, you must reframe the issue so that the document can be written in a spirit that readers can start reading.
3. Do not document for the purpose of documentation
Software Quality Assurance is a concern of every development organization. To maintain consistent software quality, we need a set of unique
Therefore, process definition and document standards have become a concern of many organizations. However
The usage of the generated document is irrelevant to the correct implementation of the function. Because the document record must be consistent with the document standard, the result is used.
It will be very tedious and messy.
This document writing philosophy is only for the purpose of checking, rather than promoting efficiency and better development.
It is a document writing method. There is only one purpose for writing such a document, that is to prove that we are
I am not responsible for making any mistakes when doing the same thing as the official team. If the project can be completed, no
It is my consideration.
Many documents have not been read by anyone. The reason is that they cannot be understood and are not suitable for the habits of relevant personnel.
There is no way to associate documents with your own development work. Of course, many reviews only focus on the document format, not the document
File validity, only focus on the number of words in the document rather than the ideology of the content. Such things cannot be solved by development units alone,
If such a review exists, one suggestion is to develop two sets of documents, one for review and the other for review.
Within the development team. This seems to be a lot of time, but the time spent is worth it. It is better than formatting the documents to be reviewed.
Files are much more efficient for actual development. Try it and you will find the meaning of this suggestion.
4. Coordination between graphs and texts
When talking about design documents, it is inevitable to use graphical expressions. However, it takes some effort to coordinate images and documents. Comparison of charts
Description, and text is more suitable for expressing details. The two are irreplaceable. As a design, if there is no graph,
Related personnel may not be able to obtain a general concept about the problem domain. But it is impossible to define it without a detailed text expression.
Development also cannot direct development to what we need. An image does not need to be comprehensive, but only needs to express its focus.
The text details should be sufficient to define the key points of development, but developers should also be given the appropriate play
Space.
Some organizations are keen to directly generate code for class diagrams. This is a misunderstanding and a wrong place for the diagrams. Code is nothing
Fine and closely related to the individual characteristics of the coders. There is no need to draw a picture so detailed or not.
To draw a picture, you must be smart, describe the causes of each structure policy, and describe the negative effects of the adopted policy,
Designing just according to a certain pattern is a beginner's business. A senior designer's way of thinking is to break through everything.
The purpose is everything.