How important is it to document the project? I was chosen by the top 100 up leaders and stood up again

On the importance and methods of writing project documents .

Remember the synthetic watermelon game that was popular all over the network some time ago ？

Actually, when I just heard about this game , It belongs to the village that has just been connected to the Internet , At that time, the game had been spread all over the Internet , And some students stripped the source code , And made it public to GitHub platform .

It happened to be a lunch break , I looked at the source code of this game , It is not difficult to make some simple modifications . There are just some students who are looking for ways to modify on the Internet , I simply made a serious mistake 『 Magic watermelon tutorial 』, And also in GitHub There's a project built on .

It didn't work out , Soon the project came from behind , Top the list ！ Relevant tutorials are also spread on the Internet , There are hundreds of thousands of readers in total ！

It is worth mentioning that , There is one. B Stations Hundred great UP Lord （ fans 300w+） After seeing my project , Take the initiative to contact me if I can cooperate with him , Provide technical support for his video .

As a 1024 Small line up, Have the opportunity to cooperate with the big guys , I'm very excited , That night we contacted by telephone , And the next day I helped him finish the works he needed .

After that day , I have been looking forward to this top 100 up Post this video , Give yourself a small hand .

result , This wait , Until the game is over , I didn't see the video sent out .

What a pigeon ！

But I don't feel angry , After all, there is a circle gap , In the eyes of millions of fans , This is called a matter ？

But I still thank him , Let me understand a programming principle , That's it The importance of good project documentation .

I asked him , Why are there so many tutorials on the Internet about the magic watermelon game , I am not the first to send it , Why did you choose me ？

He said ：“ I've seen a lot of projects , Only the links on your project documentation , It's directly accessible .”

Some project documents

So that's it , yes “ At first sight ” The role of ！

There are too many open source projects and products on the Internet , If you want more users to use your project , That must be in entrance Do enough . A good official website is the facade of the company's products , Empathy , A good project document is also the face of a project . therefore , In the process of developing a project , Keep writing documents .

How to provide a high-quality document for the project ？

How to write a good document

What kind of documents can be considered as high-quality ？ I summed up the following points , You can optimize project documents from these perspectives .

Intuitive and popular

If it is an external project document , It is recommended to use the most popular way at the beginning of the document to let users understand what your project is doing , Instead of using some too professional terms at first . Try to make the document more intuitive , It can give users a glance get To the value of the project is the best .

For example, you can add some small statistical logos at the beginning of the project 、 List some project highlights, pictures, etc , You can also use some visual charts to replace complicated data tables , Help users understand the project more quickly .

Ali Ant Design The project documentation is great , What is the project in one sentence under the headline , Then a large number of small logos are used to supplement the information of the project , And put a few beautiful component screenshots . You can refer to it .

Can experience easy to use

In addition to the intuitive and popular content , If you can directly provide an online experience address of a project in the document , It will add a lot of points to the project ！

After all, there are many students who do not read documents , Prefer hands-on experience .

Additional experience Links

In addition to experience Links , If it is a runnable project , Be sure to provide a way to run the project quickly , For example, how to build an environment 、 How to start the project 、 What parameters are set . You can provide another small Demo, Help users quickly use and learn the project .

For back-end projects , It is better to provide some online data sources , Users do not need to build databases and create data locally .

This point ,Ant Design The documentation is still very good , Two installation methods and simple component usage are provided ：

Installation and usage instructions

If it's an open source project , The way to participate in the project contribution can be supplemented in the document , Attract more friends to contribute to your project .

It is worth mentioning that , Many cloud platforms now support users' one click deployment projects , Add this function to the documentation , Make it easier for users to run your project , You don't need to build your own environment locally .

For example, at that time, I added the one click deployment button of Tencent cloud to the document of the magic transformation big watermelon project , You can go directly to the magic change website ！

Simple and clear

Be sure to sort out the order of the content , Try to simplify as much as possible , And divide the plates , Make the whole document more structured , Clear and organized .

If the project document contains many contents , At the beginning of the document , There should also be a clear directory or menu guide .

A clear directory

Typesetting

Want to improve the readability of the code , Format it . Empathy , Writing documents also pays attention to typesetting and format , Unified typesetting and standard format can improve the readability of documents , Give users a good experience .

There is an open source online 『 Chinese copywriting refers to the north 』, Unified Chinese copywriting 、 The usage of typesetting , Help you write elegant documents , Reduce communication costs among team members , Enhance the temperament of the website .

For example, spaces should be added between Chinese and English 、 Spaces should be added between numbers and units , See the end of the document for the address .

Add spaces between Chinese and English

Answering question

If many users have similar questions about the project , You may wish to add questions in the document （FAQ Frequently asked questions ）, Sort out some common problems for users' reference . It can reduce the cost of team maintenance projects , And let users understand , The person in charge of this project is very considerate , trustworthy ！

I was maintaining the magic watermelon project , There are hundreds of questions every day , If not in this way , Answer the questions one by one , You may not be able to answer all day ！

Organize the list of questions

Easy to search

When there are many documents , If you provide full-text search , It can help readers find their interesting content faster .

Now there are many document site generation tools , Just put the written document in the tool directory , It can automatically generate a website that supports search for you , It can also be published to the server for public access by others ！

Search for

Common document site generation tools are ：Docsify、VuePress、Docusaurus、Dumi etc. .

It's easy to use , You can refer to this article ： actual combat | docsify+ Development of cloud , Create your document website efficiently

Beautiful interface

The content of the document is important , But also make sure the document page is beautiful , Otherwise, it will also affect the user's reading experience and efficiency .

For example, the following two styles of documents , I would prefer the latter interface style .

Classic style ：

Fresh style ：

We usually don't need to design and develop the document interface ourselves , Most platforms offer default styles . You can also use the document site generation tool mentioned above , Choose the theme provided by the tool , Or customize the document interface .

---

Last , Through this matter , I also learned a little ： There is no shortcut to success , It's still up to you ！

Elegantly typesetting documents ：https://www.code-nav.cn/rd/?rid=28ee4e3e607167fa0ecab6b722c458d7