Jump to: navigation, search

Difference between revisions of "RMF/Contributor Guide/Documentation Guideline"

< RMF
(Requirements)
(Review of Requirements)
Line 11: Line 11:
 
The initial requirements for the RMF documentation:
 
The initial requirements for the RMF documentation:
  
* A user should be able to easily contribute to the documentation
+
* The following classes of documentation exist:
* The documentation shall exists as eclipse wiki
+
** '''Developer Documentation''' for developers using RMF
* The documentation shall existis as eclipse help plugin
+
** '''User Documentation''' for ProR
* The documentation shall contain a documentation for developer
+
** '''Committer Documentation''' for developers contributing to RMF
** The developer documentation shall contain a tutorial for creating presentation plugins
+
 
** The user documentation shall contain a FAQ
+
==== Requirements Documentation in general ====
** The developer documentation shall contain an architecture description
+
 
** The developer documentation shall support cross referencing
+
* The documentation shall support cross referencing
* The documentation shall contain a documentation for users
+
* The documentation shall be printable
** The user documentation shall contain a tutorial for ProR
+
** The user documentation shall contain a FAQ
+
** The user documentation shall contain a reference
+
** The user documentation shall support cross referencing
+
** The user documentation shall contain documentations for presentation plugins
+
* The documentation shall contain a roadmap
+
 
* The old ProR documentation (from pror.org) shall be recycled and adapted
 
* 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 may 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
  
 
== Developer Documentation ==
 
== Developer Documentation ==

Revision as of 03:47, 9 May 2012

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

Specification

Mind Map

Rmfdocu mindmap.png

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 may 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

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.