GNOME Bugzilla – Bug 584041
a proper offline manual
Last modified: 2011-09-18 14:09:52 UTC
I think a nice, multilingual manual that pops up when you hit F1 and shows up with yelp would be nice, maybe in addition to the online version. http://www.pitivi.org/wiki/Manual is outdated, and I have the vague feeling that having a manual be "part of the trunk" (ie: versionned with git) would force us to keep it current with PiTiVi's development (adding a few descriptions here and there when a new feature is implemented).
Created attachment 135637 [details] Help file skeleton Here's a basic skeleton we can use to begin writing some accurate documentation. Now let's write real content :-)
Claude, I dare to ask, is there a gnomeish application out there intended to help writing documentation in a pleasurable way (ie: in the style of OpenOffice Writer)? I'd really like a wysiwyg approach that doesn't force me to see 20 tags per word :) what I mean is, I would really like to use a tool that makes me focus on writing the contents (well, and the images), instead of having heavy syntax in my way.
AFAIK there is no good wysiwyg free and open-source editor for DocBook content. I suggest you write the content in a Wiki and I'll gladly convert the content to DocBook in a second stage.
I started writing a few pages of the manual today. It is surprisingly fun to write documentation (so far)! So I'll tackle this job, I guess. So far, I have done the typesetting in OpenOffice Writer for now (and I daresay, it looks very pretty; I took some inspiration from professional software manuals). A question that obviously came to my mind: should that manual be licensed CCbySA, LGPL, FDL? Does it matter?
OK, just let me know when you have some content ready to be committed and I'll care for the DocBook formatting. There is also a possible DocBook export format in OOo, but I never tried it and it might be that there is more work to adapt it to GNOME style that with a manual process. And don't try to do too much fancy formatting in OOo, because it is not guaranteed to be reproducible in DocBook :-/ Regarding the license, read http://mail.gnome.org/archives/gnome-doc-list/2009-April/msg00057.html. CC-BY-SA 3.0 should be fine.
CC-BY-SA 3.0 is 100% fine by me... if it's fine for the doc writers too :)
Just for the record, a first version of my manual is here: http://jeff.ecchi.ca/blog/?p=897
I plan to "attempt" converting our existing manual (20+ pages long!) to Mallard, but if someone else would like to attempt it in my stead (or help me plan its structure), that would be quite appreciated as I don't have much time for it. The biggest challenge for me here is to switch from the hierarchical mental model to a "topic-oriented" model; the hardest part here is to make a *good* plan of the manual structure. The rest is basically copy-pasting and typesetting (gedit + mallard code snippets plugin makes this very easy). All in all, I don't really know yet whether or not the topic-oriented approach/paradigm would perfectly in our use case, until the manual would be (almost) complete... A mallard-based user manual also brings various headaches because you have to think about: - pitivi release versions - making that manual translateable - distributing it properly with the application and online
Let's just put up a short draft, that will allow us to do most of the integration work, get familiar with the format, translations and such. Just some quick topics like "Adding media to your project", "Moving a video clip along the timeline", then we'll iterate over and over.
I will setup the draft now, based on the current ODT. I think Mallard isn't so heavily topic-oriented. We can make it in a tutorial style anyway. See also http://sourceforge.net/mailarchive/forum.php?thread_name=1291525681.11161.8.camel%40kusanagi&forum_name=pitivi-pitivi
The draft is now available at Gitorious: http://gitorious.org/pitivi-help/pitivi-help
Implemented by commits ed4915e2c2e1 to 999025b8999