Søren's Blog

Random Ramblings

Previous Entry Share Next Entry
The anatomy of a README file
I like to put a README file in the root directory of all my software projects. And as I would never do any kind of software development without using some kind of version control (e.g. Git), the README will also be in the root of the repository.

The README is the first piece of documentation a new development will see. It does not need to be the only, in many cases you will have an issue tracker, a wiki or other site with further documentation. You should list those in the README.

Because the README is what the developer sees, it should describe how to build the software and what tools are required (including versions). Describing the directory structure is also a good idea, especially if it's a complex system.

Below is an example of a minimal README, you can use as a template:

System Name

A short description of the system.

Copyright and/or company information.

If relevant name and description of customer.

Links to other documentation, issue tracker, etc.


The following tools are required for development:

* tool version 1.2.3
* another thingy version 4.0

Directory layout

All source files are placed in the src directory. 
Generated files are placed in build. This README, the
Makefile and a few helper scripts are placed in the root.
Documentation can be found in doc.


You'll need access to the repository, mainline development is 
done here:

* http://subversion-server/svn/project-name/trunk/

Install the required software. Setup you local database...

Build by issuing the following command

* build

Deploy to you local server using:

* deploy

Now the system is deploy on http://localhost:1245/system/


Log in