документация – How to write a good README?

Question:

I think everyone has seen README files. I would like a detailed guide on how to write an exceptional README with as little effort as possible.

  • What is a "README file"?
  • What should I write in it?
  • How should I format it?

Answer:

The README should be simple and short. A good README can save time, especially if it's a README for something like a library that parses command line options.

Here's what it should include:

  • names of projects, all submodules and libraries (sometimes they are named differently and confuse new users)
  • description of each project, all submodules and libraries
  • 5-line snippet (code snippet) with usage example (if it's a library)
  • copyright and license information (or link to license)
  • instructions on how to find documentation
  • instructions for installation, configuration and launch
  • instructions for obtaining fresh sources and detailed assembly instructions (or a quick review and a link to installation instructions)
  • a list of developers or a link to a file with a description of the authors
  • instructions for submitting bug reports, feature requests, change requests, patches, and how to receive announcements, join a mailing list, or join the developer community in other forms
  • contact information (email address, website, company name, address, etc.)
  • a brief history of changes, if this is an update or a fork of another project
  • legal information (for cryptographic software)

The Apache HTTP Server has a simple but good README . Another good example is the README for GNU make available online.

About formatting:

stick to Unix tradition as much as possible, and/or use markdown, especially for projects on Github that render README.md to an html file.

  • Only ASCII characters if the README is in English
  • write it in English, if possible, and include the file with the translated version. Add a two-letter extension corresponding to the language to such a file, for example README.RU
  • no more than 80 characters per line
  • one blank line between paragraphs
  • underline the header line with minus characters
  • use spaces (0x20) for indentation, not tabs

Let's put it all together…

Документация
-------------

GNU make полностью документирован в справочнике по GNU make, который содержится
в этом дистрибутиве как файл make.texinfo. Вы также можете найти он-лайн,
PostScript и DVI версии на сайте FSF. Там же приведена информация о заказе 
документации в печатном виде.

http://www.gnu.org/
http://www.gnu.org/doc/doc.html
http://www.gnu.org/manual/manual.html

Wikipedia defines the README as:

A README (or READ ME) file contains information about files in a folder or archive and is usually distributed with software.

Wikipedia lists parts of the README:

  • setup instructions
  • installation instructions
  • Operating Instructions
  • manifest file
  • copyright and licensing information
  • contact information for distributor or developers
  • known bugs
  • troubleshooting
  • credits and credits
  • List of changes
Post Views: 8
Scroll to Top