Difference between revisions of "Documentation Requirements"
From GnuCash
Codesmythe (talk | contribs) |
Codesmythe (talk | contribs) (Accidentally dropped one of Fell's requirements.) |
||
| Line 95: | Line 95: | ||
|- | |- | ||
| MUST support linking (cross-references) inside and between documents. | | MUST support linking (cross-references) inside and between documents. | ||
| − | | A requirement for | + | | A requirement for professional documentation. |
| + | | | ||
| + | | | ||
| + | |- | ||
| + | | SHOULD be able to generate a List of Figures, Equations, etc. | ||
| + | | Also required for professional documentation. | ||
| | | | ||
| | | | ||
Revision as of 21:11, 7 May 2020
Purpose of this page is to collect the requirements, which must or should be met in case we want to change the documentation file format (source language). See Bug 722016 - We should change the Documentation file format.
Contents
Definitions
- Input Format
- The source format of the documentation files. Examples are DocBook, reStructuredText (reST) and Markdown. Contributors to the documention would be encouraged to use this format.
- Output Format
- Formats such as HTML, EPUB or MOBI that are produced by the documention flow.
- Documentation Flow
- An automated process that takes in documentation source files in a given input format and outputs processed files in various output formats.
- MUST, SHOULD, MAY
- As defined in RFC 2119.
Output Format Support
The documentation flow...
| Requirement | Justification | DocBook Support | reST support |
|---|---|---|---|
| MUST support Yelp. | Yelp is a primary HELP view for GNOME. | ||
| SHOULD support KHelpCenter. | KHelpCenter is a primary HELP viewer for KDE. | ||
| MUST support HTML output. | Required for presentation on GnuCash website. | ||
| MUST support EPUB output. | A popular format for tablets and e-readers. | ||
| SHOULD support CHM output. | |||
| MUST support PDF output. | Many people like to read long-form documentation in PDF. |
Documentation Tooling
All tools used in the documentation flow...
| Requirement | Justification | DocBook Support | reST support |
|---|---|---|---|
| MUST have several years of active development. | Project prefers to use proven tools. | ||
| MUST have a major community of users. | Better chance for support/bug fixes in larger projects. |
Input Format Requirements
The documentation input format...
| Requirement | Justification | DocBook Support | reST support |
|---|---|---|---|
| MUST support semantic markup. | More consistent appearance across output formats. | ||
| MUST support reasonable version control. | Allows maintainers to handle projects and diffs easily. | ||
| MUST support linking (cross-references) inside and between documents. | A requirement for professional documentation. | ||
| SHOULD be able to generate a List of Figures, Equations, etc. | Also required for professional documentation. | ||
| MUST support variable substitutions (also referred to as macros). | Easier maintenance. |
Internationalization
The documentation flow...
| Requirement | Justification | DocBook Support | reST support |
|---|---|---|---|
| MUST support internationalization. | GnuCash has a world-wide user base. | ||
| MUST support non-latin writing. | Many GnuCash users use non-latin languages. |
