Embedded documentation style guide

The embedded documentation style guide describes guidelines for structure, content, and links in embedded documentation.

Structure

• The module documentation should be brief without repetition: 2 paragraphs and a list of links.
• In no more than 2 to 3 sentences, the first paragraph should clearly and succinctly describe the module through its benefits to users.
• The second paragraph should provide an explanation of module features that will help users to accomplish the most common tasks.
• The text should be followed by a list of complete sentences that describe a task and the path to the page where administrators can accomplish that task.
• The phrase "For more information, see the online handbook entry for Modulename module." should be added to the administration help so that "Modulename module" is linked to an appropriate handbook page. Note that the "Modulename module" should be capitalized as in the following examples: "Aggregator module", "Blog module", "Blog API module", "OpenID module".

Content

• For consistency, the first sentence of the first paragraph will include the module name.
• Use the term "post" instead of "node."

Links to common tasks

NOTE: In order to facilitate auto-generation of admin help documentation from the handbook, there have been changes to this section. Please read carefully.

• The links section should be easily scannable so that users can quickly navigate to relevant interfaces.
• The list of links should begin with the phrase "You can" and be followed by an unordered list of complete sentences that describe a task and identify the path to the page where administrators can accomplish that task. If the list has only one item it should be a single paragraph beginning with 'You can'.
• Create a path description using the following rules (take a look at the source code for some examples such as the aggregator and search module pages):

  1. If describing an internal Drupal link, such as admin/settings, use the notation:

  <strong class="drupal_link_admin_settings">administer >> settings</strong>

  Place the path in a <strong> attribute, and give it a class of drupal_link_path_separated_by_underscores.

  2. If describing a link to a Drupal file, such as cron.php, use the notation:

  <strong class="drupal_base_cron_php">cron.php</strong>

  Place the path in a <strong> attribute, and give it a class of drupal_base_name_of_file

  3. If you are linking to additional information on the web, such as a Drupal.org handbook page, enter the link as normal. It is suggested that the last item in the "You can" be a link to the module project page, something like:

  file issues, read about known bugs, and download the latest version on the <a href="http://drupal.org/node/####">modulename project page</a>.

• If the module requires access permissions to be set, provide a path to the access permissions page.
• If the module is a content type, provide a path to create content type.
• If the content module has a page that displays all content of that type, provide a path to that page.
• If the content type has configurable submission guidelines then a link should be provided to it. Ed-example is needed.