Difference between revisions of "Documentation Overview"
From GnuCash
(Differences between kinds of Documentation) |
(/* Improve Documentation /) |
||
| Line 2: | Line 2: | ||
;Targets: Where should '''users''' search first? | ;Targets: Where should '''users''' search first? | ||
:Where should '''contributors''' add information? | :Where should '''contributors''' add information? | ||
| + | [[Category:Documentation]][[Category:Documentation Development]] | ||
| − | ==Integrated Documents== | + | ==Existing Documentation== |
| + | ===Integrated Documents=== | ||
They are the content of our [{{GitURL}}/gnucash-docs GitHub repository gnucash-docs], are usually shipped together with the program and accessible by its Help menu. | They are the content of our [{{GitURL}}/gnucash-docs GitHub repository gnucash-docs], are usually shipped together with the program and accessible by its Help menu. | ||
:;Note: Some distributions split them in a separate package "gnucash-doc" or similar. Then users should install it to have easier access. | :;Note: Some distributions split them in a separate package "gnucash-doc" or similar. Then users should install it to have easier access. | ||
| Line 17: | Line 19: | ||
:;Target: Finally all important documentation should end here! | :;Target: Finally all important documentation should end here! | ||
| − | ==Online Documents== | + | ===Online Documents=== |
;Pros: Sometimes more recent. | ;Pros: Sometimes more recent. | ||
;Cons: Internet required. | ;Cons: Internet required. | ||
| − | ===Wiki=== | + | ====Wiki==== |
| − | + | ;Pros: Often more recent. | |
| + | ;Cons: Unreachable in CN because of the [{{URL:wp}}Great_Firewall Great Firewall]. | ||
| + | ;Content: | ||
:;Thematic pages: sometimes in several languages | :;Thematic pages: sometimes in several languages | ||
:;The [[FAQ]]: a catch all starting point. But if there are 2 or more questions about the same theme, the content should go into a dedicated page, leaving only links in the FAQ. | :;The [[FAQ]]: a catch all starting point. But if there are 2 or more questions about the same theme, the content should go into a dedicated page, leaving only links in the FAQ. | ||
| Line 28: | Line 32: | ||
;Contributors: Only MediaWiki Markup required, for examples see [[Wiki_Tips]]. | ;Contributors: Only MediaWiki Markup required, for examples see [[Wiki_Tips]]. | ||
| − | ===Website=== | + | ====Website==== |
The current use is mainly | The current use is mainly | ||
:[{{WebURL}}/news.phtml announcements] and | :[{{WebURL}}/news.phtml announcements] and | ||
| Line 40: | Line 44: | ||
:;Targets: mostly marketing | :;Targets: mostly marketing | ||
| − | ===Lists=== | + | ====Lists==== |
Archives of the [[Mailing Lists]] and [[IRC]] logs are available, but usually only a short time relevant and harder to search. | Archives of the [[Mailing Lists]] and [[IRC]] logs are available, but usually only a short time relevant and harder to search. | ||
| − | ==Other== | + | ===Other=== |
;Social Media: see Website header | ;Social Media: see Website header | ||
:;Contributors: volunteering? | :;Contributors: volunteering? | ||
| − | [ | + | |
| + | =Improve Documentation= | ||
| + | <pre> | ||
| + | Code ------------+ | ||
| + | Lists ---> Wiki -+-> Docs | ||
| + | : | | ||
| + | LANG +-> Website | ||
| + | </pre> | ||
| + | ;Coders: should ideally also update the docs — or at least instead of closing fixed bugs assign them to component Documentation. | ||
| + | ;Users: should add frequently asked questions from the lists to wiki:FAQ. | ||
| + | ;Expirienced Users: should structure the content of FAQ sections into thematic wiki pages. To void redundancy, replace the content in the FAQ by links | ||
| + | ;Advanced Users: should integrate the thematic wiki pages into the official documentation. | ||
| + | ;Multilingual Users: Translate documents | ||
| + | :;Code and Website: offer PO file based translation. It can be easiest improved using [{{URL:wl}} WebLate]. | ||
| + | :;Wiki: is possible. Improvements of the process needs coordination with [[User:Warlord]]. | ||
| + | :;Others: require knowledge of the documenter tools. | ||
Revision as of 22:18, 31 May 2021
The GnuCash Project contains several kinds of Documentation. This pages explains the differences.
- Targets
- Where should users search first?
- Where should contributors add information?
Contents
Existing Documentation
Integrated Documents
They are the content of our GitHub repository gnucash-docs, are usually shipped together with the program and accessible by its Help menu.
- Note
- Some distributions split them in a separate package "gnucash-doc" or similar. Then users should install it to have easier access.
- Pros
- Accessible without internet.
- Cons
- Sometimes partially outdated.
The Gnucash-docs consist of two parts:
- gnucash-help
- is the reference manual describing the GUI elements and their relations.
- gnucash-guide
- contains the tutorial and the concepts guide. Here you can
- learn our terminology and
- the steps to resolve specific tasks.
- Contributors
-
- Requirement
- Dokbook knowledge
- Target
- Finally all important documentation should end here!
Online Documents
- Pros
- Sometimes more recent.
- Cons
- Internet required.
Wiki
- Pros
- Often more recent.
- Cons
- Unreachable in CN because of the Great Firewall.
- Content
-
- Thematic pages
- sometimes in several languages
- The FAQ
- a catch all starting point. But if there are 2 or more questions about the same theme, the content should go into a dedicated page, leaving only links in the FAQ.
- You can either Special:Search or navigate by Special:Categories.
- Contributors
- Only MediaWiki Markup required, for examples see Wiki_Tips.
Website
The current use is mainly
- [[[:Template:WebURL]]/news.phtml announcements] and
- (linking) downloads of
- [[[:Template:WebURL]]/download.phtml program] or
- [[[:Template:WebURL]]/docs.phtml documentation].
- [[[:Template:WebURL]]/features.phtml features] shows still GnuCash 2.
- [[[:Template:WebURL]]/sizing.phtml sizing] is a Y2K hommage.
- Contributors
-
- Requirements
- PHP+HTML
- Targets
- mostly marketing
Lists
Archives of the Mailing Lists and IRC logs are available, but usually only a short time relevant and harder to search.
Other
- Social Media
- see Website header
- Contributors
- volunteering?
Improve Documentation
Code ------------+
Lists ---> Wiki -+-> Docs
: |
LANG +-> Website
- Coders
- should ideally also update the docs — or at least instead of closing fixed bugs assign them to component Documentation.
- Users
- should add frequently asked questions from the lists to wiki:FAQ.
- Expirienced Users
- should structure the content of FAQ sections into thematic wiki pages. To void redundancy, replace the content in the FAQ by links
- Advanced Users
- should integrate the thematic wiki pages into the official documentation.
- Multilingual Users
- Translate documents
- Code and Website
- offer PO file based translation. It can be easiest improved using WebLate.
- Wiki
- is possible. Improvements of the process needs coordination with User:Warlord.
- Others
- require knowledge of the documenter tools.
