Difference between revisions of "Documentation Requirements"
From GnuCash
(First sketch) |
(→Other Criteria: Software Stability) |
||
| Line 14: | Line 14: | ||
;Links, indexes etc: We want to link inside and between documents, generate lists of Equations, Figures, ... | ;Links, indexes etc: We want to link inside and between documents, generate lists of Equations, Figures, ... | ||
;Variables/Macros: There a many things like URLs, appname, version, which we want to define at one place and use at several others. | ;Variables/Macros: There a many things like URLs, appname, version, which we want to define at one place and use at several others. | ||
| + | ;Software Stability: For a project, which evolved over 2 decades this is an important criterium. | ||
| + | :;First and last release: There should be several years of active development. If the last release was several years ago, it can be considered "dead". | ||
| + | :;Major reference projects: Do they have a major community of users? | ||
==Source Languages== | ==Source Languages== | ||
Revision as of 06:13, 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.
Target Languages by OS or Environment
- Linux
-
- Yelp
- Docbook, Mallard (Gnome only), DITA (experimental), man, info, and HTML
- KHelpcenter (alternative, currently unsupported)
- Docbook, man, info, and HTML
- Macos, WWW
- HTML
- Windows
- CHM (aging)
- Paper
- Several Mobiles, Tablets etc.
- EPub, Mobi
Other Criteria
- Semantic vs. descriptive Markup
- Descriptive languages use direct formatting like <bold>, <italic>, ... while in semantic languages you mark the meaning <guilabel>, <title>, ... and the rest is done by stylesheets like XSL, CSS, .... That will lead to a more consistent appearance.
- I18N
- We want also create translations in an easy way, also in non-latin writing, currently having japanese and cyrillic. How difficult is the conversion of existing translations?
- Links, indexes etc
- We want to link inside and between documents, generate lists of Equations, Figures, ...
- Variables/Macros
- There a many things like URLs, appname, version, which we want to define at one place and use at several others.
- Software Stability
- For a project, which evolved over 2 decades this is an important criterium.
- First and last release
- There should be several years of active development. If the last release was several years ago, it can be considered "dead".
- Major reference projects
- Do they have a major community of users?
Source Languages
- Docbook
- Semantic markup, all target languages supported by XSLTs or FOP.
