Claire N Streb - Expert Remote Senior Software Pro: September 2015

What is a readme file? It is a text file that helps other developers know how to do things with your software project that aren't obvious like:

Special build instructions
Third-party package descriptions
Where to find the associated technical documentation or official software development procedures
How build the API documentation
How to run a code analysis
TDD procedures

The goal of the readme file is to keep it short and sweet. Provide just enough information to help the developer know how to work with the software project.

What are the contents of a good readme file? Your readme file's content depends on the nature of your project. Here are some some examples:

If you are writing software that is only going to be modified in-house or as an open-source project, it makes sense to include a topic like How to get the latest version from source code control.
If you are delivering a software package, it is useful to include topics like How to install and Getting Started.
If you are delivering a web service API, a good topic could be How to authenticate your client.

What are the benefits of a readme file? There are quite a few benefits:

The file can be quickly created and maintained even in software shops that hold little regard for documentation or the software development process.
All current and future developers will have a single source of helpful information right at their fingertips, right alongside the code. This saves a LOT of time (and we all know that time = money) and frustration.
It enables one to see when a procedure is getting overly complicated and in need of refinement and simplification.
It provides a talking point for discussion.

How does one name a readme file? README.TXT, README, readme, readme.html, readme.txt, or _readme.txt. Depending on your operating system and the tool/command you are using to view your files, the highlighted names are typically used to cause the file to appear close to the top of the list of files.

When should we create the readme file? Ideally before any code is written. This helps the author plan and think about how to structure the project(s).

What are some other possible uses? For those using .Net, a project-specific readme file can be used for each project instead of one readme file for your entire solution (.sln). A project can be used in one or more solutions. A project-specific readme file lets one record important details about the project, whereas a solution-specific readme file can be placed in a Solution Files folder at the top of the solution. For example:

What is a good example of a readme file? My favorite is to have a table of contents that the reader can easily skim, copy the topic string to the clipboard, then do a 'find' pasting in the topic name to locate the details of the topic. This is shown below:

    PROJECT-X DEVELOPMENT README FILE

    *** TABLE OF CONTENTS ***
    WHAT IS THIS PROJECT?
    WHERE IS THE CODE LOCATED (FOR XYZ EMPLOYEES ONLY)
    ITEMS NEEDED
    HOW TO BUILD (COMPILE)
    HOW TO ADD A NEW PROJECT
    TROUBLESHOOTING
    CODING STANDARDS

    *** DETAILS ***

    WHAT IS THIS PROJECT?
       etc.

Other sources:

Why I wrote this blog post: As a software consultant, most software projects I have seen either have no readme file or one so huge it is difficult to maintain. The latter point indicating the software project might possibly be overly complicated, or perhaps it is so large that each module warrants its own readme file.

Claire N Streb - Expert Remote Senior Software Pro

Saturday, September 12, 2015

All Hail the README File!