HelpWikiQualityAssurance

Differences between revisions 1 and 19 (spanning 18 versions)
Revision 1 as of 2006-07-13 15:00:30
Size: 1716
Editor: mailgate
Comment: creating page
Revision 19 as of 2007-08-21 15:05:29
Size: 5153
Editor: cluster-j
Comment: restructuring spec a bit, adding some further development of ideas
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
 * '''Contributors''': MatthewEast, MatthewNuzum, RobertSchumann  * '''Contributors''': MatthewEast, MatthewNuzum, ["Philbull"]
Line 13: Line 13:
The documentation wiki is increasingly important for the development of documentation and in the future might conceivably be the only place that documentation for the Ubuntu project develops. It is also freely editable by anyone. As a result, quality assurance and social control is of vital importance. It is also important that the user gets a good impression of how reliable a particular document is when reading it. Completion of this specification will allow us to present the [https://help.ubuntu.com official documentation] alongside community contributions.
Line 14: Line 16:

 * Jane is looking for information about how to install a program. She finds a page contributed by a community member, but has no way of telling how reliable it is.
 * Bill has found a document about using a program, but doesn't know whether it is valid for the version of Ubuntu that he is using.
 * Jamie comes across a document which contains some information which doesn't work on his machine, and wants to report it to somebody.
Line 17: Line 23:
The documentation wiki at https://help.ubuntu.com/community
Line 19: Line 27:
 * Establish some concrete categories of cleanup that different pages require. For example:
  1. Style - the page needs to be brought in line with the wiki's style guidelines for documentation
  1. Review - the page needs to be reviewed by the documentation team
  1. Update - the page needs to be updated to include information about the latest version of Ubuntu
  1. Formatting - the page needs to be better presented
  1. Expansion - the content on the page needs expanding
 1. '''Cleanup'''
  See discussion [http://thread.gmane.org/gmane.comp.web.wiki.moin.general/3975/focus=3975 on the MoinMoin mailing list]. A solution may be:
  * Establish some concrete categories of cleanup that different pages require. Not too many, but enough to encapsulate what we need. We can look at [http://en.wikipedia.org/wiki/Wikipedia:Cleanup_resources#Cleanup the different categories that Wikipedia uses] and learn from them.
  * Write a macro which responds to (something similar to) {{{[[Cleanup(tag)]]}}} where {{{tag}}} is one of the categories identified
  * The macro should automatically show a prominent box to the user at the top of the page which includes the reason that the page has been tagged with Cleanup.
  * We can then generate lists of pages which have been tagged with this macro by doing a {{{[[FullSearch]]}}} on the text used to call the macro.
 1. '''Version applicability'''
  * Make it clear to the user what version of Ubuntu a particular document applies to.
  * Write a simple macro which responds to something like {{{[[Version(5.10,6.06)]]}}}. The macro should show a box to the user at the top of the page which explains which versions the document applies to.
 1. '''Feedback'''
  * Make it easy for users to give feedback on the wiki. This can be done by:
   a. Expanding the use of talk pages and developing a comment box with which users can easily submit comments. The user should not have to create the talk page manually where it does not already exist.
   a. Include links in the standard page layout which encourage users to submit bugs or write to the documentation team.
Line 28: Line 43:
 * Write a macro which responds to (something similar to) the following code.{{{
[[Cleanup(style)]]
[[Cleanup(review)]]
[[Cleanup(update)]]
[[Cleanup(formatting)]]
[[Cleanup(expansion)]]}}}
 * The macro should show a box to the user at the top of the page which explains the reason that the page has been tagged with Cleanup, how to help and how to discuss the issue with the documentation team.
 * Make this macro easy to add to pages via a drop-down menu (not essential)

 1. '''Cleanup'''
  The proposed categories for cleanup are as follows:
   a. ''Style'' - this page needs to be brought in line with the wiki's style guidelines for documentation
   a. ''Review'' - this page needs to be reviewed for technical accuracy
   a. ''Update'' - this page needs to be updated to include information about the latest version of Ubuntu
   a. ''Unsupported'' - this page may contain information which is not supported by the Ubuntu developers and may damage your system.
   a. ''Formatting'' - this page needs some work to improve its formatting
   a. ''Expansion'' - the content on this page is too brief and needs expanding
  Some progress has been made on using the {{{Include}}} macro to do what we want by PhilBull, see ["Philbull/Test"].
 1. '''Version applicability'''
  A similar macro to that used under Cleanup should be developed to insert version applicability into the page.
 1. '''Feedback'''
  * The theme for the wiki will be updated so that at the foot of each page there is a link to the /talk page for each page. The talk page should be created automatically where it does not exist and should automatically contain the {{{[[PageComment2]]}}} macro, which would do nicely for inserting comments ([http://moinmoin.wikiwikiweb.de/MacroMarket/PageComment2 homepage]). This is easily done by forcing the new page to use a particular template, in a similar way that the New``Page macro currently works. However, this currently will result in the page being overwritten where it already exists. Upgrading to Moin 1.5 would avoid this problem (see http://moinmoin.wikiwikiweb.de/MoinMoinBugs/NewPageOverwritesExistingPage).
Line 39: Line 60:
=== Data preservation and migration ===
Line 45: Line 65:
Please feel free to add comments to the ["/talk"] page.

Summary

This spec aims at introducing features to the documentation wiki (https://help.ubuntu.com/community) to allow greater quality assurance and to inform users about the reliability of the pages they are reading.

Rationale

The documentation wiki is increasingly important for the development of documentation and in the future might conceivably be the only place that documentation for the Ubuntu project develops. It is also freely editable by anyone. As a result, quality assurance and social control is of vital importance. It is also important that the user gets a good impression of how reliable a particular document is when reading it. Completion of this specification will allow us to present the [https://help.ubuntu.com official documentation] alongside community contributions.

Use cases

  • Jane is looking for information about how to install a program. She finds a page contributed by a community member, but has no way of telling how reliable it is.
  • Bill has found a document about using a program, but doesn't know whether it is valid for the version of Ubuntu that he is using.
  • Jamie comes across a document which contains some information which doesn't work on his machine, and wants to report it to somebody.

Scope

The documentation wiki at https://help.ubuntu.com/community

Design

  1. Cleanup

    • See discussion [http://thread.gmane.org/gmane.comp.web.wiki.moin.general/3975/focus=3975 on the MoinMoin mailing list]. A solution may be:

    • Establish some concrete categories of cleanup that different pages require. Not too many, but enough to encapsulate what we need. We can look at [http://en.wikipedia.org/wiki/Wikipedia:Cleanup_resources#Cleanup the different categories that Wikipedia uses] and learn from them.

    • Write a macro which responds to (something similar to) [[Cleanup(tag)]] where tag is one of the categories identified

    • The macro should automatically show a prominent box to the user at the top of the page which includes the reason that the page has been tagged with Cleanup.
    • We can then generate lists of pages which have been tagged with this macro by doing a [[FullSearch]] on the text used to call the macro.

  2. Version applicability

    • Make it clear to the user what version of Ubuntu a particular document applies to.
    • Write a simple macro which responds to something like [[Version(5.10,6.06)]]. The macro should show a box to the user at the top of the page which explains which versions the document applies to.

  3. Feedback

    • Make it easy for users to give feedback on the wiki. This can be done by:
      1. Expanding the use of talk pages and developing a comment box with which users can easily submit comments. The user should not have to create the talk page manually where it does not already exist.
      2. Include links in the standard page layout which encourage users to submit bugs or write to the documentation team.

Implementation

  1. Cleanup

    • The proposed categories for cleanup are as follows:
      1. Style - this page needs to be brought in line with the wiki's style guidelines for documentation

      2. Review - this page needs to be reviewed for technical accuracy

      3. Update - this page needs to be updated to include information about the latest version of Ubuntu

      4. Unsupported - this page may contain information which is not supported by the Ubuntu developers and may damage your system.

      5. Formatting - this page needs some work to improve its formatting

      6. Expansion - the content on this page is too brief and needs expanding

      Some progress has been made on using the Include macro to do what we want by PhilBull, see ["Philbull/Test"].

  2. Version applicability

    • A similar macro to that used under Cleanup should be developed to insert version applicability into the page.
  3. Feedback

    • The theme for the wiki will be updated so that at the foot of each page there is a link to the /talk page for each page. The talk page should be created automatically where it does not exist and should automatically contain the [[PageComment2]] macro, which would do nicely for inserting comments ([http://moinmoin.wikiwikiweb.de/MacroMarket/PageComment2 homepage]). This is easily done by forcing the new page to use a particular template, in a similar way that the NewPage macro currently works. However, this currently will result in the page being overwritten where it already exists. Upgrading to Moin 1.5 would avoid this problem (see http://moinmoin.wikiwikiweb.de/MoinMoinBugs/NewPageOverwritesExistingPage).

Code

Unresolved issues

BoF agenda and discussion

Please feel free to add comments to the ["/talk"] page.


CategorySpec

HelpWikiQualityAssurance (last edited 2008-08-06 16:37:07 by localhost)