Drupal documentation: hook_help texts

I'll be doing the Documentation Sprint at DrupalCon Prague - focusing on the hook_help texts for Drupal 8 core modules.
Here's my notes...


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?

    Standard wording

    • Modules that provide fields for fieldable entities:
      The Foo module allows you to create fields that contain [something]. See the Field module help and the Field UI help 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.'