How to write quality README!

Tram Ho

Arguably the most important piece of documentation for any open source project is README . A good README not only informs everyone what the project does and who it is for but also how they use and contribute to it.

What is README?

Basically, README is a text file (.txt or .md) that acts as a document for a project or directory. It is often the most visible documentation and landing page for most open source projects. Even the README file name is fully capitalized to catch the reader’s attention and make sure it’s the first thing they read.

There is evidence that README dates back to the 1970s. The oldest example I can find is this README for DEC’s PDP-10 computer, November 27, 1974. Although the origin of the name README is Arguably, the two most common hypotheses are:

  • Programmers of the main mainframe computers that originally came with punch cards, will leave a stack of paper instructions with the word READ READ ME! written in the foreground .
  • The name was inspired by Alice in the wonderland of Lewis Carroll, in which the protagonist Alice found a potion labeled DRINK ME! and the cake labeled “EAT ME” changed her size .

What should be put in README?

Ok, so what should the great README file contain?
To get started, I recommend including the following important things:

  • Name the project (or something README wants to target):
    Don’t forget to name your project or highlight your name. There are some surprising projects on GitHub that have no name.
  • Introduction or summary:
    Write a short introductory two or three lines explaining what your project does and who it is for. Also, remove titles like ‘About’, ‘Summary’ or ‘Overview’ – this is clearly an introduction.
  • Prerequisites:
    Immediately after your introduction, add a section titled listing any knowledge or prerequisite tools that anyone who wants to use the project may need before getting started. For example, if it runs on the latest version of Python, ask them to install Python. Here is an example:

  • How to install:
    Provide installation steps! Surprisingly, there are many used projects that only provide basic user guides and expect you to know how to install it magically. Be sure to divide the installation into numbered steps if it requires multiple steps.
  • Using:
    Add steps to use the project when the user has installed it. Be sure to include usage examples and references that explain command or flag options if you think they will be helpful. If you have more advanced documents in a separate file or website, link to this document from here.
  • How to contribute:
    Provide steps to contribute to the project. In addition, you may want to create instructions for contributors in a separate file and link to this guide from your README if you want people to read it before contributing a pull request to your project.
  • Add contributors:
    Enter the name of any contributor who has contributed a lot to the author. It is a good way to make an open source project feel like a team effort and acknowledge the contributions of everyone who took the time to contribute.
  • Add citation:
    Similarly, if you have used anyone else’s product (code, design, image, etc.) with a copyright that requires confirmation, you may want to add it here. You can also acknowledge any other developer or organization that helped with the project.
  • Communications:
    You may not want to do this because you are an extremely private person but if someone has questions, wants to collaborate with you, or is impressed enough with your project to give you employment opportunities, it is true that it makes sense to have your contact details in the middle of it loud and clear.
  • Copyright information:
    You definitely want to include license information if available. Startups and other companies that rely on third party software don’t seem to be able to use your project unless you provide this. Check choosealicense.com or opensource.org for a list of licenses you can use.

    Add fire to REAME ?

    If you really want to make your README stand out and look really good, you can do the following:

  • Add logo: If your project has a logo, add it at the top of your README . Branding makes a project look cool and helps people remember it.
  • Add badges and shields: You can add badges and shields to reflect the current status of the project, the license it uses, and if any dependencies it uses are up to date. Plus it will look pretty good! You can find a bunch of badges at Shields.io .
  • Add screenshots: Sometimes a simple screenshot or a set of screenshots can help you avoid having to type dozens of lines of description. However, if you use screenshots, you will need to update them each time you update your project.
  • Using Emoji?

    Resources

  1. https://www.youtube.com/watch?v=2dAK42B7qtw
  2. https://www.youtube.com/watch?v=fXMN4X9B8Rg&feature=youtu.be
  3. https://github.com/kefranabg/readme-md-generator
  4. https://dev.to/scottydocs/how-to-write-a-kickass-readme-5af9
Share the news now

Source : Viblo