User Documentation Content Checklist

Complete: 3


This is a checklist to be used to review the user documentation. It is based on the Annex B of the ISO Standard ISO/IEC 18019:2004(E), for which copyright is waived by ISO.

This checklist covers mainly the aspects of the documentation which are intended for the users of the application. It does not fully cover the reference documentation including the detailed description of the algorithms. This does not imply that such items can or should be ignored.

In the following table, the column "General" refers to the top level documentation, "Domain" to the different domains distinguished in the main page of the Offline Guide, and "Module" to a single software module or a collection of modules needed for a specific task. Some examples have been provided.

Use this list to check your documentation, there is no need to record the results of your check as a twiki page (do not modify this page), this list is meant to help you and not to bring more work.

Checklist item General Domain Module
1. General information
Is it clear what version of the software the documentation applies to?   example: WorkBookBTagging example: WorkBookBTagging
Is the information that users need when asking for support included? WorkBookHelp#DrupalHelpAtCern example: SWGuideVertexReco#Contacts  
2. Overview of the application
Is there an overview of the application? SWGuidePreface, WorkBookCMSSWFramework example: SWGuidePFTauID#Introduction  
- Does it explain what the application is for? WorkBookCMSSWFramework#InTro    
- Does it explain what application functions are available? WorkBookCMSSWFramework#ModA    
- Does it explain the structure of the application? SWGuidePreface#SwDom    
Is it clear what the application has done by default for standard RECO data?      
3. Overview of the documentation
Is there an overview of the documentation? SWGuidePrefaceDoc    
- Does it explain what documentation there is? SWGuidePrefaceDoc#DocSuite    
- Does is explain how to use the documentation? SWGuidePrefaceDoc#HowTo    
4. Task descriptions
Is there a task description for each task that user can perform? WorkBookCMSSWFramework#ModA    
Are there process descriptions that put the task in context? WorkBookMakeAnalysis    
5. Parameter sets
Are all parameters explained? - -  
Are all options (default and non-default) explained? - -  
Is the information about different types of parameters approriate? - -  
6. User interface elements
Are all the elements of the application's user interface explained?      
- Are the changes in configuration files and BuildFiles necessary to use the module explained?      
- Is the format of the output data of the module explained?   WorkBookBTagging#BtagData  
7. Application functions
Are all functions of the application described?      
8. Messages
Are messages explained, if necessary?      
9. Terms
Are all terms used either defined in the documentation or already familiar to users? WorkBookGlossary    
Is the terminology used consistently?      
10. Concepts
Are all the important concepts explained?      
11. Exploitation
Is there information on how to exploit the advanced features of the application?      
12. Questions and problems
Does the documentation answer questions that users may have? SWGuideTroubleShooting    
Is there any problem-solving information provided, if necessary? SWGuideTroubleShooting    
- Does it cover all the problems users may be expected to encounter?      
- Does it provide solutions?      
13. Examples
Are there example on how to access the standard RECO data?     example: WorkBookTrackAnalysis#EdAn
Are the examples suitable?      
Are the examples presented consistently?      
14. Captions
Are captions and callouts for illustrations, tables, photographs and other graphics effective and consistent?      

Review status

Reviewer/Editor and Date (copy from screen) Comments
KatiLassilaPerini - 22 Oct 2007 created page

Responsible: KatiLassilaPerini
Last reviewed by: Most recent reviewer

Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r3 - 2011-11-09 - EleanorRusack

    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback