About Open Source Documents: Ten Things That Programmers May Overlook

Most open source documents are extremely disappointing, mainly from the following aspects.

1. lack of a good self-report or introduction.

Readme is the first impression of potential users on your project.

If the project is on GitHub, the readme is automatically displayed on the main page of the project.

If you do not keep your mind in mind, your potential users will never return.

So your project must have a good self-report to attract users' interest in your project.

The readme paper should include at least the following points:

What item is it?

What users are facing;

Which hardware or platform to run on?

Main dependencies;

How to install or deep directional pointer.

These are for users who have never heard of your project before, and may never even consider your project.

Of course, don't think that every user who reads your own account knows what it is. When necessary, you need to make some notes and attach some useful links to help users understand your project.

2. does not provide online documentation.

Although I haven't seen any research in this field, I think 90% of the documents are searched by Google or other browsers on the Internet.

So documents must be online and available.

How did I find out this? Because many users often search the answers from the Internet without looking at the answers to common problems, which often lead to problems in the project.

Therefore, providing online documentation can help users solve problems better.

3. only online documents.

The other side of the problem is that developers only provide online documents.

Some projects do not contain documents that can interact with the project, or the documents that are included are non conforming versions.

For example, the PHP language does not contain any documentation. If you want a document, you must use a separate page to open them.

Worse yet, only core code can be downloaded.

As a result, users may not be able to get useful information for themselves.

Open source projects can't assume that users need online documents when they access the Internet.

Of course, you do not want users to rely too much on your project website.

4. does not contain installation documentation.

This problem is usually the creator of the package, not the developer of the project.

For example, in the Ubuntu Linux operating system, the package selected by the Perl language itself is a separate document.

Users must know the required installation documents and the core language documents when they install them, so that users can solve problems in time when they encounter problems.

5. lack of screenshots

Is there any better way to get the attention of potential users, or to explain the correct use of software?

In the Internet age, a picture may be worth more than a thousand words.

Screenshots enable users to judge whether they are using the right method, and it is easy for him to find his own mistakes.

Therefore, the necessary screenshots are also important for open source documents.

6. lack of examples

For code based projects, simulation screenshots are certainly good, but relevant examples are also essential.

These examples should not be abstract, but should be extracted from the real world.

Take the time to create some project related examples to show users how to solve problems in the process of software application.

If you have hyperlinks, remember to use them in the document.

Do not think that users can understand and understand the document after reading it. There may be some things that users can not understand in the document.

You need to use all your hyperlinks and references to help users solve some problems.

8. forget new users.

When you write a document, you are writing from the developer's own perspective, which is easy for software developers.

For those new users, however, entry documents are needed.

In order for new users to understand your software as early as possible or to be proficient in using software, I think we should use separate pages to write introductory documents for users.

The developer of the project must listen to the user's demand for the whole project.

The most effective way is to let more people try out your project to find out the problem.

Equally important is that in the process of listening to user needs, project developers should take account of the real reasons behind these questions.

If your project has a large enough user base, you can ask users to add comments to the document directly.

The best example I have seen is the PHP language. Each page in its document allows users to authenticate to add comments, or add comments that are not core documents.