Writing a good README Copy

Introduction

You’ve worked hard and built a great application, but now what? You want your code to be available for others to view.

While working on a project, keep in mind that you will need other developers to understand your code and what it does.However, reading through code in order to understand the project is time intensive. Additionally, the code itself cannot convey everything that others might need to know. So accompanying it with an extra guide README file will be really helpful.

Learning Objectives:

  • What is a README File?
  • Why should I make it?
  • How should I make it?

Study:

What is a README File?

A README is a text file that introduces and explains a project. It contains information that is commonly required to understand what the project is about.

It is the first impression your project makes.By convention, the README file should be added to the top level directory of your Git repository. GitHub and other similar sites will look for this file, and actually display it as part of the project’s home page. It is often written in Markdown (.md), which quickly structures and formats your text. You can check the documentation of Markdown here .

What should be included in a README?

1- Project’s Title:

This is the name of the project. It describes the whole project in one sentence, and helps people understand what the main goal and aim of the project is.

2- Overview:

A brief description outlining what the project. The quality of a README description often differentiates a good project from a bad project. A good one takes advantage of the opportunity to explain and showcase:

  • What your application does,
  • Why you used the technologies you used,
  • Some of the challenges you faced and features you hope to implement in the future.
3- Table of Contents:

If your README is very long, you might want to add a table of contents to make it easy for users to navigate to different sections easily. It will make it easier for readers to move around the project with ease.You can link to the different sections below

4- Description:

A more detailed outline of the project. What does it do? Is there a high level list of features? If describing a project that has visual features, consider adding pictures or animations of the features and functionality in this section. See Adding Screen Captures below.

The quality of a README description often differentiates a good project from a bad project. A good one takes advantage of the opportunity to explain and showcase:

  • What your application does,
  • Why you used the technologies you used,
  • Some of the challenges you faced and features you hope to implement in the future.
5- Installation:

How can another developer get your project up and running on their own? What dependencies are required? Are there environmental requirements? Be specific, and outline steps to take in order to get the project running.

Provide a step-by-step description of how to get the development environment set and running.

6- How to Use the Project

Provide instructions and examples so users/contributors can use the project. This will make it easy for them in case they encounter a problem – they will always have a place to reference what is expected.

You can also make use of visual aids by including materials like screenshots to show examples of the running project and also the structure and design principles used in your project.

Also if your project will require authentication like passwords or usernames, this is a good section to include the credentials.

For a library or framework, this section would outline how to use the library within another project (see socket.io ). For a service that is meant to be used within a larger project architecture, instructions on how to integrate may be necessary (see node-statsD ).

7- Include Credits:
  • Team Members : If you worked on the project as a team or an organization, list your collaborators/team members. Describe roles on the team such as "Product Owner", "Scrum Master" and more.. You should also include links to their GitHub profiles.

  • Also, if you followed tutorials or referenced a certain material that might help the user to build that particular project, include links to those here as well.

This is just a way to show your appreciation and also to help others get a first hand copy of the project.

  • Related Projects: Links to other repositories that are related to the current one. Are there partner projects? Is there a newer version of this project elsewhere?
8- Add a License:

If open source, state how the project is licensed.


Additional README Sections:

Additionally, for some projects, additional information might make sense.

9- Badges:

It provides a long information short! It can hold information such as

  • version of npm used
  • status of last build
  • number of downloads happen over period of time
  • license type

Don’t know where to get them from? Check out the badges hosted by shields.io.

10- How to Contribute to the Project

If you’d like others to be able to contribute to your work, outline a process through which they can submit a request for changes to be incorporated. More specifically, outline the Git workflow for these contributors. Should they use a feature branching workflow? Should they rebase or merge? Should the fork the repository? What is the review process?

11- Include Tests

Go the extra mile and write tests for your application. Then provide code examples and how to run them.

Extra points

Here are a few extra points to note when you’re writing your README:

  • Keep it up-to-date – It is a good practise to make sure your file is always up-to-date. In case there are changes make sure to update the file where necessary.
  • Pick a language – We all come from different zones and we all speak different languages. But this does not mean you need to translate your code into vernacular. Writing your README in English will work since English is a globally accepted language. You might want to use a translator tool here if your target audience isn’t familiar with English.

Adding Screen Captures

When documenting a project that focuses heavily on user interface features and functionality, it can be helpful to include pictures or animated gifs of the project. This is a great backup for maintaining a deployed build of the project, as readers can see the running application without setting it up themselves.

Think through key user interactions that you’d like to record. It is best to separate interactions into individual screen captures and include multiple short gifs, as opposed to a single longer gif with multiple steps.

Tools that can help you capture a screen recording include:

Resources:

Leave a Reply