Documentation Overview

From GnuCash
Revision as of 22:18, 31 May 2021 by Fell (talk | contribs) (/* Improve Documentation /)
Jump to: navigation, search

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-help
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

[[[: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.