EMI 2 and EMI 3Documentation Review Process

1.1. Tools

A shared spreadsheet has been created to be able to track the results of the documentation review and generate statistics and reports afterwards.

Snapshot of the spreadsheet which is the same for both EMI 2 and EMI 3: Doc2ReviewSurvey.gif

1.2. Responsibilities

The different release tasks are assigned to the different members of the Documentation Team according to a responsibility matrix.

  • EMI 2 matrix [R2].
  • EMI 3 documentation review will be done by Jozef Cernak.

1.3. Review Process

  • Documentation is evaluated using the information available in the release tasks of the release tracker [R3].
  • For each release tasks associated to the products you are going to review do:
    • When task is "certified" or "ready for testbed", "deployed on tested" or "verified":
      • Check the Documentation field.
      • If the field is empty OR doesn't include all mandatory documents, put a comment like:
        Could you please update the documentation links so that the following 
        mandatory documents are provided and we can start reviewing them?
            * General Documentation
                  o Release Notes (in the task only)
                  o Functional description 
            * User Documentation
                  o User guide 
                  o Client Installation and Configuration 
            * System Administrator Documentation
                  o System Administrator Guide 
                  o Service Reference Card (Please, create a SRC in the EMI EMT 
        twiki: https://twiki.cern.ch/twiki/bin/view/EMI/EMTSrcTemplate#SrcLinks)
        If some of the mandatory documents are not applicable here, please, explain why.
        Please, check the Documentation Policy to know how to prepare the documents:
        https://twiki.cern.ch/twiki/bin/view/EMI/EMISa2DocumentationPolicy, bear in mind 
        that several documents can be grouped together in the same document.
      • If the Documentation field provides mandatory documents:
        • Fill in the shared spreadsheet and evaluate each mandatory document.
          • If the document is Rejected, open a documentation task explaining why you have rejected the document, as explained in How to manage Documentation Tasks [R4]. Please, prefix the summary with [EMI X] so that we can easily browse the Documentation tasks per EMI major release.
      • If the task progresses and some mandatory documents are still missing, open a documentation task reporting the missing mandatory document, as explained in How to manage Documentation Tasks [R4]. Please, prefix the summary with [EMI X] so that we can easily browse the Documentation tasks per EMI major release.
      • At the end of the review, add the following summary in the task:
        Documentation Review:
        - Release Notes: Accepted or NA or Missing (TASK #XXXX) or Rejected (TASK #XXXX)
        - Functional description: Accepted or NA or Missing (TASK #XXXX) or Rejected (TASK #XXXX)
        - User guide: Accepted or NA or Missing (TASK #XXXX) or Rejected (TASK #XXXX)
        - Client Installation and Configuration: Accepted or NA or Missing (TASK #XXXX) or Rejected (TASK #XXXX)
        - System Administrator Guide: Accepted or NA or Missing (TASK #XXXX) or Rejected (TASK #XXXX)
        - Service Reference Card: Accepted or NA or Missing (TASK #XXXX) or Rejected (TASK #XXXX)

When a mandatory document is missing or it has been rejected by the reviewer, please add the task number where this is being tracked.

The overall results of the review will be compiled and a general report will be prepared.

1.4. What to Evaluate

The following criteria, present in the shared spreadsheet, needs to be checked for each mandatory document:

  • First page:
    • Existence of EMI logo.
    • Updated Date.
  • Second page:
    • Existence of EMI funding acknowledgement text.
  • TOC/Existing template:
  • Remainer of the document:
    • Platform specific instructions: check those sections where you think platform specific instructions should be present, whether all supported platforms are clearly mentioned in the document.

1.5. References

Reference URL
R1 EMI 2 Documentation Review Shared Spreadsheet
R2 EMI 2 Documentation Review Responsibilities
R3 EMI Release tracker
R4 How to manage Documentation Tasks
R5 System Administration Guide TOC
R6 Service Reference Card Template
R7 EMI 3 Documentation Review Shared Spreadsheet

1.6. Logbook

v1.0 (In progress)

  • 26.04.2012: First version created.

Edit | Attach | Watch | Print version | History: r6 < r5 < r4 < r3 < r2 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r6 - 2013-01-18 - MariaALANDESPRADILLO
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    EMI All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2022 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