Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
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: | ||
| − | + | * The following classes of documentation exist: | |
| − | * The documentation | + | ** '''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 | * 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 04:47, 9 May 2012
This page describes where, and in what form, documentation for the RMF project should be recorded.
Contents
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 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.