Drupalcon Prague Doc Sprint

We encourage users to post events happening in the community to the community events group on https://www.drupal.org.
LeeHunter's picture
Posted by LeeHunter on September 18, 2013 at 4:44pm
Start: 
2013-09-27 09:00 - 18:00 Europe/Prague
Organizers: 
LeeHunter
ifrik
Event type: 
Sprint

https://prague2013.drupal.org/sprints

Another Drupalcon and another Docs Sprint! Join us in Panorama Hall or on IRC and help get the docs ready for Drupal 8.

Some of the work to be done includes trying out existing (or patched) hook_help, and checking for:

  • Clarity
  • Accuracy (Making sure the text matches what's on the admin screens)
  • Completeness (Covers most or all of what the module does)
  • Style
  • Working links

An issue that lists all the D8 modules is here: https://drupal.org/node/1908570

And there are lots of other D8 docs issues to work on: https://drupal.org/project/issues/search/documentation?text=&assigned=&s...

If you need help getting started, ifrik (clara on IRC) will be available on site and LeeHunter will be on IRC (although he might start a little later due to the time difference).

Categories: ,

Comments

Documentation sprint Resources

Posted by ifrik on September 25, 2013 at 8:00am
ifrik's picture

and here are my links, notes and resources ...

Resources

What to check?

  • Is the writing clear and understandable? If not, rephrase it. Sometimes it needs just moving sentences around, or deleting unnecessary words.
  • Is the text accurate? Does it match what you see on the admin pages? Some of the headings and tab headers have changed since D7.
  • Is the text reasonably complete? Does it cover most or all what the module does, but without bloating it up with too many details that could better go onto the d.o. pages?
  • Does it match our standard format for help? The Help text standard gives an example. Other default phrases are listed below.
  • Do all the links work?
  • Are the links written in the new default URL format?

Template

Shortened version of the Help text standard

/**
* Implements hook_help().
*/
function editor_help($path, $arg) {
  switch ($path) {
    case 'admin/help#foo':
      $output = '';
      $output .= '<h3>' . t('About') . '</h3>';
      $output .= '<p>' . t('The Foo module [allows somebody to do something][does something]. For more information, see <a href="!foo-documentation">the online documentation for the Foo module</a>.', array('!foo-documentation' => 'http://drupal.org/documentation/modules/foo/')) . '</p>';
      $output .= '<h3>' . t('Uses') . '</h3>';
      $output .= '<dl>';
      $output .= '<dt>' . t('Doing something') . '</dt>';
      $output .= '<dd>' . t('To do this, visit  the <a href="!intertal">Internal Foo</a> page or the <a href="!external">External</a> page.', array('!internal' => url('path/to/page'), '!external' => 'https://example.com')) . '</dd>';
      $output .= '</dl>';
      return $output;

Standard wording

  • Modules that provide fields for fieldable entities:
    The Foo module allows you to create fields that contain [something]. See the <a href="!field">Field module help</a> and the <a href="!field_ui">Field UI help</a> pages for general information on fields and how to create and manage them.
  • Link to d.o. pages:
    For more information, see the online documentation for the Link module.
  • Un-countable nouns: text, email
  • Don't use abbrevations: 'For example' instead of 'e.g.'

Site builder and Documentation WG member

Documentation

Group categories

Event type

Post type

Topic

Group notifications

This group offers an RSS feed. Or subscribe to these personalized, sitewide feeds:

Hot content this week

See all hot content.