GC Concept Guide Review and Wiki Pages

[Geert Janssens]

On Friday 15 October 2010, Thomas Bullock wrote:
> Hi Geert,
> 
> Thank you very much for your offer.  I too would like the information to be
>  available as soon as possible for general use by any interested persons.
> 
> Your putting it into a wiki would relieve me of a felt (on my side)
>  pressure to get this done.  It is a kind and appreciated offer.  I could
>  send you a copy of the file if you do not have one available.  Just tell
>  me.
> 
I still had the file around in my list messages. See 
http://wiki.gnucash.org/wiki/Documentation_Update_Instructions
for the result in wiki format.

For your reference, here's a very short summary of (most of) what I did:
* titles: surround with ==...==
* subtitles are created by surrounding them with one additional = per 
sublevel, so for example first subtitles will be ===...===
* numbered lists: replace "1. ", "2. ",... with "#"
* Add some bulleted lists by prepending the paragraphs with a "*"
* The # and * additions can be combined to get recursive lists.
* Note that lists are pretty picky about newlines. I removed most of them 
inside list paragraphs, otherwise numbering wouldn't add up.
* If you want a newline in a list item, begin the new line with the same 
combination of # and * as the previous line and add one ":"
* literal commands: surround with <pre>...</pre> (I also removed the quotes, 
they don't add value anymore with the <pre>...</pre> formatting)
* if you wish to indent a paragraph: prepend a colon (":") and make sure to 
remove all newlines from that paragraph.
* I removed the -------------- separators. The wiki sections and subsections 
markup is clear enough IMO.
* Note that the tables of contents is courtesy of Media wiki. I don't have to 
write it.

So far I have not made any changes to the text itself (apart from some 
spelling fixes), to make it easier for your to see how it got translated from 
plain text to wiki text.

I do have some remarks on what you have written also though:
Step 9: you don't have to list yourself as wanting to be notified explicitly 
when you reported the bug. In that case you will automatically be notified.

Notes on step 1: the events you describe here in case subversion is not 
installed are very distribution dependent. I think right now it only happens 
in very recent distro's (I know for Fedora it will only first appear in the 
new Fedora 14). Perhaps it's best to refer the reader to his/her distro 
specific application installation tools here to install subversion.

Notes on step 6: your explanation here is a bit misleading. "svn dif" doesn't 
contact the online repository. It uses the local working copy's metadata 
(which can be found in the hidden directory .svn) to determine what has 
changed since the last time you ran svn update. It is the svn update command 
that connect to the online repository to retrieve any new changes. So if you 
wish to view the changes you made compared to the status of the online 
repository, you should start with an svn update, and then run svn diff.

In the same section: you mention "diff -ur". As I mentioned in the mailing 
list as well, this won't work in subversion. Instead you should use "svn 
diff". ("diff -ur" requires additional parameters to run).

(Forgive me if my writing is a little compact. I should be in bed by now...)

<snip> 
> If I am not mistaken there is also duplication among the wiki pages which
>  should be rectified by making them more topical with cross-linking to the
>  main place treatment of a topic is given.
> 
Yes, there most likely is.

> Finally, I think we could have a feature that we could think of as a "site
>  map".  It would be a way for persons to search all aspects of
>  documentation: Guide, Help, FAQs.  Key words and aliases pointing to key
>  words constitute what I am thinking about.  Each key word is a link to a
>  page.  On that page are references to all places where the key word is
>  discussed, explained, used.  This certainly would need for all
>  documentation catch-up to be completed before it was attempted in earnest
>  fashion.  This last idea really is only a dream at this point.  Much, Much
>  more needs to be done before that is a realistic project.
> 
There are some helpful pages provided automatically by Media wiki, but they 
are fairly well hidden. If you click the "Special Pages" link on the left, you 
will get a list of pages Mediawiki itself maintains. Of particular interest 
here are the "All Pages" page and the "Categories" page. The first is simply 
an alphabetical list of all the pages in the wiki, the second a list of pages 
ordered by categories. Note that we have to setup the categories ourselves and 
there aren't many yet. But that could become a helpful tool to organize the 
wiki in the future.

> On a different topic while focused on documentation, I note that there are
>  no page numbers to use as references.  That may be explained by using XML
>  and HTML versions of the manuals.  Has anyone ever brought up the idea of
>  using numbered sections and segments within the chapters' numbering system
>  as a means of cross-referencing to related ideas within the manuals?   To
>  some extent this seems present, but not as extensively as I think it
>  might.  This idea, if adopted, should  be implemented only after the
>  duplication removal gets completed.
> 
There are some challenges here: some parts of our information are in a wiki, 
other parts are in plain html files and some parts are in the xml 
documentation. It will be interesting/challenging to come up with an indexing 
scheme that works for all these formats.

But as you say, that's a concern for somewhere in the future.


Geert