Difference between revisions of "Documentation Validation procedure"

From Gcube Wiki
Jump to: navigation, search
(Components Lacking Documentation)
(Components Containing Wikidoc Links Pointing to the Old Wiki)
Line 801: Line 801:
  
 
===Components Containing Wikidoc Links Pointing to the Old Wiki===
 
===Components Containing Wikidoc Links Pointing to the Old Wiki===
To be filled.
+
 
 +
{| border="1" cellpadding="4" cellspacing="0"
 +
! rowspan="3" width="600"|Component !! rowspan="3" width="100"| Old Wikidoc Link !! rowspan="3" width="100" | Corrected Link !! rowspan="3" width="100" | Related Ticket !! colspan="3"|Issue Resolution Status
 +
|-
 +
! width="30"|1 !! width="30"|2 !! width="30"|3
 +
|-
 +
! width="30"|Ticket Creation !! width="30"|Resolution in HEAD !! width="30"|Component Release
 +
|-
 +
| org.gcube.dvos.voms-admin-stubs || [https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/Virtual_Organisation_Management Link] || || || bgcolor="blue" | || bgcolor="white" | || bgcolor="white" |
 +
|-
 +
| org.gcube.spatial.data.gis-interface || [https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php Link] || || || bgcolor="blue" | || bgcolor="white" | || bgcolor="white" |
 +
|-
 +
| org.gcube.spatial.data.geonetwork || [https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php Link] || || || bgcolor="blue" | || bgcolor="white" | || bgcolor="white" |
 +
|-
 +
| org.gcube.search.rseprcache || [https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/GCube_ResultSet_%28gRS%29#ResultSet_Cache Link] || || || bgcolor="blue" | || bgcolor="white" | || bgcolor="white" |
 +
|-
 +
| org.gcube.common.geoserverinterface || [https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php Link] || || || bgcolor="blue" | || bgcolor="white" | || bgcolor="white" |
 +
|}
  
 
===Components Containing Problematic Wikidoc Links===
 
===Components Containing Problematic Wikidoc Links===

Revision as of 13:23, 14 March 2013

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

  1. 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.
  2. 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).
  3. 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).
  4. 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

  1. 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).
  2. 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.
  3. 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 Major Review
