Module Maintenance Documentation

Steve Wirt's picture

If you maintain a module, there is potential for documentation to appear in at least three places  

  1. Project README.md file,
  2. hook_help in the module,  
  3. The project page on d.o.   

This multi-sourcing almost guarantees that one or more of them will soon be out of sync with the rest.

 I use a hook_help that uses the README.md as the help, and then I copy and paste that into the project description on d.o   Then whenever I change the README, I just copy and paste it to the description of the module on d.o   It is not completely foolproof, but it does help me spend less time keeping documentation in sync.

 

<?php
/** 
 * Implements hook_help(). 
 */ 
function MODULE_MACHINE_NAME_help($path, $arg) { 
  switch ($path) { 
    case 'admin/help#MODULE_MACHINE_NAME': 
     $output = file_get_contents(drupal_get_path('module', 'MODULE_MACHINE_NAME') . '/README.md');
     if (module_exists('markdown')) { 
       // Markdown can be used. 
       module_load_include('php', 'markdown', 'markdown'); 
       $output = Markdown($output); 
     } 
     else { 
      // Markdown is not available. 
      $output = ' <pre>' . $output . '</pre>';
    } 
   return $output; 
  } 
}
?>

If the site is using the Markdown filter, it uses it and outputs the markdown. If, not available, it just outputs the contents of the README which are still pretty readable, just not 'pretty' readable.

There is a movement on d.o to get the project page for modules to have the option to read directly from the README.md if desired. That would be awesome and save both time and reduce conflicting documentation. https://www.drupal.org/node/1674976

Examples of good README files on Drupal.org

Tags: 

Groups audience: 

- Private group -

Openness: 

Public - accessible to all