Am Die, 2003-08-19 um 12.19 schrieb Branko Collin:

What it comes down to, I guess, is that Daniel and Mel had a clear vision of the style of the new user documentation, but I somehow missed an explanation of that vision.

We started the project by sketching that vision in some files in the CVS module. I'm totally aggreeing that this not only needs updating but also to be placed in a more prominent location.

In an earlier thread, Daniel wrote: "we're not too happy with the content and the structure of the GUMP". I take it you meant the GIMP documentation?

GUM is the GIMP User Manual, so yes.

Why are you not too happy about the content and the structure?

It is too anarchic in its sructural layout and Mel didn't like the language at all. What we imagined was more like a modern manual (in both content and layout) leveraging all possibilities of modern tools without the fear to break anything existant (ie. the helpbrowser).

You also talked about granularity. Apparently, part of your idea of a GIMP documentation style is that help pages should be of similar size. Could you elaborate about that? Is that what you mean with granularity?

Granularity means that an author is not limited to squeeze all information about a certain topic into exactly the given structure, like a section; we had great troubles and some not so nice workarounds when being faced with large topics in the old version. This means that if something deserves a chapter it'll get a chapter without us having to worry about how this is transformed into a HTML file with a fixed name (because it's hardcoded into the GIMP) and referenced later on. This would be grnaularity on the source side.

Granularity on the output means exactly what you are referring to that the help chunks are all of the correct size. When the user requests help on blur the displayed information should resemble exactly that and not show all plugins with blur somewhere at the beginning. We already agreed to use HTML with anchors though, so this is something we probably cannot have easily since it's impossible to control the output granularity on case-by-case basis.

On 19 Aug 2003 14:01:12 +0200, Daniel Egger wrote:

Am Die, 2003-08-19 um 12.19 schrieb Branko Collin:

In an earlier thread, Daniel wrote: "we're not too happy with the content and the structure of the GUMP". I take it you meant the GIMP documentation?

GUM is the GIMP User Manual, so yes.

Why are you not too happy about the content and the structure?

It is too anarchic in its sructural layout and Mel didn't like the language at all. What we imagined was more like a modern manual (in both content and layout) leveraging all possibilities of modern tools without the fear to break anything existant (ie. the helpbrowser).

Now I am confused. I thought that we were talking about the online help system, not about the manual (GUM). It looks like you consider both of them to be the same thing. Is that right?

I thought that the online help would be something that is focused on explaining individual functions, i.e. one page for each feature. If I understood you correctly, you would like to merge these functional descriptions with something that is more like a tutorial.

For the "online help" part (the part that is called directly by the GIMP when the user invokes the context help), I do not see any need to allow anything else than a one-to-one mapping between the English version and the translations. That's why I did not understand some of your previous arguments. But if you want to merge this with a "tutorial" part, then it could make sense to allow a bit more freedom for the translators.

I think that too many people are confused now. Daniel, it would be nice if you start a new thread with a message explaining what are the plans for the new help system. I would like to know what are the goals, non-goals and the proposed implementation. Note that these goals do not necessarily have to be discussed: it would be fine for me if you said: "I am going to do it like that or not at all." But at least these ideas should be summarized in a clear way, to avoid future confusion about the plans for the help system.

-Raphaël

Am Die, 2003-08-19 um 14.25 schrieb Branko Collin:

Thank you for your elaborate answer. I do have some follow-up questions though.

No problem, whatever you want to know. :)

Assume for a second that I know nothing about 'modern manuals'. What is it about them that you like. What did Mel not like about the language of the old manual?

