GC Concept Guide Review and Wiki Pages

[Tom Bullock]

  On 10/15/2010 6:11 PM, Geert Janssens wrote:
> 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
Thanks very much for getting this into the wiki!  I also appreciate your 
short tutorial.  It will help me greatly as I try to act more 
independently.  All Much appreciated.

Tom