After I gave a little "status of the gimp user manual" at GimpCon, i'll
want to do this for the others subscribed to the mailinglists as well.
What is written so far
---------------------
I created a little python script, which can be found in the gimp-help-2
module under docs. It compares the help ids[1] in the header file with
our help ids, found in the gimp-help.xml file for each language.
Therefore, following content is written approx.:
French: 77% done
German: 38% done
English: 80% done
Swedish: 9% done
The most of the French and English content was written by our french
writers, which are Julien Hardelin, Cédric Gémy, Raymond Ostertag and
Sébastien Barre. The status don't include plugins or any additional
content, like introductions.
Current issues and problems
---------------------------
Communication: we need a new mailinglist:
Well, the first thing i added to my list of issues was a
mailinglist, which is now available for everyone. Subscribe to:
gimp-docs@xxxxxxxxxxxxxxxxxxxxxx
or use the subscription page at:
https://lists.xcf.berkeley.edu/mailman/listinfo/gimp-docs
Thanks to yosh, sven and daniel egger to get the mailinglist
working. The archives are currently not working, so please be
patient. The server will get an upgrade and the archives will be
back soon.
Well, I hope that the communication with the new mailinglist will
encourage writers to communication their ideas and improvements
more than sending mails to everyone. The lack of communication is
the problem in every softwareproject, so please use the
mailinglist. Also, communciation between eachother prevents us
from inconsistencies in our documentation.
User who are testing and using our documentation are encouraged
as well to give us opinions and feedback about the manual. What
should be improved, what is not in the right place?
Lack of writers: we need an easier way to contribute:
I was thinking about an XML<->Wiki Roundtrip. People can write
the docs on a wiki and we're able to fetch the docs from the
wiki a put them nicely in shape. I tested the following
solutions, but the lack of time prevented me from writing up
my opinions.
1. DocBook Wiki[2] is a wiki for editing the content and is able
to display the Docbook online. It is possible to export the
content into other things like XML, HTML, PDF and much more. The
installation of this thingy is a bit cumbersome - I didn't get
it working with our manual. I gave up after a while messing
around with php and C++ code.
2. Another idea was a ReST[3] to Docbook XML roundtrip. I found
some alpha code which let us generate Docbook XML from a ReST
document and the other way around could do the MoinMoin Wiki. I
found a restructured text parser for the Wiki at [4], but didn't
tested it yet.
3. The third and last idea gave me Jimmac and TigerT at the
GimpCon. The Monodoc browser [5] display's on the one hand the
help itself, but let the people edit marked paragraphs and
therefore contribute to the project. I found this way the most
pleasant way to give contributors a chance to write
documentation. Users don't need to be connected to a server all
the time while writing documentation and can decide for
themselves, when they want to contribute.
Conclusion: Tools are nice, but we decided in short-term not to
concentrate to much on new tools, but more in trying more
contributors on the project. Kenneth Wimer from Novell/SuSE
offered help and I want to try to ask the gnome docwriters if
some of them want to join us. During the GUADEC, i talked to
Eugene O'Connor and other people from SUN about the Javahelp and
GNOME documentation. They provided me with some tips for a
better document structure and information about JavaHelp.
technical difficulties:
Well, we have some minor technical difficulties to generate
other formats than HTML. I managed to get some HTMLHelp out of
the XML sources working, but unfortunately without images. I run
into the same problem with the images, when I try to generate
a PDF/LaTeX document out of the XML sources. I'll invest some
more time into this, to get it working. I'm affraid, that some
of the pages are not well-formed, but i need to investigate this
first.
Screenshots:
The problem is, that GIMP's UI changes faster than we can
provide screenshots. My idea was an application which records
mouse movements and play's them afterwards to create screenshots
only once and then automatically. This idea has some major
problem when it comes to different positioning of menus and
other things, that i discarded the idea. Well, the guys from Sun
gave said, that we should provide screenshots only when they are
*really* necessary. Another problem with screenshots are the
dependencies to languages. I propose, that we shouldn't make
screenshots for every minor function or dialog, but describe the
functions or dialogs better.
To summarize: I want thank everyone who made this possible. After
writing most of the content, the content needs to be reviewed
consistently by everyone, especially the developers or people who know
the technology background. Users who are testing the manual might be
able to give us feedback, when they encounter errors, typos or not the
solution they are looking for. I hope, that I'm able to encourage more
people to help us and to have a nice user manual for everyone who is
using The GIMP.
[1] - gimp/app/widgets/gimphelp-ids.h
[2] - http://doc-book.sf.net/homepage/
[3] - http://docutils.sourceforge.net/
[4] - http://docutils.sourceforge.net/sandbox/mmgilbe/rst.py
[5] - http://www.mono-project.com
Greetings,
--
Roman Joost
www: http://www.romanofski.de
email: roman@xxxxxxxxxxx
Attachment:
signature.asc
Description: Digital signature
