David (Saturday, 06. November 2010)
> I do have a cloned copy, and have submitted one minor change from
> it.

I just wanted to make sure that we don't talk about different version 
of the manual.

> However the webpages at
> http://drking.webstarts.com/index.html
> are a quick mock-up using (rather imperfect) html/css.

That's what I thought.

> The main problem I'm trying to solve can be illustrated thus:
> The docs describe how to draw a straight line, *at least twice*.
> The second author must have been unaware that it had already been
> done.

It's a feature: it doubles the chance that a user finds it. ;-)

Ok, seriously, in this special case it may happened because the first 
chapter (5. How to Draw Straight Lines) is an external tutorial. Or 
because a user may skip the "Getting Started" part if he is not an 
absolute beginner.

But it may also show one of our main problems: the way the manual is 
growing (rampant) over the years...

> Now, if an author is unable to find what is in the contents,
> there is surely little hope for a user. That's a problem, isn't
> it? ;)

It is. ;-)

> My contention is that by restructuring the contents we could make
> the docs much easier to use. So I've mocked that up for your
> comments.

At first sight your suggestion looks fine to me. My problem is that I 
*know* where to find the topics (translator/documenter bias ;-)).
So shouldn't we ask someone who had never worked with GIMP or had 
never tried to read the manual? ;-)

> Because it was easy, I've used a more visually compact page layout,
> which I prefer - that's a secondary (independent) issue.

Note that the table of contents is created automatically. So if we 
build the manual without changing the toc parameters, your toc will no 
longer be compact.
(We can also build a compact toc, e.g. with
        make html-en XSLTEXTRAFLAGS='--stringparam toc.max.depth 2'
and then the current toc is as readable as your version.)

> If there is interest in restructuring the contents, I'd try to find
> the time to set things up. If not, I'd be better offering just
> minor changes from hand-altered docbook source, for someone else
> to test / commit.

Hmm, obviously we need more feedback...  

Roman, what does the big boss think about it? ;-)

David (Saturday, 06. November 2010)
> @Ulf
> > "Selections" as sub-section of "Painting" is not too absurd IMHO.
> > Remember that you can select and copy/cut to create a new brush
> > (see 7.9.2. "Creating a brush quickly").
> Sorry - should have replied to this. If I'm right that the contents
> page is too long, then a new user needs to be able to find
> "Selections" from a top level section heading.

You might be right. I would use the browsers's search routine
(Ctrl-F), but I don't know how an average user or a new user solves 
this problem. Again, we don't get any feedback. :-(

> The killer point is that the contents are for someone who doesn't
> currently know that "you can select and copy/cut to create a new
> brush." Actually I didn't ;).

I learned it when translating that section.
> It's just my view of course...

Good points IMHO. :-)


Jeder Staat beruht auf Macht, jede Macht auf Gewalt, und
Gewalt, sagt Einstein, zieht stets moralisch Minderwertige an.
                -- Karlheinz Deschner

Attachment: signature.asc
Description: This is a digitally signed message part.

Gimp-docs mailing list

Reply via email to