[GNC] Porting the Tutorial & Concepts Guide to ReadTheDocs.org

[David Cousens]

Adrien,

The wiki is currently an entry point for your Group 2 people to provide
input and it is a route already in place to migrate documentation from the
wiki to the formal docs. I am in the process of migrating the trading
accounts documentation although what was in the wiki was not much more than
a note. Even the wiki requires you to learn a basic language although it is
much like AsciiDoc.

I ended up doing documentation after i had made a few minor code changes and
realized no-one was likely to know about them unless I incorporated it into
the documentation and in doing so realized a lot of other things in the same
area were not very completely documented. I still make mistakes in the
process of the documentation that Frank and others will attest to. I had no
knowledge of DocBooks when I started a couple of years ago and I'm still
learning.

I am not sure that AsciiDoc is necessarily any less of a committment than
learning DocBook although some of its basic concepts are fairly simple. OK
once you know it it's no problem. Having to use complete tags in XML is a
bit of a pain but I find myself cutting and pasting common structural
elements rather than typing them in all the time. A nice editor with tag
completion would certainly not go astray. I tried one but it doesn't pick up
on the gnucash DTD as it is not in the same directory as the guide or help
sources in the current source structure.

AsciiDoc can actually generate formal DocBook output and it is meant to be
semantically equivalent so it should be possible to use it as a development
tool however it won't know about the GnuCash specific structures and how
they link to each other.  It has some similarities (and differences) to the
wiki markup language.

If you are going to contribute to the docs I think it is unavoiable having
to invest time in the toolchain, whatever it happens to be. Most of the
toolchain is pretty transparent once you have configured a build directory
its just
make check
make html (or pdf or epub or mobi or all of them)
and then view what you have written once you have located the newly written
output.

I don't think one can avoid the github repository either or the process of
submitting PR's to it from a personal repository in an environment when
multiple people on multiple continents in different time zones are
contributing changes and those changes have to be reviewed and organized to
match and be consistent with code releases etc etc.  I am still a git and
github novice as John and Frank will attest but there are tools that make
that a lot easier too (Gitkraken has made my lack of skill with raw
git/github look a lot less clumsy).  

Likewise using the Bugzilla for flagging documentation changes. A user can
always  submit the documentation changes they want to suggest as raw text in
Bugzilla. 

I am not opposed in principle to changing but I do think we need to ensure
we will all be better off after any change.

David







-----
David Cousens
--
Sent from: http://gnucash.1415818.n4.nabble.com/GnuCash-User-f1415819.html