RMF/Contributor Guide/Documentation Guideline
This page describes where, and in what form, documentation for the RMF project should be recorded.
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
- 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 resides in the Wiki. Important: Always include the RMF category at the end of all RMF pages:
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.