Documentation Writing guidelines

Description

Documentation plays a vital role in all large scale software systems. It is safe to say that the level of adoption of a given information system by a community, largely depends on the amount, detail and quality of documentation and relevant support material distributed together with the system. 

Roles

Two primary roles of people are engaged in the process of documentation production:

• The Documentation Editor
• The various Documentation Authors

Tools

The activity will utilize a different number of tools to handle all aspects of documentation management, including the collection of individual contributions, monitoring of documentation quality and completeness etc.

JavaDoc

Since Java is the primary programming language used for the development of gCube we use Sun’s JavaDoc tool to generate API. 
Guidelines have been defined that outline the common practices and procedures for the source code annotation with documentation information and the automatic generation of human readable reports with details regarding the code structure and comments on the code design, internal logic, algorithms used etc.

Checkstyle

Checkstyle is a development tool that helps programmers write Java code which adheres to a coding standard. Checkstyle is highly configurable and can be set, using XML notation, to support almost any coding standard. For example, these rules can enforce a specific coding style and most importantly detect the existence and completeness of the Java API documentation.

The following configuration file provides a good example and a starting point for checking and verification of gCube's source code API documentation:

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Puppy Crawl//DTD Check Configuration 1.2//EN"
"http://www.puppycrawl.com/dtds/configuration_1_2.dtd">

<module name="Checker">
<module name="TreeWalker">

<!-- Checks for Javadoc comments. -->
<!-- See http://checkstyle.sf.net/config_javadoc.html -->

<!-- Don't check for javadoc in getters/setters -->
<module name="JavadocMethod">
<property name="scope" value="public" />
<property name="allowMissingPropertyJavadoc" value="false"/>
</module>

<module name="JavadocType"/>

<!-- Don't check for comments in private variables -->
<module name="JavadocVariable">
<property name="scope" value="public"/>
</module>

<!-- Don't check the first sentence for missing periods etc. -->
<module name="JavadocStyle">
<property name="checkFirstSentence" value="false"/>
</module>
</module>
</module>

The above configuration ensures that all public classes, methods and fields are documentated. Especially for the public methods, it ensures that all input as well as return values are properly documented and described.

A Checkstyle Eclipse plug-in is also available. The plugin is used within an Eclipse workbench notifies the developer for problems via the task window and source code markers in the same way like compiler errors or warnings. More information regarding the Checkstyle Eclipse plug-in are available here http://eclipse-cs.sourceforge.net/#!/. You can easy install the Checkstyle Eclipse plug-in using the Eclipse Marketplace integrated in the Eclipse.

Help -> Eclipse Marketplace ... -> Search Checkstyle -> Click on Install button in Checkstyle Plugin-in (actually 6.9.0) by Lars Ködderitzsch.

Once installed select Window (from main menu) -> Preferences -> Checkstyle -> Click on New... button -> select External Configuration File in Type list box and import javadoc_checks.xml (containing the content shown above).

ETICS

The ETICS system will be utilized wherever possible to automate the production and verification process of documentation material. This is especially the case for API documentation. ETICS provides the appropriate hooks for producing documentation per component and sub-system configuration basis. ETICS can also automate the execution of profiling tools like checkstyle and produce completeness reports for D4Science source code.

Types of Documentation

gCube and gCore systems comprise a large set of documentation material targeted to all groups of people interested to use or extend them. Such groups are users from the D4Science-II communities, developers from the technical partners, developers outside the project consortium, reviewers interested in the developed technology etc. In order to satisfy the requirements of all these diverse communities, TSA3.3 activity will design, supervise, monitor and deliver a variety of different support material.

Global Documentation

The following three manuals are available:

• Administrator’s Guide – Provides detailed instructions for installing and initializing a gCube based VRE. Includes information about external dependencies, known issues, incompatibilities, specific platform details etc. Offers guidelines and documentation for the every day administration and upgrading of the deployed infrastructure.

• User’s Guide – Targeted towards the VRE end-users. Provides instructions for using the VRE's end-user facilities, especially concerning the available User Interfaces (web portals, portlets etc). The document should also reference known problems, limitations, problem reporting etc.

• Developer’s Guide – Documents technical-oriented information that will help developers further extend and exploit gCube and gCore systems' source code. The Developer’s manual will accompany the components' API documentation providing examples, good practices and common pitfalls when using them. The manual will also include whatever other implementation information was omitted in the source code documentation like for instance detailed references regarding the algorithms used and the theory applied for the component implementation. The document will target two classes of programmers:
  • Those who want to reuse the code – Programmers who will use gCube and gCore libraries to build their own tools, without need to have access to the source code.
  • Those who want to modify/extend the source code – Programmers who will use the platforms' source code to extend it, fix it and/or port it to different environments and applications domains.

