Ten essential points to include in your next read me file


Introduction

This topic traverses any programming language. For all projects, no matter how small or large, there is always the need to have a read me file with sufficient details.

What is a ReadMe file ?

In brief, a read me file tells other developers all they need to know about your project.

How to start

To set up your readme simply create a plain text file and name it README (or to be more specific README.md or README.markdown ).

Add this file to your git commits. Remember to place the file at the root of your repo. Online repositories such as GitHub, Gitlab or Bitbucket will then pick this up as the project’s readme file.

Tips

Start writing a Read me file from the very beginning of the project. This is to prevent you from forgeting some pertinent information.

When writing instructions, pretend like you are writing them for someone who knows next to nothing about your application. You could test the usefullness of the readme file with someone else. Let us see if they can get a handle on your application.

Sections to include

The Date

I usually like to write the date in the American format, that is year-month-day.

For example: Demo Program written version 2.0 2014-09-08

The Authors

These can be a list of authors or a single author. These are all the developers who have contributed in some part to the project. For example, is Authors: John Doe

General Information:

The “General Information” section should give other developers an idea of what the project is all about as well as who is involved on this project.

Information you might want to include could be:

  • The name of the project
  • The name, contact details of the client and any 3rd party vendors
  • The names of the developers on the project
  • A brief description of the project: You should make sure you answer the question of what problem the project is solving. Also, you could mention if this is if it’s a replacement or a fork of something else
  • An outline of the technologies in the project: What frameworks were used for example Rails, Django, Play, As well as the storage used for your database.
  • Links to any related projects: For example, is this a Django API corresponding to other front-end clients like iOS and Android clients.
  • Links to online tools related to the application: These could be links to your Dropbox where your wire frames are stored and other such details.

Getting Started:

This section outlines the process of getting the application installed and made usable for the programmer. I define ‘usable’ in this context as being able to all the functionality available to the application. Information you might want to include is:

A detailed spin-up process

This includes instructions on installing the application. For example, is the application dependent on some form of storage, for example Mongo database.

Instructions on running the app

For example, on a Rails apps you might have to include details like the rake db:create, db:migrate as well as other instructions on starting a server (for instance are we using pow, or just the default “rails s”).

Secrets and configuration management

Be sure to list the configurations needed, for starting the application up.

Other useful details to include are a list of credentials that can be used to log in with each user type in the system.

The user credentials will be useless without the login URL. Hence please do not forget to include that as well. Any information about subdomains in the application (For example api.mydemoapp.dev/) are also appreciated.

Testing

Include the test suites used in the application. Perhaps you used RSpec, Jasmine, Cucumber. Also details the setup to make this possible. This is a vital section.

The Development, Staging and Production environments:

In developing an application, there are at least three environments. These are the development, staging and production environments. Depending on your setup other environments such as pre-prod, and DR ( disaster recovery ) could also exist.

Have at least one section per environment. This would be helpful since he now knows how these environments operate. Information you should include is:

  • Which server is the application on? Is it on Amazon Oregon? Or a server down the road?
  • How can the developer connect to the server? Do they need permissions, and what are they?
  • Are there cron jobs that the developer should know about, and what is there use?

Known Issues

Are there any problems with features of the application that the developer should know? For example, let the developer know if no validation has been made on incorrect dates.

Help

Basically, this should be how to get information to better use the system

Contact Information

Add contact information of the developers. Their phone number and email should suffice. For instance Eli can be reached at

  • Voice: +233-241407600
  • email: anthony.eli.agbenu@gmail.com

Planned enhancements

Sometimes some projects look to be unfinished. And that is very true. By the project’s very nature, a lot needs to be done before it is ready for the next release.

Add this section, so that anyone who pulls the project understands the reasoning behind your architecture of the project. On the other hand, if you are not around to take over the project, then the new developer can implement these recommendations you gave. Of paramount importance is not to let the project die when you leave the project.

Parting comments

I realize sometimes the urge to just start programming can be great and you just want to leap headfirst into the project. Yet still I hope you embrace the habit of writing a Read me file sooner rather than later.

God willing, I will catch you again soon. Stay blessed.

Cheers.

Anthony Eli Agbenu would love to get in touch
© 2021 Eli's blog. All rights reserved.