README files

Last updated October 19, 2011. Created by MGParisi on April 28, 2009.
Edited by pfrenssen, rootwork, ao2, jwilson3. 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.

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, however you may borrow from the following examples:

• Morbus' README.txt style (which matches Drupal core's style the closest)
• sun's README.txt style
• John VanDyke & Matt Westgate README.txt style
• syscrusher style

A template for README.txt?

For more information, or to participate in the ongoing discussion, please refer to this thread in the Coding Standards and Best Practices group.