Recently a project from a programmer to a senior document brother, well, I am not called advanced, but I found that writing documents is not easy, how to make people look comfortable, comfortable, cool not, after reading want to give you a thumbs-up? I also summed up some feelings about writing documents, can not be said to be experience, after all, my younger brother is still young, haha.

Writing a README for a project is like writing a preface to a book. A good project should not only consist of high-quality code, but also high-quality documentation. For users, a good document can save a lot of time.

internationalization

For example, GitHub is a code hosting platform with a different name, the largest gay dating site in the world. Your project may not only be used by Geeks in China, but also a good project with users from all over the world, so a bilingual document in English and Chinese is crucial.

After all, documents in your native language will feel more familiar and easier to read.

For example, the Ant Design Pro documentation:

What is the project about

First, have a project name. It doesn’t have to be fancy, but it has to be catchy, not a mouthful, and not too long.

For example, Chalk, React, Vue, Commander, etc. If you really don’t know what to do, make a random function and try your luck.

Of course, if you have a LOGO is the best, a high definition LOGO handsome face, look comfortable there is no.

Like this:

  • What language is it written in? Node, Python, or something else
  • What is the purpose of this project
  • Latest Version Information
  • Build, test results, etc
  • Demo Demo address or official website

Something like this:

shield.io

At the same time, we should summarize the highlights of the project, which features are exciting, others do not, this is a good way to attract users.

Like this:

Installation and quick start

This part of the content is a very important part of the document, through these steps, can let the user quickly use.

First, you should tell the user how to get and initialize the project, such as the following:

API

API is the soul of a project. It is the most direct place to expose users. When users have questions, they will immediately turn to your API documentation.

What should be clear about an API is:

  • role
  • Is the input parameter and each parameter required, what is the data type, and so on
  • The return value

If you don’t have a lot of apis, you can put them in one file, but if you have a lot of apis, it is recommended that you put them in a separate file with a single link.

Also, if you have multiple versions of your API, you may need to prepare several copies of your API documentation to address different requirements.

Like this:

Version changes

It is also best to have a CHANGELOG document, what changes have been made to different versions, what features are available and so on, so that users know what each version does.

Like this:

FAQ

Of course, if you don’t want to answer very repetitive questions, I think you need an FAQ to document some frequently asked questions.

contribution

I’m sure many of you, like me, are proud to submit PR to well-known warehouses.

So if there was a way or a way to submit PR, to attract more people to contribute code, and to expose contributors, I think there would be more people willing to contribute.

For example, it’s interesting to see a list like this:

copyright

I believe that not long ago Facebook open source agreement events we all know, is also noisy, so, for the open source agreement and so on the copyright issue must be careful, if you want to do is not a toy project, so about this must write clearly.

conclusion

In conclusion, this may or may not be enough for a good README, but the document is always there for the user, so what the user cares about is the focus of our document.

But here are the basics we should all need:

  • The name
  • Introduction to the
  • function
  • Install the configuration
  • A quick tutorial
  • The API documentation

These are points that users care about and should be considered before writing.

These are just when I am doing some document work, I looked at a lot of documents, comprehensive impression, write so much, but the actual situation may be very different, so whether to write so, we have different opinions!