Documentation Validation procedure old
From Gcube Wiki
This page provides information about the procedure that must be followed for the validation of the documentation content and the status of this procedure . This procedure is essential for maintaining high quality documentation in the Administrator's[1], the Developer's[2] and the User's[3] guide. The actors in the procedure are the authors of each section in the aforementioned guides, and the reviewers, which are recipients of the information provided in the content for which they are responsible.
Validation Procedure
Wikidoc Validation
Procedure
Each review process workflow consists of four stages
- Whenever a documentation section becomes eligible for review, the Review Process Status should be changed from orange (pending) to blue (eligible for review). The Documentation Editor will then open a ticket to the assigned reviewer of the aforementioned section and place a link to that ticket in the Related Ticket column.
- The assigned reviewer of the section performs the review, classifying this section into APPROVED - MINOR CHANGES - MAJOR CHANGES, and sets one of these three options into the Content Status column. This classification will give an overall estimation for the situation of the given section and will help each author understand how extensive the changes in his content should be. Reviewers should also provide more detailed comments to authors, in order to inform them about parts that have not clear meaning or must be described in more detail, parts that should be extended to broaden their scope and include more information and missing parts. During this first stage of the review process, the Initial Comments column of the Review Process Status field has yellow color (in progress). This stage finishes when the reviewer reassigns the ticket to the author (or the person responsible for the corresponding subsystem if the section is written by more than one authors), to provide him with the detailed comments of his review. The reviewer then changes the Initial Comments column of the Review Process Status field to green (accomplished) and the Address Comments column to yellow (in progress).
- The author/maintainer(s) of the section must perform the changes needed to address the initial comments of the reviewer. When this stage is completed the latter changes the Address Comments column of the Review Process Status field to green (accomplished) and the Approval column to yellow (in progress).
- The reviewer of a specific section must check that the changes performed by the author, addressed his comments. Additional comments can be provided to the author by the reviewer, through the open ticket, in order to help the author address the initial comments. When this stage is completed the reviewer must change the Approval column of the Review Process Status field to green (accomplished), place APPROVED into the Content Status column and close the open ticket.
Reasons to Review
A new review for a specific section is indicated by inserting a new line, in one of the tables below, beneath the lines that correspond to previous reviews for this section. The reason for a new review can be:
- An extended change in the contents of a section(if this change involves only a specific subsection of this section then the name of this subsection is placed into the SubSection column). In this case the new line should be inserted by the author of the section, who is also responsible for informing the corresponding reviewer about the initiation of a new review procedure for this section.
- A minor release closure. In this case the responsible for initiating the procedure is the Documentation Editor.
- Some other reason that demands validation of some parts in the three guides.
The reason must be placed into the Reason to review column.
Deadlines
The Due Date depends on the reason for which the review is performed, being 5 weeks in case of a Major Review and 4 weeks in case of a minor release closure. The Initial Comments should be provided to the author by the reviewer in about one weeks' time after the initial ticket creation by the Documentation Editor. The documentation update should be performed in 3 weeks' time in case of a Major Review or other reason and in 2 weeks' time in case of a minor release closure. The final review should be performed in an additional one weeks' time. Each subsequent review/update cycle, if any, should be performed in one weeks' time for each action. In this case, the Due date should be updated accordingly by the reviewer to 2 weeks past the previous date.
If a review process fails to be completed within the Due Date, the reviewer must place the red color (expired) to the appropriate stage in the Review Process Status field. The reviewer can change the Content Status column during the third stage of a review process(i.e. he may decide that a section that needed MAJOR CHANGES, still needs some minor changes after the second stage). If the reviewer considers a section as APPROVED after the first stage, then this review process for this section, is considered to be completed without any actions taken by the author.
Distribution Validation
Description
Distribution validation is an additional documentation validation procedure defined from the distribution point of view instead of the documentation point of view. Its purpose is to complement the Wikidoc Validation procedure by
- Making it easier to identify software lacking documentation
- Facilitating access to documentation by correcting documentation-related issues in the distribution
- Eliminating all possibilities of confusion by ensuring that all documentation links point to the project's current Wiki
The documentation issues are identified by the Documentation Editor and fall into three categories
- Components lacking documentation. This category in turn includes
- Components for which documentation exists, but don't include a link to that documentation. The expected action for such components is simply to include the link to the existing documentation.
- Components which contain documentation links pointing to empty documentation pages or sections. The expected action for such components is to produce the required documentation.
- Components which neither contain documentation links nor there exists documentation for them. The expected action for such components is both to produce the required documentation and to include the link the latter.
- Components containing documentation links pointing to the old Wiki. This is a fairly common distribution issue which can generate confusion, especially when the correct page is updated often. This category includes
- Components for which a corresponding documentation page or section already exists in the current Wiki. The expected action for such components is simply to update the documentation link included in the component.
- Components for which a corresponding documentation page or section does not exist in the current Wiki. The expected actions for such components is to produce the required documentation and to update the documentation link included in the component.
- Components containing problematic documentation links. This category includes all components with documentation link issues which cannot be classified into the previous two categories. In this case, a description of the identified issue is included.
Procedure
The procedure workflow consists of three stages
- The party in charge of the procedure (either the Documentation Editor, or an associate of them) opens a ticket (Type: defect, Defect Category: Documentation) for the issue to the Developer responsible for the component, describing the issue category. The former then changes the Ticket Creation column of the Issue Resolution Status field to green (accomplished) and the Resolution in HEAD column to yellow (in progress).
- Once the issue is resolved and the corresponding HEAD configuration is updated in ETICS, the Developer updates the ticket in order to notify the party in charge of the procedure of the progress made. The latter then updates the Resolution in HEAD to green (accomplished) and the Component Release column to yellow (in progress). If the changes made do not require a component release, the latter also updates the Component Release to green and closes the ticket, signifying that the procedure was successfully completed.
- If the changes made require a component release and once the component is released, the Developer updates the ticket in order to notify the party in charge of the procedure and the latter updates the Component Release column to green and closes the ticket, signifying that the procedure was successfully completed.
n Note: The component validation procedure is designed to address mainly distribution-related issues and it is expected that there will be no major overlaps with the Wikidoc Validation procedure. However, if such overlaps occur, the author responsible for the documentation section under review is expected to add a link to the related ticket in order to make the monitoring of the two procedures more efficient as they run simultaneously.
Status of Wikidoc Validation
Developer's Guide
| Section | Subsection | Author | Reviewer | Reason to review | Due Date | Content Status | Related Ticket | Review Process Status | ||
|---|---|---|---|---|---|---|---|---|---|---|
| 1 | 2 | 3 | ||||||||
| Initial Comments | Address Comments | Approval | ||||||||
| 1. Introduction | All | Federico De Faveri, Pasquale Pagano | Major Review | |||||||
| 2. gCube Architecture | All | Leonardo Candela, Pasquale Pagano, Manuele Simi | Major Review | |||||||
| 3. Reference Model | All | Leonardo Candela, Manuele Simi | Manuele Simi, George Kakaletris | Major Review | #1567 | |||||
| 4.1 GCube Infrastructure Enabling Services | All | Manuele Simi | Manuele Simi, George Kakaletris | Major Review | #1568 | |||||
| 4.1.1 Information System | All | Lucio Lelii, Manuele Simi | Vassilis Veroios | Major Review | 31/05/2011 | #1437 | ||||
| IS-Cache | All | Vassilis Veroios | Panagiota Koltsida | Major Review | #1917 | |||||
| 4.1.2.1 Security Library | All | Major Review | ||||||||
| 4.1.3 VRE Management | All | Lucio Lelii, Kostas Liaskos, Fabio Simeoni, Manuele Simi, Daniele Strollo | Major Review | |||||||
| 4.1.4 Execution Engine | All | Giorgos Papanikos | Stefanos Tsaklas, Giota Koltsida | Major Review | #1673 | |||||
| 4.1.5 Workflow Engine | All | Gerasimos Farantatos, Giorgos Papanikos | Stefanos Tsaklas | Major Review | 16/05/2011 | #1466 | ||||
| 4.1.6 Messaging Infrastructure | All | Andrea Manzi | Gerasimos Farantatos | Major Review | 20/06/2011 | APPROVED | #1436 | |||
| 4.2 gCube Information Organisation Services (NEW) | All | Fabio Simeoni | Major Review | |||||||
| 4.2.1 Storage Manager | All | Federico De Faveri | Major Review | |||||||
| 4.2.2 Content Manager | All | Fabio Simeoni | Kostas Tsakalozos | Major Review | APPROVED | #1877 | ||||
| 4.2.3 Content Manager Library | All | Fabio Simeoni | Kostas Tsakalozos | Major Review | APPROVED | #1878 | ||||
| 4.2.4 gCube Document Model and gCube Model Library (2.0) (NEW) | All | Fabio Simeoni | Giota Koltsida | Major Review | APPROVED | #1870 | ||||
| 4.2.5.2 gDL 2.0 | All | Federico De Faveri, Fabio Simeoni | Giota Koltsida | Major Review | APPROVED | #1869 | ||||
| 4.2.6 View Manager | All | Fabio Simeoni | Kostas Tsakalozos | Major Review | MINOR CHANGES | #1879 | ||||
| 4.4 gCube Information Retrieval Services | All | Leonardo Candela | Major Review | |||||||
| 4.4.1 gCube ResultSet (gRS) | All | Kostas Tsakalozos | Major Review | |||||||
| 4.4.2 gCube ResultSet 2 (gRS2) | All | Gerasimos Farantatos, Giorgos Papanikos | Lucio Lelii | Major Review | 16/05/2011 | APPROVED | #1465 | |||
| 4.4.3 Search Framework | All | Vassilis Veroios | Major Review | |||||||
| 4.4.4 OpenSearch Framework | All | Gerasimos Farantatos | Major Review | |||||||
| 4.4.5 Index Management Framework | All | Vassilis Veroios | Major Review | |||||||
| 4.4.6 Data Transformation | All | Kostas Tsakalozos | Major Review | |||||||
| 4.4.7 Personalisation | All | Giota Koltsida | Rena Tsantouli | Major Review | 26/05/2011 | APPROVED | #1438 | |||
| 4.4.8 Distributed Information Retrieval Support Framework | All | Fabio Simeoni | Major Review | |||||||
| 4.4.8 gCube Ontology Management Service | All | Rena Tsantouli | Major Review | |||||||
| 4.5.1 Application Support Layer | All | Rena Tsantouli | Giota Koltsida | Major Review | #1871 | |||||
| Home Library | All | Federico De Faveri | Major Review | |||||||
| 4.5.2 gCube Portal Engine | All | Giota Koltsida | Massimiliano Assante | Major Review | 13/05/2011 | APPROVED | #1439 | |||
| 5.1.2. Profile Specification | All | Manuele Simi, Daniele Strollo | Major Review | |||||||
| 5.1.3. Service Archive Specification | All | Lucio Lelii | Major Review | |||||||
| 5.2.1. Developing gCube Portlets Guide | All | Massimiliano Assante | Giota Koltsida | Major Review | APPROVED | #1872 | ||||
| 5.2.2 GCube Widgets Library - General guidelines about Portlet StyleSheets | All | Massimiliano Assante | Giota Koltsida | Major Review | APPROVED | #1873 | ||||
| 5.2.3 GCube Portlets common icon set | All | Massimiliano Assante | Giota Koltsida | Major Review | APPROVED | #1874 | ||||
| 5.2.4 Inter Portlet Subscription/Notification Mechanism (Client side) | All | Massimiliano Assante | Giota Koltsida | Major Review | APPROVED | #1875 | ||||
| 5.2.5 Building your gCube Portlet in ETICS | All | Gabriele Giammatteo | Giota Koltsida | Major Review | APPROVED | #1876 | ||||
| 5.3.1. Security Model | All | Andrea Manzi | Major Review | #1964 | ||||||
| 5.3.2. Security Plugins Table | All | Major Review | ||||||||
| 5.3.3. How To Configure Service Security | All | Major Review | ||||||||
| 5.3.4. Common Security Troubleshooting | All | Major Review | ||||||||
| 5.3.5. How to use VOMS api library | All | Major Review | ||||||||
| 6. GCube Infrastructure Tools | All | Andrea Manzi | Major Review | |||||||
| 6.1 SAM Tools | All | Andrea Manzi | Major Review | |||||||
| 6.2 Resource Manager Client | All | Andrea Manzi | Major Review | |||||||
User's Guide
| Section | Subsection | Author | Reviewer | Reason to review | Due Date | Content Status | Related Ticket | Review Process Status | ||
|---|---|---|---|---|---|---|---|---|---|---|
| 1 | 2 | 3 | ||||||||
| Initial Comments | Address Comments | Approval | ||||||||
| 1 Introduction | All | Leonardo Candela, Pasquale Pagano | Major Review | #1900 | ||||||
| 2 Basic Concepts | All | Leonardo Candela, Pasquale Pagano | Anton Ellenbroek | Major Review | #1900 | |||||
| 3 Common Functionality | All | Massimiliano Assante, Federico De Faveri, Giota Koltsida | Major Review | #1903 | ||||||
| 3.1 Login to a VO/VRE | All | Massimiliano Assante | Major Review | #1902 | ||||||
| 3.2 Search | All | Giota Koltsida | Major Review | #1903 | ||||||
| 3.3 Result Browsing | All | Massimiliano Assante | Major Review | #1903 | ||||||
| 3.4 Annotations | All | Giota Koltsida | Major Review | #1903 | ||||||
| 3.5 Content Viewer | All | Giota Koltsida | Major Review | #1903 | ||||||
| 3.6 User Profile Management | All | Giota Koltsida | Major Review | #1903 | ||||||
| 3.7 Report Management | All | Massimiliano Assante | Major Review | #1903 | ||||||
| 3.8 Course Management | All | Gerasimos Farantatos | Major Review | #1903 | ||||||
| 3.9 Time Series | All | Federico De Faveri | Major Review | |||||||
| 3.10 AquaMaps : Species Distribution and Biodiversity Maps | All | Leonardo Candela | Major Review | |||||||
| Workspace | All | Federico De Faveri | Major Review | |||||||
| 4.1 Login to a portal instance and select a VRE | All | Giota Koltsida | Major Review | #1915 | ||||||
| 4.2 Perform a search and view the metadata of a record | All | Giota Koltsida | Major Review | #1915 | ||||||
| 4.3 Annotating Information Objects | All | Giota Koltsida | Major Review | #1915 | ||||||
| 4.4 Send a workspace area item to another user | All | Federico De Faveri | Major Review | #1915 | ||||||
| Ontology Editing Portlet | All | Rena Tsantouli | Major Review | |||||||
Administrator's Guide
| Section | Subsection | Author | Reviewer | Reason to review | Due Date | Content Status | Related Ticket | Review Process Status | ||
|---|---|---|---|---|---|---|---|---|---|---|
| 1 | 2 | 3 | ||||||||
| Initial Comments | Address Comments | Approval | ||||||||
| 1. Introduction | All | Leonardo Candela, Pasquale Pagano | Andrea Manzi | Major Review | #1954 | |||||
| 3. How to set up a gCube infrastructure | All | Manuele Simi | Andrea Manzi | Major Review | #1955 | |||||
| 4.1 gCube Hosting Node (gHN) Installation | All | Manuele Simi | Andrea Manzi | Major Review | #1559 | |||||
| 4.2 Adding Virtual Platforms to a gHN | All | Manuele Simi | Major Review | |||||||
| 5. Core Services Installation | All | Manuele Simi | Andrea Manzi | Major Review | #1956 | |||||
| 5.1 Information System Installation | All | Manuele Simi | Andrea Manzi | Major Review | #1671 | |||||
| 5.2 VRE Management Services Installation | All | Manuele Simi | Andrea Manzi | Major Review | #1672 | |||||
| 5.3 Dynamic Virtual Organization Support Service Installation | All | Andrea Manzi | Major Review | #1958 | ||||||
| 6. How to create a Virtual Organization | All | Manuele Simi | Major Review | Andrea Manzi | #1958 | |||||
| 6.1 Installing the Virtual Organization enabling services | All | Manuele Simi | Andrea Manzi | Major Review | #1958 | |||||
| 6.2 Configuring the Virtual Organization | All | Manuele Simi | Andrea Manzi | Major Review | #1958 | |||||
| 6.3 Verifying the Virtual Organization correctness | All | Manuele Simi | Andrea Manzi | Major Review | #1958 | |||||
| 6.4 VO gCube Resources | All | Manuele Simi | Andrea Manzi | Major Review | #1958 | |||||
| 6.5 Dynamic Services Deployment and Configuration | All | Manuele Simi | Andrea Manzi | Major Review | #1958 | |||||
| 6.6 Monitoring the Virtual Organization | All | Manuele Simi | Andrea Manzi | Major Review | #1960 | |||||
| 6.7 Managing the Virtual Organization | All | Manuele Simi | Andrea Manzi | Major Review | #1961 | |||||
| 6.8 Creating Indices at the VO Level | All | Vassilis Veroios | Andrea Manzi | Major Review | #1918 | |||||
| 7. How to create a Virtual Research Environment | All | Leonardo Candela, Pasquale Pagano | Andrea Manzi | Major Review | #1962 | |||||
| 7.1 Defining the Virtual Research Environment | All | Leonardo Candela, Pasquale Pagano | Andrea Manzi | Major Review | #1962 | |||||
| 7.2 Approving the Virtual Research Environment | All | Leonardo Candela, Pasquale Pagano | Andrea Manzi | Major Review | #1962 | |||||
| 7.3 Verifying the Virtual Research Environment correctness | All | Leonardo Candela, Pasquale Pagano | Andrea Manzi | Major Review | #1962 | |||||
| 7.4 Managing the Virtual Research Environment | All | Leonardo Candela, Pasquale Pagano | Andrea Manzi | Major Review | #1962 | |||||
| 8.1 New gCube Portal Installation (Liferay) | All | Massimiliano Assante, Giota Koltsida | Massimiliano Assante | Major Review | 16/05/2011 | #1467 | ||||
| 8.2 Authentication management with Certificates and https | All | Giulio Galiero, Kanchanna.ramasamybalraj | Major Review | |||||||
| 8.3 Portal Administration Functionality | All | Rena Tsantouli | Gerasimos Farantatos | Major Review | #1963 | |||||
| 8.3.1 Roles' Management | All | Giota Koltsida | Federico De Faveri | Major Review | MINOR CHANGES | #1668 | Two screenshots need to be changed. | |||
| 8.3.2 Users' Management | All | Giota Koltsida | Federico De Faveri | Major Review | APPROVED | #1669 | First screenshots need to be updated, blu text need to be removed. | |||
| 8.3.3 Profiles' Management | All | Giota Koltsida | Federico De Faveri | Major Review | APPROVED | #1670 | ||||
| 8.3.4 Information Space Editor | All | Federico De Faveri | Major Review | #1964 | ||||||
| 8.3.5 Resource Management | All | Fabio Sinibaldi | Major Review | |||||||
| 8.3.6 Content Import | All | Federico De Faveri | Major Review | |||||||
| 8.3.7 Index Management | All | Kostas Tsakalozos | Major Review | |||||||
| 8.3.8 IR Bootstrapper | All | Giota Koltsida | Vassilis Veroios | Major Review | #1702 | |||||
| 8.4 Monitoring System | All | Massimiliano Assante | Major Review | |||||||
| 9 Programmatic Administration Interface | All | Manuele Simi | Major Review | |||||||
| 12.1 Security Model | All | Andrea Manzi | Major Review | #1964 | ||||||
| 12.2 gHN Security Configuration | All | Andrea Manzi | Major Review | #1964 | ||||||
| 12.3 gHN Argus Configuration | All | Andrea Manzi | Major Review | #1964 | ||||||
| 12.4 Policy Definition Portlet | All | Andrea Manzi | Major Review | #1964 | ||||||
Status of Distribution Validation
Components Lacking Documentation
| Component | Related Ticket | Issue Resolution Status | |||
|---|---|---|---|---|---|
| 1 | 2 | 3 | |||
| Ticket Creation | Resolution in HEAD | Component Release | |||
| org.gcube.application-support-layer.application-support-layer-resourcemanagement | 1354 | Done | |||
| org.gcube.application-support-layer.application-support-layer-storagemanagement | 1355 | Done | |||
| org.gcube.application-support-layer.application-support-layer-voms | 1356 | Done | Discontinued | ||
| org.gcube.information-system.is-cache | 1357 | Done | |||
| org.gcube.metadata-management.mmlibrary | Discontinued | ||||
| org.gcube.portal.custom-portal-handler | 1358 | Done | Done | ||
| org.gcube.portlets-admin.collection-explorer | 1359 | Done | Done | ||
| org.gcube.portlets-admin.data-transformation-admin-portlet | 1360 | Done | Done | Done | |
| org.gcube.portlets-admin.taskmanager | 1361 | Done | |||
| org.gcube.portlets-admin.vre-deployer | 1362 | Done | Done | Done | |
| org.gcube.portlets-user.gcube-loggedin-portlet | 1363 | Done | |||
| org.gcube.portlets-user.html-proxy-portlet | 1364 | Done | |||
| org.gcube.portlets-user.scorm-packaging | 1365 | Done | |||
| org.gcube.portlets-user.session-library | 1366 | Done | |||
| org.gcube.portlets-user.workspace-portlet-lighttree | 1367 | Done | Link | Done | |
| org.gcube.vo-management.usermanagement-core | 1369 | Done | Link | Done | |
Components Containing Wikidoc Links Pointing to the Old Wiki
| Component | Old Wikidoc Link | Corrected Link | Related Ticket | Issue Resolution Status | ||
|---|---|---|---|---|---|---|
| 1 | 2 | 3 | ||||
| Ticket Creation | Resolution in HEAD | Component Release | ||||
| org.gcube.information-system.glite-bridge | Link | Link | 1369 | Done | Done | Done |
| org.gcube.information-system.glite-bridge-stubs | Link | Link | 1370 | Done | Done | Done |
| org.gcube.metadata-management.metadatamanager | Link | Discontinued | ||||
| org.gcube.metadata-management.metadatamanager-stubs | Link | Discontinued | ||||
| org.gcube.metadata-management.metadatamanager-testsuite | Link | Discontinued | ||||
| org.gcube.metadata-management.xmlindexer | Link | 1371 | Done | |||
| org.gcube.metadata-management.xmlindexer-stubs | Link | 1372 | Done | |||
| org.gcube.portlets-user.results-portlet | Link | Link | 1373 | Done | Done | Done |
| org.gcube.vo-management.authorization | Link | 1374 | Done | Discontinued | Discontinued | |
| org.gcube.vo-management.authorization-stubs | Link | 1375 | Done | Discontinued | Discontinued | |
| org.gcube.vo-management.authorization-testsuite | Link | 1376 | Done | Discontinued | Discontinued | |
| org.gcube.vo-management.delegation | Link | 1377 | Done | Discontinued | Discontinued | |
| org.gcube.vo-management.delegation-stubs | Link | 1378 | Done | Discontinued | Discontinued | |
| org.gcube.vo-management.delegation-testsuite | Link | 1379 | Done | Discontinued | Discontinued | |
| org.gcube.vo-management.voms-admin-stubs | Link | 1380 | Done | |||
| org.gcube.vo-management.voms-api | Link | 1381 | Done | |||
| org.gcube.vo-management.voms-api-testsuite | Link | 1382 | Done | Discontinued | Discontinued | |
Components Containing Problematic Wikidoc Links
| Component | Identified Issue | Problematic Link | Corrected Link | Related Ticket | Issue Resolution Status | ||
|---|---|---|---|---|---|---|---|
| 1 | 2 | 3 | |||||
| Ticket Creation | Resolution in HEAD | Component Release | |||||
| org.gcube.content-management.gcube-model-library | Incorrect Page URL | Link | Link | 1383 | Done | Done | Done |
| org.gcube.content-management.view-manager | Old CM Documentation | Link | 1384 | Done | |||
| org.gcube.portlets-user.geospatial-portlet | Irrelevant Documentation Section | Link | Link | 1385 | Done | Done | Done |
| org.gcube.portlets-user.report-generator-portlet | Irrelevant Documentation Section | Link | Link | 1386 | Done | Done | Done |
| org.gcube.portlets-user.result-presentation | Irrelevant Documentation Section | Link | 1387 | Done | |||
| org.gcube.portlets-user.search-portlet | Incorrect Section URL | Link | Link | 1388 | Done | Done | Done |
| org.gcube.portlets-user.template-generator | Irrelevant Documentation Section | Link | Link | 1389 | Done | Done | Done |