Contributions for the above guides will be collected through the dedicated D4Science documentation wiki. Basis for the above will be the three respective manuals, legacy of DILIGENT project, which will be re-structured and extended to accommodate new information and expose the updated organization of gCube system.

Documentation shipped with the service/library package

Apart from the three main guides documenting the various aspects of gCube, a number of additional supporting files will be provided on per service/library basis. These files will be packaged and distributed together with the individual gCube and gCore components. In particular every package generated from ETICS is expected to contain the following informative files:

Each of this files must be placed in distro directory. The distro directory must be located in the root of the component.

You can find samples project with the needed files and skeleton at http://svn.research-infrastructures.eu/public/d4science/gcube/trunk/samples/

In particular, to create a new (or to check an existing one) smartgears service take a look at http://svn.research-infrastructures.eu/public/d4science/gcube/trunk/samples/sample-service-smartgears/

The README file

Serves as an introductory file for a given component. Provides a general overview of the characteristics and purpose of the component/subsystem, information about current version number, etc. Includes links to on-line documentation, project web sites, etc. 

The file also includes license information of all depending external software that the component/sub-system utilizes. This license information is extracted usually from the relevant file of the external software which most of the times includes specific clauses regarding how to reference the software.

Resources: http://www.mactech.com/articles/mactech/Vol.14/14.10/WritingAReadMeFile/index.html

The INSTALL file

Provides step by step instructions for installing/updating a given component. In case source code compilation is required, the file documents the configuration parameters and options, and the exact compilation steps. The file also references pre-requisites and dependencies for installation. Notice that for most gCube components this file should be considered optional for inclusion in the package. Indeed most of the components don't require manual installation, rather they depend on the centralize setup and deployment process orchestrated by a Virtual Research Environment (VRE) Manager.

The MAINTAINERS file

Lists the names and contact information of the developers responsible for specific parts of the component/subsystem. Helps identify responsible persons for each component and keeps track of their involvement in the development.

The LICENSE file

Provides detailed information about legal and licensing information pertaining the specific component/sub-system. Typically, in case a standard license is adopted, the LICENSE file contains just a copy of the license text. 

The CHANGELOG file

Keeps a journal of changes per component release. For each change the specific date is registered together with the reasons why the change was required, what sub-systems it effects and what potentially new features it introduces.

The procedure for changelog generation are described in Changelog Generation procedure page.

You can find more information regarding how to write a changelog at http://www.gnu.org/software/guile/changelogs/guile-changelogs_toc.html

API Documentation

API documentation guidelines define common practices and procedures for the annotation of the source code with documentation information and the automatic generation of human readable reports with details regarding the code structure and comments on the code design, internal logic, algorithms used etc. D4Science-II inherited most of the codebase developed during the DILIGENT and D4Science projects.

APIDOC Quality Assurance

One of the main considerations of gCube documentation activities, is to ensure the completeness and validity of API documentation. For this purposed a number of tools and procedures were employed to automate the verification process and monitor the progress of documentation development within the source code.

gCube will continue to work towards this direction in order to further improve the quality of the provided API documentation and also to ensure that this documentation will be maintained and extended in the subsequent code evolution and refactoring activities. For this purpose the checkstyle reports generated by ETICS will be made publicly available from the integration web site. These reports list the number of type of coding problems identified by the checkstyle rules, related to source code documentation. The Documentation Editor will have the responsibility, according to these reports, to generate a ranking of gCube components based on the total checkstyle errors. For the components with most errors (typically the top ten of the ranking table) a ticket will be opened in the Trac system, assigned to the component developer, with the task to correct the errors within the time between two reporting periods (typically one week). Tickets will be escalated depending on the time they remain unsolved and immediate action will be requested in cases a certain time limit has passed and the issue has remained unresolved.

Generic Guidelines

Since Java is the primary development language and platform in D4Science-II, the focus of this activity is to define procedures, tools and metrics to ensure the proper documentation of Java source code. By "proper" we mean documentation that can be parsed by the JavaDoc tool in order to generate human readable, and easily browsable reference material, but also complete enough in order this material to provide to the developer (either within or outside the project) non-trivial and useful information.

• All source code will be fully and properly documented by including both implementation and documentation comments. Implementation comments help developers who have access to the program’s source code, get a better insight to the inner implementation details. Programmers should also provide comprehensive documentation comments. These comments will be parsed by the JavaDoc tool in order to produce API documentation in HTML format.
• Sun’s “Code Conventions for the Java Programming Language”(http://java.sun.com/docs/codeconv/) will be followed regarding all styles of comments (implementation and documentation). Code Conventions define also appropriate variable, method and class naming policies that help produce a clear, self-documented code.

The following links provide essential reference material for writing documentation comments and using the javadoc tool:

• How to Write Doc Comments for the Javadoc Tool http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
• Requirements for writing Java API Specifications http://java.sun.com/j2se/javadoc/writingapispecs/index.html