Open Source Project Document 13 should avoid

Most open source project developers focus on the quality of the software and often forget to write high quality documents. However, the quality of the document is critical to the success of a project, which can help users quickly understand the project or provide some help in the user's use process.

However, the documentation for many Open-source projects is disappointing, mainly in the following areas.

1. Lack of a good readme or introduction

The readme can enable potential users to have a preliminary, quick understanding of your project, and if the project is on GitHub, the Readme file will automatically appear on the project's home page. A good introduction is essential if you want to attract users all of a sudden and ask them to continue to explore your project. If the introduction is bad, these users may not come back again.

The Readme file should contain at least:

• Project use
• For the crowd
• Platform or hardware to run
• Important dependencies
• How to install, or something deeper

Project Readme must be written for someone who has never heard of your project. For example, there is a module in the project that calculates the Levenshtein distance, and you don't assume that everyone who is reading the Readme knows what Levenshtein is. You should explain, and add the relevant details of the links to facilitate further exploration.

When introducing a new thing, do not introduce other new things, such as "numberdoodle similar to Bongocalc, but better", people may not know Bongocalc.

2. No online documentation available

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

I posted an open source project before and I was annoyed that users often emailed me questions I had answered in the FAQ, and later I realized that I didn't put the FAQ on the site. This is a relatively easy mistake, because the author does not stand in the user's perspective to consider the problem.

3. Only available online documentation

You cannot provide online documentation, but you cannot provide only online documentation. Some projects are not included in the final version of the document, or contains the project development phase of the incomplete documents, and the final document on the Web, which to users without network, causing a certain amount of trouble.

For example, the SOLR project has a very comprehensive wiki (document), but the download is a 2200-page auto-generated API Javadocs, where the only document for end users is a single-page tutorial.

The PHP language pack also doesn't come with any documentation, and if you want a document, you have to go to a separate page. Unfortunately, only the download core document is available and there are no comments that are helpful to the user.

Open source projects cannot take for granted that users can surf the Internet. Nor can you make users overly dependent on the project site. Over the past few months, I've found SOLR wiki downtime at least two times, and I was in dire need of a tricky configuration problem.

The better part of this is Perl and its CPAN module library. Each module document is available in an Easy-to-read hyperlink format on search.cpan.org and metacpan.org. For offline environments, each module document is embedded in the code itself, and when the user installs the module, a local document is automatically created as the instruction manual. The user can also use the Perldoc module::name command in the shell to get the document. Whether online or offline, you can use it.

4. The document is not installed automatically

This is usually the fault of the creator of the installation package. For example, in Ubuntu Linux, the Perl language document is a stand-alone, optional package that users may omit from installing. Although a few MB of disk space is saved, users cannot find it in time when they need it.

5. Missing screenshots

Sometimes, a picture is better than words.

A screenshot can help the user visually compare the results of the operation, see if the tasks are done correctly, or easily find out where the problem is.

Now, using video to introduce items is also becoming commonplace, and video can show the steps of a complex process. For example Plone project, there is a dedicated website to provide video tutorials. However, the video can not replace the screen capture, because users can not quickly find some content through video (need to see 1.1), and the video could not be included in Google Image search, screen capture.

6. Lack of realistic examples

Screenshots are good for code based projects, but giving an example is more practical. These examples should not be abstract, but come from the real world. Developers should take the time to create a relevant example to show the user how the project solves the problem.

As Rich Bowen of the Apache Project says, "a correct, full-featured, tested, annotated example trumps one page of tedious introductions." ”

7. Lack of links and references

Don't assume that the content you want to explain is part of the document, or that the user has read it before, or knows where it is, no longer need to use hyperlinks. For example, part of your project is to manipulate Frobbitz objects, you need to explain Frobbitz objects, or link to related pages.

8. Do not consider new users

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

9. Do not listen to the user's feedback
You should actively listen to the advice and needs of users who use your software, such as "If you have an introduction or link to a database driver installation, this will help me install this program".

Create a common problem based on feedback from the user. And often focus on other sites or forums, such as StackOverflow, and create a Google Alert to learn about the Internet's discussion of your project.

10. Do not accept user input

If your project has a large enough user base, you can consider allowing users to write comments directly to the document. The best example I've seen is PHP, where each page document allows authenticated users to comment on the page, or to add a Non-core document example.

These things need to be maintained, because over time, there will be some outdated annotations that need to be eliminated.

11. Must be installed to understand the purpose of the project

Each software project needs to have a feature list and a screenshot of the page, and if it is a pure code project, such as a library, there should also be a sample page.

12. Rely on automatic document generation

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

In the worst case scenario, there is nothing in the changelog except for some submission information. Changelog should list new features, bug fixes, and potential compatibility issues, and the target group is the end user. And the submission log is for developers to see.

13. Treat small white users with an arrogant attitude

Instead of "RTFM" (Read the freaking Manual, reading the TMD manual), you may scare a group of potential users.

If the user's problem can be found in the document, but they do not do so, do not think it is stupid. It may be because your documents are poorly written, difficult to read, or incomplete. You need to be patient about improving the "Getting Started" section, explaining what the software is for, or showing the user where to find relevant information.


English Original: Things people hate about Your Open Source Docs