The old manual (or at least the content we had, I've never read the book, see below) was anachronistic, more like a reference than a fluent style, every single part following the exactly same style like a manpage. We changed quite a lot and tried to enrich the content as much as we could but Mel felt that it was too tight to reuse and that it would be better to completely start over; I liked that idea so this is what we did.

So, when you are talking about the GUM, are you talking about that obscure book, or about the help files, or both?

The old gimp-help content was derived from this "obscure book" with consent from the authors, so yes. In the beginning we just had the HTML which was converted over to DocBook/SGML in quite some amount of work and reformatted to be useful.

Are you trying to make a manual and help files in one?

Ultimatively yes. We tried to start with the manual though and haven't cared to much about the "help files" so far. In the end the help files will simply be fractions of the manual whether HTML or some other format, optionally reformatted for better use in a helpbrowser.

Ah, OK, so when you say size, you don't mean physical size?

Size is the perceived size, whether that are kilobyte, megabyte, lines or words (real or with markup) doesn't matter.

But that the document is on-topic for the user?

I beg your pardon?

Probably not. But I imagine that if I wanted to see a page about one of the blur filters, you would be able to provide me with a page about that help filter.

That for sure. Uncertain is how much information you'll get.

Am Die, 2003-08-19 um 15.08 schrieb Raphaël Quinet:

Now I am confused. I thought that we were talking about the online help system, not about the manual (GUM). It looks like you consider both of them to be the same thing. Is that right?

The old gimp-help was build upon the content of the GUM. And yes, I think it still makes sense to derive the onlinehelp from manual (but not the other way round).

I thought that the online help would be something that is focused on explaining individual functions, i.e. one page for each feature. If I understood you correctly, you would like to merge these functional descriptions with something that is more like a tutorial.

Exactly, I think online help is only worth it when it helps people. That means it should provide information about the topic at hand, it's meaning, a short description how it works, the available parameters and at least a link to some tutorial.

Typically some builtin help is more like a rephrasing of what a non-blind person can see in the user interface. I don't think this is helpful at all; I think the person desperately trying to retrieve some useful information which cannot be found is more annoyed by the loss of time than the missing help. At least I made that experience some years ago with quite prominent MS software.

For the "online help" part (the part that is called directly by the GIMP when the user invokes the context help), I do not see any need to allow anything else than a one-to-one mapping between the English version and the translations.

Yes, for this it may not be necessary technically, but why restrict oneself when more is possible without additional efforts... :)

I think that too many people are confused now. Daniel, it would be nice if you start a new thread with a message explaining what are the plans for the new help system. I would like to know what are the goals, non-goals and the proposed implementation. Note that these goals do not necessarily have to be discussed: it would be fine for me if you said: "I am going to do it like that or not at all." But at least these ideas should be summarized in a clear way, to avoid future confusion about the plans for the help system.

Caught me here. I fear I still haven't provided enough information so I'd probably be better off investing some time into some updated paperwork which I can refer to. I'm a bit busy though so please don't hold your breath....

On Tue, Aug 19, 2003 at 07:32:24PM +0200, Daniel Egger wrote:

book, see below) was anachronistic, more like a reference than a fluent style, every single part following the exactly same style like a manpage. We changed quite a lot and tried to enrich the content as much

References are extremely important, more important than tutorials in prose, IMnsHO.

I think tutorials/introductions/verbose manuals/howtos are extremely important to get people working, but for the actual work I very very much prefer manpages, since when I ask for help on a specific item I want to know about obscure settings, settings I didn't memorize, and a terse manpage-like style is the one that gets the information across.

Now, maybe this can be combined, like a manpage-style reference + links to usage examples (that would imho be optimal!), plus introductory material.

Of course, whoever produces a sizable amount of help material decides on the style, so the above just declares my preference in what I would clal "useful".

I mean, I almost never use online help since I usually cannot find the information I was looking for anyways. Under Windows (where I most often need help) for example, I often go to the online help because I want to know what that obscure option does, only to find that only the basic options are documented, the basic options I know already anyways.

That for sure. Uncertain is how much information you'll get.

Yeah :( But providing good and useful documentation is extremely hard. I don't believe the Gimp will succeed, but if it does, it'll be _the_ prototypical "free software rocks" app for another reason again.

Am Mit, 2003-08-20 um 01.41 schrieb pcg@goof.com:

References are extremely important, more important than tutorials in prose, IMnsHO.

This doesn't clash with my idea. Especially good cross references are important but this is exactly one of DocBooks' strengths.

Now, maybe this can be combined, like a manpage-style reference + links to usage examples (that would imho be optimal!), plus introductory material.

This is the plan. :)

Yeah :( But providing good and useful documentation is extremely hard. I don't believe the Gimp will succeed, but if it does, it'll be _the_ prototypical "free software rocks" app for another reason again.

Heh, don't be so negative, rather help us to bring the help up to par with your sense of quality, content- and structurewise.