2009年4月13日 星期一

[轉]How-To Write a Good Readme File

How-To Write a Good Readme File

First year students in the Software Engineering and Management programme at the IT-University of Göteborg are currently in their final hours of their first programming assignment hand-in. As supervisors, we're slightly worried that we will have to spend a lot of time getting the assignments to run properly, or even at all. One way to justify this is to provide a clear readme file. Therefore, we are providing what we believe is a good example of such here.

There are six details one at a minimum, should address when writing a readme. These are:

  • Application Name
  • Developer names and contact details
  • Application description / purpose
  • How to start / install the application
  • Assumptions
  • Requirements
  • Known issues

This may seem like a lot of work, but remember, we're not asking you to write an essay! A readme should be short, clear and well structured. Here's an example:

Name:
Ultimate Guessing Game

Description:
Guess a number between 1 and 1000. Play against the computer,
or let the computer play against you.

Running:
Compile the Java classes and start the game by executing start()
in Game.java in a terminal or command prompt.

Assumptions:
This application have only been tested on Ubuntu 8.04.

Requirements:
Java 6.0

Known Issues:
The high-score list is not sorted automatically.

Author(s):
Marcus Ljungblad, Quandoo, [marcus@qua...se]

Obviously there are many formats for readme's, the important part is to keep it simple and clear. And only if necessary, elaborate with further text or images, but stay within the scope.

0 意見:

張貼留言