Sysadmin university: How to write a README file

The README file is one you normally see when you've downloaded source code in order to compile and install it on your system. It (hopefully) is a guide that helps you understand, install, and set up your new application with ease. Though that is the intention of the file, there are no real established standards for what to include in it. In this article, I'll offer my opinion on and preferences for ideal README file contents, plus I'll give you two templates that you can use to create your own. 

I'm not a hardcore coder, but for script groups or web applications that I might write in PHP, Perl, or shell scripts, I always supply a README file so that anyone who uses or supports my application will be able to better understand it and its function.

You may write your README in plain text, markdown, or any other text style that you choose. I prefer markdown, plain text, and HTML, in that order. I like markdown because it's easy to use, and you can make a nice-looking document with minimal coding weirdness and without a fancy editor. 

Project title

From a marketing point-of-view, your project titles should be plain and clearly communicate its function with no extraneous descriptors or wordplay. If it's a text editor, call it that—at least after a colon.

For example, if I create a web application project to help capacity and performance engineers manage hundreds of servers, then a good title for it might be "CapPlanMan: The Capacity Planning Management Tool" rather than something like "Glass Half Full: The Capacity Planner." I won't delve deeply into the psychology of naming, but I think you can see the idea here.

Description

The Description section describes the project, program, or application in 30 words or less. It is a summary of what the application does for the user, the technology it employs, and the purpose behind the project. Here is an example:

CapPlanMan is a web-based application using standard LAMP technology to help capacity planning engineers and performance engineers better manage their system's capacity and performance measurements. The application has an at-a-glance dashboard as well as drill-down capability for examining individual systems and clusters.

This description is basically your "elevator pitch" for the project. It's a short summary of what your project is and does without any fluff or propaganda.

Prerequisites

If your project requires any applications or special configurations, you will place them in this section. Not a lot of explanation is needed here. List any requirements, packages, configurations, and disk space considerations.

This project requires the LAMP stack, SSL, and a normal user service account with no login shell.

Also, add in any special requirements for file system permissions, database permissions, and so on.

Installation

This section describes the installation of your project files. You can optionally create an INSTALL.md file and refer to it here if the instructions are more than a few paragraphs long. But if you can keep it concise, include it here.

Run the install.sh script as root to install the files, set permissions on web directories,  import the CapPlanMan.SQL file, and clean up unnecessary installation files. Read INSTALL.md for a listing of all the changes made by the install.sh script.

Be sure to include all steps here or in the INSTALL.md file. There's nothing more frustrating than spending hours troubleshooting someone else's install script, so save your users the hassle.

Usage

Include any usage notes here. Provide generic syntax and examples. 

$ ./install.sh -uroot -pP@$$w0rd 

This entry can be as simple as the one above, or you can provide multiple scenario examples that describe the different options that are available.

Contributing

The Contributing section gives potential contributors a way to contact the author(s) and to submit errata or enhancements to the project.

If you'd like to contribute to this project or submit errata, please read CONTRIBUTING.md.

This is a necessary part of any community project. Everyone feels empowered if they can participate in the development of a project. It also adds value to have other people to contribute because it means that the project has value outside of your original scope.

Authors

Include all authors of a project. Optionally include an email address.

Kenneth Hess (2020)

License

Specifying a license is standard practice. There are many from which you can choose. If you need help deciding, this tool may give you some guidance. If you're creating code for work, be sure to check with your legal department for their feedback and approval.

CapPlanMan is licensed under GPL 3.0.

Acknowledgments

Acknowledgments are 'thank yous' to people who have provided resources to your project. Be sure to mention them here.

Thanks to the Enable Sysadmin team at Red Hat.

Wrap up

If you write and make software projects public, you should include a README document to accompany it. Don't leave your potential users adrift to figure out how to install and use your software. Make it concise. Use some sort of standard formatting so that readers understand what they're looking at. Below are two template links for you. Feel free to use them, my examples, or use the guidelines above to create one of your own.

—A README.md template on GitHub from Purple Booth

—README 101 from makeareadme.com

[ Want to test your sysadmin skills? Take a skills assessment today. ]