2. gCube Architecture All Major Review
3. Reference Model All Major Review
4.1 GCube Infrastructure Enabling Services All Major Review
4.1.1 Information System All Major Review
IS-Cache All Major Review
4.1.2.1 Security Library All Major Review
4.1.3 VRE Management All Major Review
4.1.4 Execution Engine All Major Review
4.1.5 Workflow Engine All Major Review
4.1.6 Messaging Infrastructure All Major Review
4.1.7 Utility and Common Libraries All Major Review
4.1.7.1 Common-utils-encryption All Major Review
4.2 gCube Information Organisation Services All Major Review
4.2.1 Storage Manager All Major Review
4.2.2 Storage Manager (OLD) All Major Review
4.2.3 Content Manager All Major Review
4.2.4 Content Manager Library All Major Review
4.2.5 gCube Document Model and gCube Model Library All Major Review
4.2.6 gCube Document Library All Major Review
4.2.7 View Manager All Major Review
4.4 gCube Information Retrieval Services All Major Review
4.4.1 gCube ResultSet (gRS) All Major Review
4.4.2 gCube ResultSet 2 (gRS2) All Major Review
4.4.3 gRS2 Broker All Major Review
4.4.4 Search Framework (LEGACY) All Major Review
4.4.5 Search 2 Framework (NEW) All Major Review
4.4.6 OpenSearch Framework All Major Review
4.4.7 Index Management Framework All Major Review
4.4.8 Data Transformation All Major Review
4.4.9 Personalisation All Major Review
4.4.10 Distributed Information Retrieval Support Framework All Major Review
4.4.11 gCube Ontology Management Service All Major Review
4.5 Application Support Layer All Major Review
4.5.1 gCube GeoExplorer Portlet: A web interface for performing discovery of layers in a distributed GeoServer network All Major Review
4.6 gCube Data Consumption Facilities All Major Review
4.6.1 Ecological Modeling: Features for Analyzing Biological Phenomena and Species All Major Review
4.6.2 Environment Explorer: Features for Retrieving environmental data associated to a set of coordinates All Major Review
4.6.3 Geo Spatial Data Processing: Features for processing geo-spatial data All Major Review
4.7 gCube Data Transfer Facilities All Major Review
4.7.1 Data Transfer Agent All Major Review
4.7.2 Data Transfer Common components All Major Review
4.7.3 Data Transfer Scheduler All Major Review
4.8 gCube Data Assessment, Harmonization and Certification Facilities All Major Review
4.8.1 Time Series Management and Analysis All Major Review
4.9.1 gCube SDMX Statistical Data Dissemination System All Major Review
4.10 gCube Presentation Services All Major Review
4.10.1 Application Support Layer All Major Review
Home Library All Major Review
4.10.2 gCube Portal Engine All Major Review
4.10.3 ASL HTTP Front End All Major Review
4.10.4 Social Networking Library All Major Review
4.11 gCube Infrastructure Tools All Major Review
4.11.1 SAM Tools All Major Review
4.11.2 Resource Manager Client All Major Review
4.12 INSPIRE Community Applications All Major Review
4.13 DRIVER Community Applications All Major Review
5.1.2. Profile Specification All Major Review
5.1.3. Software Archive Specification All Major Review
5.2.1. Developing gCube Portlets Guide All Major Review
5.2.1.1 Create a new Mavenized gCube GWT Portlet Guide (NEW) All Major Review
5.2.2 Adding a Quick tour guide to your portlet All Major Review
5.2.3 Publish App News in User Feeds (Social Portal) All Major Review
5.2.4 GCube Widgets Library - General guidelines about Portlet StyleSheets All Major Review
5.2.5 GCube Portlets common icon set All Major Review
5.2.6 Inter Portlet Subscription/Notification Mechanism (Client side) All Major Review
5.2.7 Building your gCube Portlet in ETICS All Major Review
5.3.1. Security Model All Major Review
Security Plugins Table All Major Review
5.3.2 How To Configure Service Security All Major Review
5.3.3 Common Security Troubleshooting All Major Review
5.3.4 How to use VOMS api library All Major Review
6. GCube Infrastructure Tools All Major Review
6.1 SAM Tools All Major Review
6.2 Resource Manager Client All 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 Major Review #1900
2 Basic Concepts All Major Review #1900
3 Common Functionality All Major Review #1903
3.1 Workspace Environment All Major Review #1902
3.2 Login to a VO/VRE All Major Review #1902
3.3 Search All Major Review #1903
3.3.1 Select Collections All Major Review #1903
3.3.2 Search All Major Review #1903
3.3.3 Quick & Google Search All Major Review #1903
3.3.4 Geospatial Search All Major Review #1903
3.4 Result Browsing All Major Review #1903
3.4.1 Common Browsing Activities All Major Review #1903
3.4.2 The Basket All Major Review #1903
3.5 Annotations All Major Review #1903
3.6 Content Viewer All Major Review #1903
3.7 User Profile Management All Major Review #1903
User Profile Editing All Major Review #1903
3.8 Report Management All Major Review #1903
3.8.1 Template Creation All Major Review #1903
3.8.2 Report Generation All Major Review #1903
3.9 Course Management All Major Review #1903
3.10 Document Workflows All Major Review #1903
3.10.1 Workflow Editor : Create and Manage workflow templates All Major Review #1903
3.10.2 Document Workflow Manager : Create and Manage document workflows All Major Review #1903
3.10.3 My Document Workflows : Edit and View your document workflows All Major Review #1903
3.11 Time Series All Major Review
3.12 AquaMaps : Species Distribution and Biodiversity Maps All Major Review
3.12.1 Species Explorer All Major Review
3.12.2 Data Management Facility All Major Review
3.13 GeoExplorer : a visualization portlet for geo-spatial data All Major Review #1903
3.14 Web Application Management All Major Review #1903
3.15 WAR Management All Major Review #1903
3.16 Scheduler Portlet All Major Review #1903
Workspace All Major Review
4 Usage Scenarios All Major Review #1915
4.1 Login to a portal instance and select a VRE All Major Review #1915
4.2 Perform a search and view the metadata of a record All Major Review #1915
4.3 Annotating Information Objects All Major Review #1915
4.4 Send a workspace area item to another user All Major Review #1915
4.5 Acces workspace from Desktop All Major Review #1915
Ontology Editing Portlet All 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 Major Review
1.1 Intended Readership All Major Review
1.2 Purpose All Major Review
1.3 Related Documents All Major Review
1.4 Problem Reporting All Major Review
2 gCube Overview All Major Review
3. How to set up a gCube infrastructure All Major Review
4. Monitoring a gCube infrastructure with Nagios All Major Review
5.1 gCube Hosting Node (gHN) Installation All Major Review
5.2 Adding Virtual Platforms to a gHN All Major Review
5.2.1 Adding the Tomcat Virtual Platform to a gHN All Major Review
5.3 Security Configuration All Major Review
5.4 Security Plugins Table All Major Review
6. Core Services Installation All Major Review
6.1 Information System Installation All Major Review
6.2 VRE Management Services Installation All Major Review
6.3 Argus Configuration All Major Review
6.4 Usage-Tracker Installation All Major Review
7. How to create a Virtual Organization All Major Review
7.1 Installing the Virtual Organization enabling services All Major Review
7.2 Configuring the Virtual Organization All Major Review
7.3 Verifying the Virtual Organization correctness All Major Review
7.4 VO Resources All Manuele Simi Major Review
7.5 VO Services Deployment and Configuration All Major Review
7.6 Monitoring the Virtual Organization All Major Review
7.7 Managing the Virtual Organization All Major Review
7.8 Creating Indices at the VO Level All Major Review
7.9 Runtime Resource Management All Major Review
8. How to create a Virtual Research Environment All Major Review
8.1 Defining the Virtual Research Environment All Major Review
8.2 Approving the Virtual Research Environment All Major Review
8.3 Verifying the Virtual Research Environment correctness All Major Review
8.4 Managing the Virtual Research Environment All Major Review
8.4.1 Creating the Virtual Research Environment Layout All Major Review
8.4.2 Editing the Virtual Research Environment Information Space All Major Review
8.4.3 Managing Virtual Research Environment Users All Major Review
8.4.4 Monitoring the Virtual Research Environment through the Information System All Major Review
9 Third Party Software All Major Review
9.1 GDAL All Major Review
10 gCube Portal All Major Review
10.1 gCube Portal Installation All Major Review
10.2 Social Portal Extension Setup All Major Review
10.3 Configure Portal with LDAP All Major Review
10.4 Authentication management with Certificates and https All Major Review
10.5 Portal Administration Functionality All Major Review
10.5.1 Search Fields' Management All Major Review
10.5.2 Roles' Management All Major Review
10.5.3 Users' Management All Federico De Faveri Major Review
10.5.4 Profiles' Management All Major Review
10.5.5 Information Space Editor All Major Review
10.5.6 Resource Management All Major Review
10.5.7 Index Management All Major Review
10.5.8 IR Bootstrapper All Major Review
10.5.9 DataTransformationAdminPortlet All Major Review
10.5.10 Task Manager All Major Review
10.5.11 About inter-portlet referring All Major Review
10.5.12 Upload of new Software All Major Review
10.6 Monitoring System All Major Review
10.7 Jackrabbit Repository Installation & Configuration All Major Review
11 Programmatic Administration Interface All Major Review
14.1 GCube Security Model All Major Review
14.2 gHN Security Configuration All Major Review
14.3 Argus Configuration All Major Review
14.4 Policy Definition Portlet All Major Review

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.data.publishing.sdmx-publisher
org.gcube.portletsuser.sessionlibrary
org.gcube.application.authorextract
org.gcube.portlets.admin.ishealth-monitor-widget
org.gcube.common.eolusclient
org.gcube.common.hibernate-patched
org.gcube.contentmanagement.statisticsextractor
org.gcube.execution.reportingframeworklibrary
org.gcube.portlets.user.wsmail-widget
org.gcube.portlets.user.wsmail-widget
org.gcube.applicationsupportlayer.asl-http-infrastructure-login
org.gcube.execution.grsbridge
org.gcube.dbinterface.h2interface
org.gcube.applicationsupportlayer.aslresourcemanagement
org.gcube.contentmanagement.codelistmanager
org.gcube.data.harmonization.occurrence.occurrence-reconciliation
org.gcube.portlets.user.share-updates
org.gcube.applicationsupportlayer.asl-http-information-retrieval
org.gcube.execution.environmentproviderlibrary
org.gcube.contentmanagement.time-series-geotools
org.gcube.common.rapidminer-custom
org.gcube.portal.gcube-reporting-library
org.gcube.portal.social-networking-library
org.gcube.data.transfer.scheduler-portlet
org.gcube.messaging.accounting.portal.AccountingPortlet
org.gcube.portletsadmin.bdwmsuite-support-library
org.gcube.portlets.user.messages
org.gcube.search.search-client-library
org.gcube.execution.madgiknotificationhandlinglibrary
org.gcube.externalsoftware.gwt-ext-patched
org.gcube.execution.jmsenvironmentproviderlibrary
org.gcube.data.publishing.sdmx-datasource-client
org.gcube.common.exist-library
org.gcube.data.spd.species-products-discovery-service
org.gcube.data.spd.species-products-discovery-stubs
org.gcube.portlets.user.joinnew
org.gcube.commons.bitlet
org.gcube.applicationsupportlayer.aslvre
org.gcube.dbinterface.postgres
org.gcube.data.publishing.sdmx-registry-client
org.gcube.portlets.admin.resource-sweeper-widget
org.gcube.portletsuser.timeseriescharts
org.gcube.application.refextract
org.gcube.application.quantitative-properties-visualisation
org.gcube.execution.gcubeenvironmentproviderlibrary
org.gcube.application.refextract-script
org.gcube.contentmanagement.ecologicalmodelling
org.gcube.data.access.queueManager
org.gcube.contentmanagement.lexicalmatcher
org.gcube.execution.informationsystemlibrary
org.gcube.applicationsupportlayer.aslstoragemanagement
org.gcube.execution.urlresolutionlibrary
org.gcube.applicationsupportlayer.aslup
org.gcube.portlets.user.guided-tour-widget
org.gcube.portlets.user.workspace-application-handler
org.gcube.portlets.user.social-profile
org.gcube.execution.queueableexecutionengine
org.gcube.portlets.user.notifications
org.gcube.portletsuser.webapplicationmanagementportlet
org.gcube.common.dbinterface
org.gcube.contentmanagement.aquamapstransectgenerator
org.gcube.data.analysis.statistical-manager-service
org.gcube.data.analysis.statistical-manager-stubs
org.gcube.applicationsupportlayer.asl-http-content-access
org.gcube.informationsystem.iscache
org.gcube.portletsuser.d4science-reporting-library
org.gcube.applicationsupportlayer.asl-http-ore-provider
org.gcube.applicationsupportlayer.aslhttpinfrastructurelogin
org.gcube.contentmanagement.geo-utils-custom
org.gcube.data.publishing.software-upload-wizard
org.gcube.execution.notificationhandlinglibrary
org.gcube.applicationsupportlayer.aslsocial
org.gcube.execution.storagesystemlibrary
org.gcube.execution.workflowdtsadaptor
org.gcube.portlets.user.application-news-widget
org.gcube.application.ocropus
org.gcube.data.publishing.sdmx-registry-client-gcube
org.gcube.portal.notificationchecker
org.gcube.data.publishing.sdmx-datasource-common
org.gcube.portal.workspacetree
org.gcube.ontologymanagement.ontologymanagementservice
org.gcube.ontologymanagement.ontologymanagementservicestubs
org.gcube.portletsadmin.taskmanager
org.gcube.portlet.user.my-vres
org.gcube.common.csv4j
org.gcube.common.oaiharvester

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.dvos.voms-admin-stubs Link
org.gcube.spatial.data.gis-interface Link
org.gcube.spatial.data.geonetwork Link
org.gcube.search.rseprcache Link
org.gcube.common.geoserverinterface Link

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.application-gcube_search_android_application Incorrect Page URL Link
org.gcube.application-parallelindexing Incorrect Page URL Link
org.gcube.application-ocr Incorrect Page URL Link
org.gcube.application-datamanagementfacilityportlet Irrelevant Documentation Section Link
org.gcube.applicationsupportlayer-aslsearch Incorrect Page URL Link
org.gcube.applicationsupportlayer-asl_oai_ore Incorrect Page URL Link
org.gcube.applicationsupportlayer-asl_http_access_management Incorrect Page URL Link
org.gcube.applicationsupportlayer-aslcore Incorrect Page URL Link
org.gcube.applicationsupportlayer-aslcontent Incorrect Page URL Link
org.gcube.applicationsupportlayer-gcube_search_library Incorrect Page URL Link
org.gcube.common-tschartdatamodel Irrelevant Documentation Section Link
org.gcube.core-common-scope-maps Irrelevant Documentation Section Link
org.gcube.core-common-gcore-stubs Irrelevant Documentation Section Link