RMF/Contributor Guide/Documentation Guideline

This page describes where, and in what form, documentation for the RMF project should be recorded.

RMF Documentation

The RMF documentation is maintained in the Eclipse Wiki. There are some special sections which are automatically included to an Eclipse Help plugin which is delivered with the RMF release. More information can be found in the #Wiki to Eclipse Help Generator chapter. Furthermore, some parts of the documentation are maintained in ReqIF files. This will allow us to specify nontrivial features (i.e. those too big for a Bugzilla entry) using ProR. These can then be linked to from the Wiki. The procedure is described in the #ReqIF to HTML Generator chapter.

Wiki to Eclipse Help Generator

The following chapter are currently included automatically to the Eclipse Help plugin:

• RMF/User_Guide/Tutorial
• RMF/User Guide/Reference
• RMF/User Guide/Presentations
• RMF/FAQ

This means, whenever you are editing something in these chapters, the changes are also included in the next RMF build (e.g. nightly build).

Here is a screenshot displaying the structure in the Eclipse Help:

The responsible plugin is org.eclipse.rmf.pror.reqif10.help.ui.

ReqIF to HTML Generator

We just started to implement a script that takes .reqif files from the git repository and generates public HTML files with an unchanging URL. This will allow us to specify nontrivial features (i.e. those too big for a Bugzilla entry) using ProR. These can then be linked to from the Wiki. To give you an idea, we moved the importer feature description from the Wiki to a reqif model:

RMF/Roadmap#i12.05_.28May_2012.29

The .reqif files reside at org.eclipse.rmf.git/dump/reqif

The generated html files can be found after a build at org.eclipse.rmf.git/dump/html. You can find all generated html files so far also by accessing the last successful RMF build: https://hudson.eclipse.org/hudson/job/rmf-nightly/lastSuccessfulBuild/artifact/dump/html

In order to create a link to a specific html file, just link to it. Here is an example link: https://hudson.eclipse.org/hudson/job/rmf-nightly/lastSuccessfulBuild/artifact/dump/html/RMF_Importer_rmf-6a6dbb0c-6091-485c-8a6b-8b0c0ef81f17.html

Any changes on that file will eventually lead to an updated HTML file. This is, for now, a proof of concept with a few caveats:

• The renderer currently ignores advanced formatting
• Not all presentations can be used
• Problems with the .reqif files break the build
• We should decide on a better location (dump sounds dumpy) - should we leave them in the developer repository, or would a separate repository be more appropriate?

The responsible plugin is org.eclipse.rmf.pror.reqif10.genhtml.

Problem Description

Specification

Mind Map

Requirements

The initial requirements for the RMF documentation:

• The following classes of documentation exist:
  • Developer Documentation for developers using RMF
  • User Documentation for ProR
  • Committer Documentation for developers contributing to RMF

Requirements Documentation in general

• The documentation shall support cross referencing
• The documentation shall be printable
• The old ProR documentation (from pror.org) shall be recycled and adapted
• Where it makes sense, the documentation should use RMF itself ("eat your own dogfood")
  • It is possible to manage ReqIF files in git and to generate HTML on checkin by Jenkins. Obviously, that does not make sense for all documentation.
• Where it makes sense, documentation should be generated
  • i.e. for developer and committer documentation, it makes sense to document in JavaDoc and to provide links to the generated JavaDoc HTML

Requirements for User Documentation

• A user should be able to easily contribute to the user documentation (not limited to Committers)
  • Possible Solution: The documentation resides in the Eclipse wiki
• The user documentation shall be made available as Eclipse help
• The user documentation shall contain a tutorial for ProR
• The user documentation shall contain an FAQ
• The user documentation shall contain a reference section
• The user documentation shall contain documentation for RMF presentation plugins
• The user documentation shall have a directory of external presentation plugins

Requirements for Developer Documentation

• The developer documentation shall contain a tutorial for creating presentation plugins
• The developer documentation shall contain an FAQ
• The developer documentation shall contain an architecture overview
• The developer documentation shall contain an API overview

Requirements for Committer Documentation

• The committer documentation shall contain a roadmap
• The committer documentation shall contain a process guideline
  • Structure of git, use of gitflow, use of bugzilla, etc.
• The committer documentation shall contain coding guidelines
  • To ensure code quality: Commenting, unit testing, etc.
• The committer documentation shall contain a guideline for contributing as a non-committer
  • E.g. via Gerrit
• The committer documentation shall contain a guideline for contributing to the RMF documentation (e.g. Grammer and writing style, style of chapters, etc.)

Developer Documentation

Developer documentation resides in the Wiki. Important: Always include the RMF category at the end of all RMF pages:

[[Category:RMF]]

End User Documentation

User documentation currently resides at pror.org. It will be migrated eventually, although it is not clear yet where to. Please propose suggestions to the rmf-dev mailing list.

Solution

1. Evaluate Eclipse Help Generator (e.g. Mylin Wikitext) (4h)
2. Provide structure required by previous item (0h)
3. Checkpoint - evaluation of work so far
4. Migration of existing content
5. Complete Documentation (yeah... right)

Independently of the previous:

1. Implmenent JavaDoc generation as part of CI (2h)
2. Implmeent reqif HTML generation as part of CI