Michael Schumacher ha scritto:

Hi all,

I'm frequently pointing users to the manual from mailing lists, irc, usenet and forum posts. Sometimes, I discover entries in the manual that are

- wrong (fortunately, this doesn't happen frequently) - incomplete (a bit more frequently) - not easily reachable from a related page

An example for the last item is the reason for this mail - I wanted to point someone at the blend tool docs and discovered that there is no link from http://docs.gimp.org/en/gimp-tool-blend.html to an explanation of gradients or the gradient editor.... a site map that does show the links between pages could be useful for checking this.

The way to fix this would be to create a bug report (and either provide a patch or to wait if someone else does it). But I wonder if anything can be done to verify the docs in a more organized way.

You can. The GIMP manual was added to the Gnome bugzilla not so long ago (the module is called GIMP-manual) and there are 12 open bugs as of now. Another way to report such things is to drop a line in the wiki (http://wiki.gimp.org/gimp/GimpDocsWip). If you find some time please file your findings (especially wrong and incomplete entries).

"Review" is probably the most obvious answer for the first two issues, the question is "What is the best way to do it?".

I think that we are suffering from resource shortage, the manual is now a beast of 500+ printed pages, it is translated into 12 languages (to different degree of completeness) and a complete and thorough review requires more eyes and hands. Maybe a more organized process is required? I am currently reviewing the italian translation that is almost completed and I will do my best to spot and correct some english parts as well.

Regards,
Michael

Cheers

Hi Michael,

Am 11.04.2007 um 15:33 schrieb Michael Schumacher:

Hi all,

I'm frequently pointing users to the manual from mailing lists, irc, usenet and forum posts. Sometimes, I discover entries in the manual that are

The GIMP community con really be proud of your engagement for all kind of GIMP users! So, having the manual as a reliable source is how we can support you.

- wrong (fortunately, this doesn't happen frequently)

yeah, sometimes we are plain wrong (or simply outdated)

- incomplete (a bit more frequently)

over 600 pages and still don't cover everything...

- not easily reachable from a related page

Can you explain this please? There is a toc in front and an index in the end of the manual (in over a dozen languages each). Additionally there is a possibility to do a fulltext search online at docs.gimp.org as well as the possibility to download the whole manual as pdf and do a fulltext search offline.

An example for the last item is the reason for this mail - I wanted to point someone at the blend tool docs and discovered that there is no link from http://docs.gimp.org/en/gimp-tool-blend.html to an explanation of gradients or the gradient editor....

OK, this is obviously a flaw. And it is one that can be fixed easily.

a site map that does show the links between pages could be useful for checking this.

um, a site map is a structured list (more a tree) like the toc is?! Could you be a bit more specific about your needs please?

The way to fix this would be to create a bug report (and either provide a patch or to wait if someone else does it).

Thats what bug filing is good for. We even have our own product by now!

But I wonder if anything can be done to verify the docs in a more organized way.

There is, but this takes time. I guess the next big thing will be an review for GIMP2.4, but starting this makes no sense until we have reached a feature and GUI freeze in the 2.3 line.

"Review" is probably the most obvious answer for the first two issues, the question is "What is the best way to do it?".

Right now it is _really_ important for me/us to learn about the weaknesses of the manual, so if you file a bug about flaws _and_ let us know about your ideas to enhance the manual is the best you can do.

Greetings, lexA

Regards,
Michael