About open-source documents: ten things that programmers may ignore

About open-source documents: ten things that programmers may ignore

Most open-source developers like to think about the quality of the software they build, but the quality of their documents is often forgotten. No one is talking about how good a project's documentation is, but it has a direct impact on the success of a project. Without a good document, you may not use your project or enjoy it.

However, most open-source project documents are extremely disappointing, mainly from the following aspects.

1. Lack of a good self-report or introduction

Self-Report is the first impression of potential users on your project. If the project is on GitHub, the self-report is automatically displayed on the home page of the project. If you are confused, you will make a mistake. These potential users may never come back again. Therefore, your project must have a good self-report to attract users to be interested in your project.

The readme file should include at least the following instructions:

• What is a project?
• Target Users
• What hardware or platform is running on?
• Main dependency
• How to install or drill down the direction pointer

These are written to users who have never heard of your project and may never even consider your project. Of course, do not think that every user who reads your self-report knows what it is. If necessary, make some annotations and attach some useful links to help the user understand your project.

2. Online documents are not provided

Although I haven't seen any research on this, I think 90% of the documents are searched through Google or other browsers on the Internet. Therefore, documents must be online and available. How did I find this? Because many users often search for answers to frequently asked questions from the Internet without looking at the answers to frequently asked questions, which often causes problems in projects. Therefore, online documents can help users solve problems better.

3. Only online documents are supported.

On the other hand, developers only provide online documents. Some projects do not contain documents that can be interacted with the project, or the documents contained are non-conforming versions. For example, PHP language does not include any documents. If you want documents, you must open them on a separate page. But worse, only the core code can be downloaded. In this way, users may not be able to obtain useful information for themselves.

Open-source projects cannot take it for granted that users need online documents when accessing the Internet. Of course, you do not want users to rely too much on your project website.

4. Installation documents not included

This problem is usually caused by the package creator rather than the project developer. For example, in Ubuntu Linux, the package selected by the Perl language is a separate document. The user must know the installation documents and core language documents required during installation, so that the user can solve problems in time.

5. Lack

Is there a better way to get the attention of potential users or describe the correct use of the software? It is wise to do so. In the Internet age, a picture may be better than a thousand words. It allows the user to determine whether the method he or she uses is correct, and easily allows him or her to find his or her own error. Therefore, it is essential for open-source documents.

6. Lack of instances

For code-based projects, the simulation is indeed very good, but related instances are also essential. These instances should not be abstract, but extracted from the real world. It takes time to create project-related instances to show users how to solve problems arising during software use.

7. inadequate links and references

If there are hyperlinks, remember to use them in the document. Do not think that users can understand and understand the document after reading it. Some things that users cannot understand may exist in the document. At this time, you need to use all your hyperlinks and references to help users solve some problems.

8. Forget new users

When writing a document, you write it from the developer's perspective, which is very easy for software developers. However, for new users, an entry-level document is required. In order to enable new users to understand your software as soon as possible or be familiar with the software usage methods, I think you should use a separate page to write entry-level documents for users.

9. Do not listen to user needs

Project developers must listen to users' requirements for the entire project. The most effective way is to let more people try your project to find out the problem. It is equally important that, in the process of listening to user needs, project developers should consider the real reasons behind these issues raised by users.

10. user input is not accepted

If your project has a large enough user group, you can allow users to directly add comments to the document. The best example I have ever seen is the PHP language. Each page in the document allows authenticated users to add comments or add comments that are not part of the core document.

From: http://www.evget.com/article/2014/11/5/21786.html