Last updated January 25, 2014. Created by MGParisi on April 28, 2009.
Edited by davidneedham, pfrenssen, rootwork, ao2. Log in to edit this page.

README.txt
Every contributed module should provide a README.txt in the package. This file should contain a basic overview of what the module does and how someone may use it. The contents of the file may be a repeat of the synopsis on the project page. See the Module documentation guidelines for further details, and refer to the README.txt Template.
INSTALL.txt
This is an optional file that can be used if the "readme" file is too large or complex. It would concentrate on the installation tasks: system requirements, installation instructions, frequently asked questions, etc.
Plain-text documentation format
Although Drupal core modules do not contain README.txt files, the general format for plain-text documentation files in contributed modules should follow that of Drupal core's INSTALL.txt. For instance, it is recommended and generally accepted that the file should wrap at 80 columns with unix-style line endings (\n).
Style
Stylistically, there is no standard or consensus yet, but the best practice is to follow the example of Drupal core. Generally speaking that means:
  • Headings in all caps.
  • Headings underlined with --- to the length of the heading, followed by a newline.
  • Bullets denoted by asterisks (*) with hanging indents.
  • Numbered lists indented 4 spaces.
  • Bulleted lists indented 1 space.
  • Text manually word-wrapped within around 80 cols.

You may reference the README.txt Template.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

I think it's time to use Markdown for the files so we can use .md files right?

I support!