Do you write a document? Why should you write a document?

Summary

This article mainly describes the importance of the document for a team's development and its significance in improving efficiency and saving time, it also points out how to write and maintain documents in practice development.

Contents

• Summary
• Introduction
• Why write a document?
• Why do most programmers prefer to write documents?
• Why should we write documents?
• How to Write documents
• Conclusion
• Postscript
• References
• RST source code in this article

Introduction

Consider the following questions first:

1. If you are a newbie to a project team, can you see the related documents of your project? Do you want to see it?
2. If you are an architect or a Senior Programmer, Are you often asked by other colleagues about the architecture? Will you answer the same question over a thousand times?
3. How did you write a document? What documents do you provide? How do you manage documents? How do you ensure that documents and code are synchronized?

If you shake your head when thinking about these issues, it is time for you to write documents for your project or ask team members to establish a document system.

Why write a document?

In fact, the reason is very simple. 1) provide a quick start path for beginners 2) Save a lot of valuable time for yourself 3) win more development time for the project 4) provides a project perspective at a high-level (the code is low-level)

If you are patiently and meticulously explaining how to configure the development environment, the entire development framework, or the composition of the entire team for new members of your team, while admiring your patience, I blame you for your inefficiency. (If I am your leader, I don't want you to spend your time teaching new ideas ).

Why do most programmers prefer to write documents?

Compared with coding and development, the corresponding and generated results will bring you a sense of joy and achievement. Writing a document is boring, but it is just a pile of text, it does not move the project forward, nor does it allow you to remove a todo entry from your own module. this is the question of accomplishment.

What's even more annoying is that your code may be constantly restructured, the framework will be constantly modified, and you will naturally update the comments of the code, and you are too lazy to change the documentation, however, they do not reflect the latest code and framework. They are not only unable to help those who read the document, but also make them "go astray", so you have to update the document reluctantly, in the update, you swear to stop writing these documents. this is the maintenance problem.

Or, to put it bluntly, some programmers are reluctant to write the framework or their own experience into documents (I think this is a minority), because he calculates the hardships he has traveled all the way, later, I thought that this non-document-free code-based process was necessary, and I was so confident that I was able to watch the newbie move forward in the thorns. this is a problem of mentality.

Some Programmers think that they are incapable of writing documents, or that they are not at the level of writing documents. Although they will use the current framework, they are confused about its implementation, and related data interaction and design concepts. he was afraid that the documents he wrote would mislead others, and he was afraid of "coming out of the ocean ". this is an issue of thinking.

And so on. There may be other reasons.

Why should we write documents?

Therefore, it is wrong for me to analyze your documents one by one.

1. A sense of accomplishment: I personally think that the less code you write in a day, the more time you think about, and the more time you write a document, the better your ability, and the big picture in your heart, instead of simply implementing a feature, a feature. the idea is to write better code, and to write documents to better support subsequent code maintenance and care for new users. when your new colleague sees your document, he will be grateful to you. when your boss sees your clear documents, he will consider promoting you. you must also know that the project manager no longer focuses on code, but on documents (Requirement documents, development documents, etc ). therefore, when writing documents, you must be confident and feel a higher sense of accomplishment.
2. Maintenance: document updates must lag behind code updates. To ensure that documents are correct and accurate, you must have a mechanism to ensure that documents are up-to-date. it has been proved that it is appropriate and efficient to use a system such as wiki to maintain documents, because:
   • One feature of Wiki itself isConstantly changing and updatedSo other colleagues will know that these documents will be constantly updated and I will keep tracking
   • Wiki's built-in version control makes it easy to write and share documents.
   • The collaboration mechanism of Wiki itself makes maintenance more convenient (think about Wikipedia, which article is completed by one person at a time)
3. Mentality: sharing is not just a kind of behavior but also a kind of spirit. When you see this blog, I am sharing it. When you write a message after reading it, you are also sharing it. sharing is the cornerstone of the Internet and the embodiment of maximizing the value of knowledge. if you want to share your past hardships with others, I think I will not be optimistic about your future, and I do not want to be friends with you, these actions cannot benefit you much. conservative and closed thinking will affect the level you can achieve. we are working hard. Every day we study hard, we hope that our children will not be so hard. Why can't we extend "children" to everyone? Share your knowledge with your friends and share it with others. You will also be recognized and supported by others. Of course, they will also give back their experiences and experiences. You are not alone in sharing your knowledge.
4. Idea: first of all, programmers who think they are incapable of writing or writing documents horizontally have a wrong idea, becauseNo one can ensure that all he writes are correct.Even Donald knuth. your colleagues read what you wrote. While benefiting, if you discover problems, they will not blame you, but will communicate with you with gratitude and discussion, eventually, you may have corrected your mistakes and grown up. if you do not share it, you may not understand it all your life. "Oh, it should have been like this ". write your own ideas, write your own understanding, share with others, help others, and improve yourself.

Of course, everyone will say that the key action lies in yourself.

The key issue is how to write documents, what should be written, and what should not be written.

How to Write documents

Before writing a document, you have to think about what to write. I will summarize the content as follows:

1. Key processing logic in the project

   • Framework Used
   • The entire processing process (for example, after clicking a link or button, the subsequent complete processing process and interaction logic)

2. Normative content (such as coding, document, and comment)

3. Knowledge content (such as how a tool is used and how a plug-in improves development efficiency)

4. Experience (such as some best practices, how to write SQL, and how to ensure code reusability)

5. Tutorial content (for example, how to get a beginner to use the current framework to write a function, and how to get started)

6. FAQ similar content (when you have been asked the same question by a colleague or customer more than three times, you should write a document to avoid being occupied by this valuable programmer time again)

Of course, all the above mentioned are development-related documents, which may be written by every programmer. there are also several types of documents, such as requirement documents, development documents, test documents, and user documents, which may also involve programmers.

In addition, the other category is code APIs. The best way to handle such documents is automation, such as a series of tools such as doxygen and epydoc. with this tool, you do not need to re-write the API documentation. You only need to generate the documentation automatically. If the code and comments are updated later, you only need to generate the document again.

We have solved what to write. Let's take a look at how to work with documents and how to maintain documents.

Here is a reference: How to make multiple ents evolve?

I have experienced teams that do not write or write documents, but often become outdated and maintain well. Based on my personal experience, my suggestions are as follows:

Use a well-organized Wiki as a document management system, and update documents in the project in a timely manner to ensure accuracy and correctness..

Of course, if you don't want to maintain a document system, you 'd rather not document it, becauseThe wrong document is not as good as the document.

So where is the document suitable?

My personal suggestion is to integrate it with the code into the version control system. For example, do you want to use the source code management tool? The Bitbucket recommended in, which is integrated with wiki. This makes maintenance and updates easier.

Conclusion

Document is a reflection of the company's strength and the quality and ability of managers. It is a great fortune for developers. therefore, maintaining a well-organized document will not only benefit you a lot in development, but also greatly improve the members' acceptance of the team and their loyalty to the company.

If your team does not have any documents, write them now.

Postscript

I still remember that when I joined a team, I only got a SVN account, a task description, and then deadline. moreover, we are remote and have no chance to communicate with each other. in the next few days, I read the code and dreamed that a document could fall down from the sky. after a week of hard work, I figured out the entire framework and ideas, and wrote a document. I don't want my colleagues to experience the same pain and helplessness.

References

1. How to make movie ents evolve?
2. Donald knuth