13 Open-source project documents should be avoided

Most open-source project developers only focus on the quality of software and often forget to write high-quality documents. However, the quality of the document plays a vital role in the success of a project. it can help users quickly understand the project or provide some help during use. However, there are... "> <LINKhref =" http://www.php100.com//statics/style/headflo

Most open-source project developers only focus on the quality of software and often forget to write high-quality documents. However, the quality of the document plays a vital role in the success of a project. it can help users quickly understand the project or provide some help during use.

However, there are many open-source project documents disappointing, mainly manifested in the following aspects.

1. lack of a good README or introduction

README allows potential users to have a preliminary and quick understanding of your project. if the project is on GitHub, the README file is automatically displayed on the home page of the project. If you want to attract users and keep them exploring your projects, a good introduction is essential. If the introduction is poor, these users may not be back.

The README file should include at least:

• Project purpose
• Target audience
• Running platform or hardware
• Important dependencies
• How to install, or something deeper

Project README must be written for those who have never heard of your project. For example, there is a Levenshtein distance computing module in the project. do not assume that everyone who is reading README knows what Levenshtein is. You should describe it and add links to relevant details to facilitate further exploration.

When introducing a new thing, do not introduce other new things. for example, "numberdoc is similar to BongoCalc, but it is better." People may not know BongoCalc at all.

2. no documents are provided online

Project documents must be available in Google, so make sure your documents are available online.

I have released an open-source project. What makes me annoyed is that users often send me emails to ask some questions that I have answered in the FAQ. later I discovered that, I did not place the FAQ on my website. This is a relatively easy mistake, because the author does not consider the problem from the user's perspective.

3. only online documents are provided.

You cannot help but provide online documents. Some project final versions do not include documents, or contain incomplete documents in the project development phase, and the final documents are put online, which is for users without a network, this has caused some troubles.

For example, the Solr project has a very comprehensive Wiki (document), but it provides a 2200 page automatically generated API Javadocs for download, the only document for the end user is a single-page tutorial.

The PHP language pack does not contain any documents. if you want documents, you must go to a separate page. Unfortunately, only core documents are downloaded and there are no comments that are helpful to users.

Open-source projects cannot be assumed that users can access the Internet. You cannot make users rely too much on the project website. In the past few months, I have found that Solr wiki is down at least twice, and I was in urgent need of a tricky configuration problem.

In this aspect, Perl and its CPAN module library are better. Each module document is provided on search.cpan.org and metacpan.org in a readable hyperlink format. For offline environments, each module document is embedded in the code itself. when a user installs a module, a local document is automatically created as the instruction manual. You can also use the perldoc Module: Name command in Shell to obtain the document. You can use it online or offline.

4. the document is not automatically installed

This is usually the error of the installer creator. For example, in Ubuntu Linux, a Perl document is an independent and optional package, which may be omitted during installation. Although it saves several MB of disk space, users cannot find it as needed.

5. missing

Sometimes, a picture is better than a thousand words.

A screen can help you intuitively compare the operation results, check whether the tasks are completed correctly, or easily find out where the problem occurs.

Nowadays, it is also common to use videos to introduce projects. videos can display steps of a complex process. For example, the Plone project has a dedicated website to provide video tutorials. However, videos cannot replace screens, because users cannot quickly find some content through videos (which requires 1.1 points), and videos cannot be indexed by Google image search.

6. lack of practical examples

It is good for code-based projects, but it is more practical to give an instance. These examples should not be abstract, but come from the real world. Developers should take the time to create an example to show users how the project solves the problem.

As Rich Bowen of the Apache project said, "a correct, fully functional, tested, and annotated example is better than a one-page tedious introduction ."

7. missing links and references

Do not think that the content you want to explain is part of the document, or the user has read it before, or knows where they are, there is no need to use hyperlinks. For example, some code in your project is used to operate frobbitz objects. you need to explain the frobbitz objects or link them to related pages.

8. ignore new users

When writing a document, do not think that some users already know something and do not go into details. You should consider new users and use a separate page and the best example to let new users quickly understand your project.

9. do not listen to user feedback
You should actively listen to the suggestions and requirements of users who use your software, for example, "If you have an introduction or link to database driver installation, this will help me install this program ".

Create a FAQ based on user feedback. Pay attention to other websites or forums, such as StackOverflow, and create a Google Alert to learn about the discussions on your projects on the Internet.

10. user input is not accepted

If your project has a large enough user group, you can consider allowing users to directly write comments to the document. The best example I have ever seen is PHP. every page of document allows authenticated users to comment on the page or add non-core document examples.

These contents need to be maintained, because there will be outdated annotations over time, and these need to be eliminated.

11. the project can be used only after installation. 

Each software project requires a function list and page. if it is a pure code project, such as a library, there should also be an example page.

12. dependent on automatic document generation

Most of the time, software developers use automated document generation systems to replace their work. They forgot to write other parts manually.

The worst case is that changelog does not have any content except some submitted information. Changelog should list new features, bug fixes, and potential compatibility issues. its target audience is end users. The submitted logs are for developers to view.

13. treat small white users with an arrogant attitude

Do not report "RTFM (Read the Freaking Manual, Read the TMD Manual)" to user problems, which may scare a group of potential users.

If the user's problem can be found in the document, but they did not, do not think it is stupid. It may be because your documents are poorly written, hard to read, or incomplete. You need to patiently improve the "getting started" section to explain what the purpose of the software is, or to indicate to the user where the relevant information can be found.


13 Things People Hate about Your Open Source Docs