Skip to content

Writing effective ReadMe for any project

A README is a text file that introduces and explains a project. It contains information about other files in a project or archive of computer software. [Source: Wikipedia].

Enlisted here are some points which are intended to help new user to write effective readme files for their projects.

Adding images and gifs to your readme

  • Pictures and gifs are a great way to add substantial value to your readme, making it very easy to provide instant context to what problem your software solves, or how. A short demonstration can also be generally included in the readme via a gif. Below are some guidelines which can help you to add better value minus the clutter.
  • Your picture should be on point. It should not contain anything else that may confuse the reader. For example, if you want to show a camera, then having a laptop in the same picture as the camera may lead the reader to believe that perhaps the laptop is also needed for the operation of the camera. Be mindful of this fact.
  • Environment of the image or gif should be consistent with the purpose of the project. For example, if your project is about using computer vision on vehicles, then your demonstration should use vehicles (and not apples for example).
  • When showing a demostration, it would be nice to have a textual prompt somewhere on the screen which "narrates" the demonstration to the reader. Note that gifs don't have sound.
  • Sometimes you may be tempted to use a picture where a simple diagram might suffice. Don't forget to use the "simplest way first". Don't use a picture where a diagram would be enough.
  • Always aim for easier, faster and better understanding of the reader when you embed images or gifs to your readme.
  • The images or gifs that you use, should in no way divulge any personal information or any identification of instruments, tools, infrastructure in any way. Do not overlook privacy concerns of not just yourself, but others as well.