The following components and template are based on the input of many who contributed to the discussion "Create a README.txt template". For the sake of having a fleshed out example, we're using some sample text. Most of it comes from the Administration menu module's README.txt.
Table of contents
TOCs are optional, but appreciated for lengthy README files.
CONTENTS OF THIS FILE --------------------- * Introduction * Requirements * Recommended modules * Installation * Configuration * Troubleshooting * FAQ * Maintainers
The introduction (required) shall consist of a brief paragraph or two that summarizes the purpose and function of this project. This introduction may be the same as the first paragraph on the project page.
The introduction should include a link to the project page and issue queue. If the project is a sandbox, these links should go to the sandbox until promotion.
INTRODUCTION ------------ The Administration Menu module displays the entire administrative menu tree (and most local tasks) in a drop-down menu, providing administrators one- or two-click access to most pages. Other modules may also add menu links to the menu using hook_admin_menu_output_alter(). * For a full description of the module, visit the project page: https://drupal.org/project/admin_menu * To submit bug reports and feature suggestions, or to track changes: https://drupal.org/project/issues/admin_menu
The requirements section (required) shall make it clear whether this project requires anything outside of Drupal core to work (modules, libraries, etc). List all requirements here, including those that follow indirectly from another module, etc. The idea is to inform the users about what is required, so that everything they need can be procured and included in advance of attempting to install the module. If there are no requirements, write "No special requirements".
REQUIREMENTS ------------ This module requires the following modules: * Views (https://drupal.org/project/views) * Panels (https://drupal.org/project/panels)
This optional section lists modules that are not required, but that may enhance the usefulness or user experience of your project. Make sure to describe the benefits of enabling these modules.
RECOMMENDED MODULES ------------------- * Markdown filter (https://www.drupal.org/project/markdown): When enabled, display of the project's README.md help will be rendered with markdown.
The installation section (required*) shall make it clear how to install the module. However, if the steps to install the module follow the standard instructions for Drupal 8, Drupal 7, Drupal 6/5, or a theme, don't reinvent the wheel — simply provide a link and explain in detail any steps that may diverge from these steps. Take special note of Drush integrations. In a case where many Drush commands are added, consider adding a section for Drush.
Consider replacing this section with a standalone INSTALL.txt file if your installation instructions are especially complex.
* - required unless a separate INSTALL.txt is provided.
INSTALLATION ------------ * Install as you would normally install a contributed Drupal module. See: https://drupal.org/documentation/install/modules-themes/modules-7 for further information. * You may want to disable Toolbar module, since its output clashes with Administration Menu.
The configuration section (required) is necessary even when little configuration is required. Use this section to list special notes about the configuration of this module – including but not limited to permissions. This section is particularly important if the module requires additional configuration outside of the Drupal UI.
If the module has little or no configuration, you should use this space to explain how enabling/disabling the module will affect the site.
CONFIGURATION ------------- * Configure user permissions in Administration » People » Permissions: - Use the administration pages and help (System module) The top-level administration categories require this permission to be accessible. The administration menu will be empty unless this permission is granted. - Access administration menu Users in roles with the "Access administration menu" permission will see the administration menu at the top of each page. - Display Drupal links Users in roles with the "Display drupal links" permission will receive links to drupal.org issue queues for all enabled contributed modules. The issue queue links appear under the administration menu icon. * Customize the menu settings in Administration » Configuration and modules » Administration » Administration menu. * To prevent administrative menu items from appearing twice, you may hide the "Management" menu block.
CONFIGURATION ------------- The module has no menu or modifiable settings. There is no configuration. When enabled, the module will prevent the links from appearing. To get the links back, disable the module and clear caches.
Troubleshooting & FAQ
These sections are optional. If present, they should address questions that are asked frequently in the issue queue (this will save you time in the future). Outline common problems that people encounter along with solutions (links are okay if the steps are long, but it is often helpful to provide a summary since links sometimes go stale).
TROUBLESHOOTING --------------- * If the menu does not display, check the following: - Are the "Access administration menu" and "Use the administration pages and help" permissions enabled for the appropriate roles? - Does html.tpl.php of your theme output the $page_bottom variable? FAQ --- Q: I enabled "Aggregate and compress CSS files", but admin_menu.css is still there. Is this normal? A: Yes, this is the intended behavior. the administration menu module only loads its stylesheet as needed (i.e., on page requests by logged-on, administrative users).
This section is optional and should replace any pre-existing standalone MAINTAINERS.txt file.
MAINTAINERS ----------- Current maintainers: * Daniel F. Kudwien (sun) - https://drupal.org/user/54136 * Peter Wolanin (pwolanin) - https://drupal.org/user/49851 * Stefan M. Kudwien (smk-ka) - https://drupal.org/user/48898 * Dave Reid (Dave Reid) - https://drupal.org/user/53892 This project has been sponsored by: * UNLEASHED MIND Specialized in consulting and planning of Drupal powered sites, UNLEASHED MIND offers installation, development, theming, customization, and hosting to get you started. Visit https://www.unleashedmind.com for more information.
Advanced help will display the README file on the screen if it is enabled.
During the Drupal project's lifetime, there has never been a clear consensus about what a README-file should look like, and many different styles exists as a result (see links below). However, we prefer new projects to use the format described on this page, or a format recognized by the Markdown filter module. If you use Markdown, your file should be named README.md (and use valid Markdown syntax), otherwise it should be named README.txt.
Here is a summary of the preferred format for README.txt:
- Headings in all caps.
- Headings underlined with
---to the length of the heading, followed by a newline.
- Two lines prior to headings (except the first one).
- 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.
Some sample README-files: