Documentation Requirements
From GnuCash
Revision as of 20:52, 7 May 2020 by Codesmythe (talk | contribs)
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.
Target 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 profession 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. |
