README, I Am Awesome



Author: Kostas Papanikolaou

Categories: Technology

README, I Am Awesome

When first encountering a device, piece of software, or technological creation in general, there are two approaches one can take, based on the circumstances and importance of what that creation does:

  • Read the Manual
  • Learn by Using

These are two rough, wide approaches, which can of course be split into different categories each one. The final decision on which path to follow is defined by several different factors. For example, you can learn how to use a spoon without the need of a User’s Manual. Hand-held tools that are not complicated are overall easy to understand for any human, without having to read instructions.

However, there are more complex creations, that require extensive instructions on how to be handled. A great example is a software. A complicated application or software overall contains several lines of code. It takes delicate work from software developers, programmers, and others, in order to be functional. User’s Manuals for software are called README files, and they are defined as follows:

A README file contains information about other files in a directory or archive of computer software. A form of documentation, it is usually a simple plain text file called READ.ME, README.TXT, README.md, README.1ST, or simply README

In essence, README files are the foundation of every software, containing all the information needed by anyone using that software in order to understand the direction of the software and its purpose. README files also contain steps to get the software running and more.

Why do we need it?

Well, simply put, why do we need every User’s Manual ever created? In order to understand how the device or software -accompanied by that Manual or README respectively- works. Maintaining and collaborating become seamless when a README file is included, as other software developers and programmers will be able to understand your software by reading all the contents of a README file prior to using/testing your software. README files can also be used by users that are not developers. They contain information that helps anyone understand why and how software was created, as well as how it works.

How to create a README file?

First and foremost, we have to make it clear that README files can be written in any text file format. There are no boundaries here, as long as the README is complete, and ready prior to going public with the software you have developed. There are a few “musts” when creating a README file, and most of these have to do with writing and presentation:

  • Titles, titles, and titles
  • Why, How, and What
  • Be analytical
  • Code matters
  • Presentation gives status
  • EXTRA: Live Demo

Defining each section with a clear, easy-to-see Title is of vital importance, since a README file contains a large amount of information, in regards to several different aspects of software. Define each section in a clear and simple manner, so that anyone who reads this file will be able to understand what each section is about.

The threefold “Why, How, and What” is not just a way to look at business Branding. It actually applies to pretty much every decision and action a person, a team, or a company makes. In your README file, explain Why you developed this software, How you developed it, and What does it do. Define its purpose.

We all can’t be perfect at everything, but writing a README file is not something that can be done from a professional Content Writer that had nothing to with the software in question. Make sure that in your writing, as a developer creating the README file, you are as analytical as possible. The more information the user of the README has, the better. You are never tired of learning how to use software that will help you.

Obviously, Code matters. Software IS Code, and therefore, Code is vital for a README file. Other developers who read this file will be able to understand code, and they will expect to see it there, in order to understand your software in-depth. Highlight your code examples, and make sure they stand out as much as possible when needed. Use them as you see fit, as long as they are relevant.

The README file is a piece of text, and presentation matters, both for users and developers that will read it. Try to include Videos, Images, and even GIFs showing certain actions of your software. Seeing something instead of reading it, helps most humans understand better what software or a device does.

Finally, if you want to be… extra -which is never bad for a README file or anything that provides instructions and information- you can accompany your README with a Live Demo of your software. To be honest, you should, since this is proof that software is not a piece of code, but something that is ready to run and is tested. If possible, get your project hosted and set-up a running demo, then include it in your README file.

What does a README include?

The contents of a README file vary greatly, depending on the software they accompany, and explain in complete detail. A README usually contains at least one of the following:

  • Configuration instructions
  • Installation guide
  • Operating instructions
  • A file manifest (list of files included)
  • Copyright and licensing information
  • Contact information for the distributor and/or programmer
  • Known bugs
  • Troubleshooting
  • Credits and acknowledgments
  • A changelog (mostly for programmers)
  • A news section (mostly for users)

Examples of README files are dated back to the 70s, with much free software and open-source software coming with a README file. Over the years, many software packages have moved some of the aforementioned auxiliary files and piece of information into a website or a wiki. Most recently, the proprietary Git repository of GitHub, has started to strongly encourage the inclusion of a README file, which is automatically presented on the main web page of software if included in the main (top-level) directory.

README example

Above, we mentioned that Titles are fundamental for a README file, as they define where a section starts, and where it ends. Order and organization are vital for every single README created, and here is a simple example of a README file, by title:

Project title

Information about the software and/or overview of What the project is about.


Motivation

Short description of the purpose that lies behind the development and maintenance of the software, explaining Why it exists.


Build status

The build status of continus integration i.e. travis, appveyor etc.


Code style

If a code style such as standard, xo etc. is used, include this section, as it will help others while they contribute to your software.


Screenshots

Images, GIFs, Videos, the logo of the software, and anything visual that will help readers understand the software better.


Tech/framework used

For example, “Built with * Electron”


Features

A casing on what makes this software special.


Code Example

Showcase what the library of the software does. This will allow developers to understand How your software solves their problem.


Installation

Step-by-step instructions on how to install it.


API Reference

Small and simple software can have their reference docs within the README file, otherwise, they usually have a link to the API reference docs are.


Tests

Show examples of how to test the software.


How to use it?

This is self-explanatory. Explain how one can use the software.


Contribute

Inform other developers about the possibility of contributing to your project.


Credits

Give proper credits to everyone included, whether it is collaborators, blogs, those who inspired and helped you, and anything else.


License

A short description of the license (Apache, MIT etc.)

Tags: README, README file