[Digikam-users] Users manual?

[Tom Cloyd]

On 01/06/2010 12:28 AM, Gilles Caulier wrote:
> 2010/1/5 jdd<jdd at dodin.org>:
>    
>> Le 05/01/2010 22:39, Mark Greenwood a écrit :
>>
>>      
>>> say it again, it's a community. Users help each other.
>>>        
>> and I have to say that when I began to use digikam the manual was
>> horrible.
>>
>> Now it's online, but very good, with many images and details. A great
>> job done by I don't know how, but not by me :-(
>>      
>
> 60% by me, the rest Gerhard Kulzer and others contributor.
>
> The manual is not updated. It still to use 0.9.x screenshot.
>
> All manual is written in docbook format and can be exported to html,
> pdf, ps, txt etc... later.
>
> http://websvn.kde.org/trunk/extragear/graphics/doc/digikam/
>
> docbook is XML based format, not too complicated to understand. A lots
> of text are contents, the rest is formating.
>
> http://websvn.kde.org/trunk/extragear/graphics/doc/digikam/index.docbook?view=markup
>
> I will be happy to see new contributors working on that and updating
> THE BOOK, because it's a book about digiKam and photography.
>
> All screenshot are PNG files.
>
> My time to share with it is very reduced now : coding coding coding.
>
> But i can guide new contributor to manage this part. It's very simple
> to do if you know how to start.
>
> My best
>
> Gilles Caulier
> _______________________________________________
> Digikam-users mailing list
> Digikam-users at kde.org
> https://mail.kde.org/mailman/listinfo/digikam-users
>
>    
Gilles,

I greatly like the general direction you thinking is taking this part of 
the project.

Maybe (I don't know) it would be best to port the document to a better 
known platform - possibly mediawiki or something like that? Docbook is 
not know well outside of the professional/serious-amateur programming 
community, I think. It looks to me like there's a choice to be made:

1. Retain docbook format (which I for one do not know and not eager to 
have to learn - I just don't have any more free time to allocate), so 
that one can have a portable stand-alone document for packaging, etc.
2. Port document to easily managed web-only platform which employs 
readily understandable text entry functionality (some kind of embedded 
WYSIWYG text input tool), so that minimally computer literate folks who 
can think, write, and contribute could jump on board the contribution train.

If one opts for #2 (which I favor),

* I'd like to see the program reference the online document - this 
includes all context help widgets.
* I'd like the program to never offer help which can possibly end in 
some kind of "can't find it" message. An online document meets this 
criteria - except in the case of someone with limited or no web access. 
But, that problem could be addressed via a program option to specify 
referencing a local HTML version of the manual, frozen at the time the 
program code is frozen (so community updates of the manual don't mess 
things up).

Mediawiki DOES offer a book creation functionality which looks quite 
nice (but I haven't yet used it). Here's the appropriate page at 
Wikipedia - 
http://en.wikipedia.org/w/index.php?title=Special:Book&bookcmd=book_creator&referer=Posttraumatic+stress+disorder. 
At Wikipedia, the option to make this book is available in the left 
sidebar of every article page, in the "print/export" group of links.

One specifies the pages wanted in your book, then an HTML or PDF book 
with those pages is created and may be downloaded. So, users of the 
online mediawiki DigiKam User manual (community-developed with guidance 
from you or some other high level person) could make their own book of 
the manual OR have available a pre-made version of the whole manual, 
with new update offered cyclically. I don't know, but it's likely would 
be possible to write script for a link to produce an on-demand of a 
current online version of the manual.

This approach would [a] make standalone manuals easily available to 
those who want them, [b] produce an always-available web version which 
is continually being updated by interested users at all levels of 
competence, and [c] avoid the hassle of having to try to manage the 
package managers with their variable and often conflicting policies.

To me, this appears to solve a great many problem, including freeing you 
as much as possible to do what you do best. Those of us who cannot make 
code contributions can surely make documentation contributions. We all 
get happy fast!

For what it's worth,

Tom

-- 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<<  tc at tomcloyd.com>>  (email)
<<  TomCloyd.com>>  (website)
<<  sleightmind.wordpress.com>>  (mental health issues weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~