ROLE Documentation HowTo
In order to achieve uniform documentation for different classes of ROLE software components (i.e. libraries, Web service APIs and instances and widgets) this document provides detailed information on why and how to generate standardized documentation.
Challenge
One of the challenges of the ROLE project is to provide a large amount of info, that is provided by different experts, that is aimed at different groups of readers (developers, users) and that fits in a large information architecture. All widget documentation has to be easy to read and easy to maintain.
Policy
Without agreeing on a uniform standard that not will be possible. The ROLE Developer Team has selected the writing principles of Information Mapping to standardize all documentation. Based on that choice, templates are presented to all developers that write documentation. That way every writer produces the same kind of texts. In a longer-term perspective the Wiki approach taken for now will be replaced by automatic generation of documentation by software agents completing the respective templates during nightly builds.
Rationale
Information Mapping distinguishes between six reader’s questions and corresponding information types:
- “What’s for sure? What are the basics?” = fact
- “What do I have to abide to. What are the rules?” = policy
- “What do we mean by……?” = definition /abbreviation
- “What does it look like and what are the functions?” = structure (like: description of a toolbar, parts of a screen, list of library functions)
- “What happens in what order?” = process
- “What do I have to do?” = instruction
Each piece of documentation should answer these questions.
Templates
The ROLE Developer Team has therefore prepared templates for various types of software components, i.e. widgets, libraries, web service API’s, web service API instances. The structure and format of these templates adapt the six information types from Information Mapping.
Each template provides:
- a format for the document title which clearly indicates what information will follow in the document;
- a format for the paragraph titles which clearly indicates what information type will follow in the paragraph;
- the relevant subtitles - if necessary - under which to present the specific items of that information;
- default text that must be used.
Result
As a result of working with these templates, all documentation will be standardized and therefore easy to find, easy to read, and easy to maintain.
- Objective: This page describes how you contribute uniform documentation for your software created with ROLE technology.
- Control: The ROLE Development Team
- Valid from: 2011/03/02
- Revision: This document will be revised by the ROLE Development Team and documentation professionals at U&I Learning.
- Which Users: All members of the ROLE SF project should contribute to good documentation.
- Access: Any editor of the ROLE Wiki must be project member and additionally requires access rights for the Wiki.
- Handling Data: The ROLE Developer Community will take care of keeping documentation clean following the Wiki approach.
- Support: If you require, but do not have rights to edit the ROLE Wiki, please contact one of the admins of the ROLE SF project.
-
Who: Developers of ROLE software components who want to write ROLE-compliant documentation and integrate it into the overall ROLE documentation architecture using the SourceForge MediaWiki.
-
Attention:
- Please note that you must be project member and have sufficient access rights for editing the ROLE Wiki.
- Following the Wiki rationale, once a page is created it can neither be deleted nor renamed.
-
Steps:
0) Navigate to the SourceForge feature settings and grant yourself permissions (Grant Admin) for MediaWiki.
1) Create a new Wiki page for the respective documentation type by creating links in the respective section of the Main Page.
2) Link your page in the respective section of the [Developer Information Page](Developer Information).
3) Select the corresponding documentation template from section Templates & Examples below. If none of the specific templates fits your purposes, use the generic documentation template.
4) Copy Wiki source of template page and paste as source of new page.
5) Populate new page following the template structure and replacing template elements marked as [Template Element]. Use the provided examples as guidance. Do not add extra blocks or titles; try to fit the information into the templates.
- [ Template for Web Service API Documentation](Template for API description)
- [ Template for Library Documentation](Template for library)
- [ Template for Widget Developer Documentation](Template for widget devdoc)
- [ Template for Widget User Guide](Template for widget usrdoc)
- [ Template for Tool User Guide](Template for tool usrdoc) (see Widget User Guide example)
- [ Generic Documentation Template ](Template for generic doc)