Sunday, January 08, 2012

#Wikipedia #help text is written all too often

A great help text is a help. Potential problems with help texts are legion:

  • they may not exist
  • they may not reflect the current functionality
  • they may not exist in translation
  • a translation may not reflect the latest original
  • it may be badly written
    • trying to be everything to everyone
    • high on terminology low on easy words
When the help text for the WebFonts extension was written, it was written for users. Documentation <grin> that is help text for developers or implementers </grin> already existed for quite some time. What we learned was that documentation did not help the people who use it.

What we produced solves some of the issues; 
  • the original text being written in a Wiki 
  • the documentation reflects the software that is in production
  • translations are created with the Translate extension; this allows for easy maintenance when changes occur
  • translations will be shown when they exist
Help texts exists in many places. It would be good when these text are merged into the central documentation. When the functionality of MediaWiki is supported centrally, it means that developers may take an interest as well. It becomes more obvious to include "stories" where a user understands the latest functionality after reading the help text...

When we agree that help text helps, if follows that help text needs to be up to date and accurate. Writing help text in a central place and translating the help text centrally should therefore be obvious.
Thanks,
      GerardM


No comments: