Difference between revisions of "Documentation Overview"

From GnuCash
Jump to: navigation, search
(Differences between kinds of Documentation)
 
({{*Url}} -> {{URL:*}}; remove {{WebURL}}/sizing.phtml)
 
(2 intermediate revisions by 2 users not shown)
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==
−
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.
+
===Integrated Documents===
 +
They are the content of our [{{URL:git}}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.
 
;Pros: Accessible without internet.
 
;Pros: Accessible without internet.
 
;Cons: Sometimes partially outdated.
 
;Cons: Sometimes partially outdated.
 
The Gnucash-docs consist of two parts:
 
The Gnucash-docs consist of two parts:
−
:;gnucash-help:is the ''reference'' '''manual''' describing the GUI elements and their relations.
+
:;gnucash-manual:is the ''reference'' '''manual''' describing the GUI elements and their relations.
 
:;gnucash-guide: contains the '''tutorial''' and the ''concepts'' '''guide'''. Here you can
 
:;gnucash-guide: contains the '''tutorial''' and the ''concepts'' '''guide'''. Here you can
 
:#learn our terminology and
 
:#learn our terminology and
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====
−
The wiki has (often more recent)
+
;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
+
:[{{URL:www}}news.phtml announcements] and
 
: (linking) downloads of  
 
: (linking) downloads of  
−
::[{{WebURL}}/download.phtml program] or  
+
::[{{URL:www}}download.phtml program] or  
−
::[{{WebURL}}/docs.phtml documentation].
+
::[{{URL:www}}docs.phtml documentation].
−
:[{{WebURL}}/features.phtml features] shows still GnuCash 2.
+
:[{{URL:www}}features.phtml features] shows still GnuCash 2.
−
:[{{WebURL}}/sizing.phtml sizing] is a Y2K hommage.
 
 
;Contributors:  
 
;Contributors:  
 
:;Requirements:PHP+HTML
 
:;Requirements:PHP+HTML
 
:;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?
−
[[Category:Documentation]][[Category:Documentation Development]]
+
 
 +
=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.

Latest revision as of 14:19, 28 January 2024

The GnuCash Project contains several kinds of Documentation. This pages explains the differences.

Targets
Where should users search first?
Where should contributors add information?

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-manual
is the reference manual describing the GUI elements and their relations.
gnucash-guide
contains the tutorial and the concepts guide. Here you can
  1. learn our terminology and
  2. 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.
Contributors
Only MediaWiki Markup required, for examples see Wiki_Tips.

Website

The current use is mainly

announcements and
(linking) downloads of
program or
documentation.
features shows still GnuCash 2.
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.
Retrieved from "https://lists.gnucash.org/wiki/index.php?title=Documentation_Overview&oldid=22001"