[beauty of software engineering - column notes] 16 | how to write project documents?

---

Column information

1. Columnist ： The treasure jade

2. Column publishing platform ： Geek time

---

primary coverage

---

summary

Basically, everyone agrees ：“ Project documentation is important ”, However, we always overestimate the importance of documents in short-term projects , And the importance of documents has been underestimated for a long time .

As a result, the slogan is very loud ： Pay attention to documents 、 Write a good document 、 Write more documents , However, with the progress of the project , There are always more important tasks than document priority , The priority of documents is always postponed intentionally or unintentionally , The document of the project is missing 、 old and worn-out 、 No maintenance .

Why don't programmers like to write documents ？ There are roughly the following reasons ：

1. I don't know how to write
2. Too busy to write or too lazy to write
3. Because it's agile development , So don't write documents ？

One Why write a document ？

1. Help document writers clear their thinking
2. Convenient for future maintenance and handover
3. It is convenient for the team to better cooperate and communicate

---

Two How to write a good document ？

1. Start with imitation
   Imitation is the best way to write documents , Especially now there are many examples that can be referred to online , When you don't know how to write a document , You might as well find a similar document , Try to imitate writing .
2. Start with a small document
   Start writing documents , The content doesn't need much , You can start with a small document . As I mentioned earlier , Take some notes , Don't care about the format , A word or two , Some screenshots , Just good notes .
3. From thick to thin , Iterative updating
   When I was a child, I wrote a composition , The most advice teachers give is to outline , I didn't listen to this suggestion much when I was a child , Later, when I want to write project documents, I feel very practical .
4. Some basic drawing skills
   Some people say ：“ Words are not as good as words , Chart is not as good as table , A picture is worth a thousand words ”. I agree with this view very much , A good diagram can help you explain the problem simply and intuitively .

   • Wireframe
     

   • flow chart
     

   • Sequence diagram
     

   • Screenshots in various formats

     Screenshots are also a very simple and direct way , Put the software UI、 The effect of interaction design 、 Data trend chart 、 Direct screenshots such as data statistics , Add some arrows if necessary 、 written words , It can also explain the problem clearly . Especially product design documents , Frequently used .

---

3、 ... and Some other suggestions about documentation

Sometimes I see some extreme situations , Is too much pursuit of documents , It takes a lot of time to write documents in the project , Many documents are formal , It doesn't make much sense , It may not be used for discussion after writing , No one's going to see it .

Agile Manifesto view ： Documentation is important , But working software is better than detailed documentation . The balance is very important .

Four Other excerpts

• Document first , Will put aside the details of the code , Think about the overall situation .
• The real obstacle is not thinking clearly , There are only some unformed chaotic ideas and concepts in my heart , We must strive to make these vague ideas definite and specific , To write it out .
• To put it another way , If you can't even write a document , Then how can you expect the code to be well written ？
• The more detailed you write, the more useless you will be , Last , You may even conflict with different opinions because you don't want to change the document .
• It's not difficult to draw a good flow chart , The point is to clarify the logical relationship , The trend of each key node under different conditions .

---

summary

No time to write or lazy , It can't be a reason not to write documents . For important project documents , It should be added to the daily development tasks , Write the document , Placed in and designed 、 Development is equally important . In a way , Poor documentation , Code is also hard to write .