Sent: 2010-08-30 19:18:43 UTC (over 1 year ago)

From: David

a new user perspective

permalink

I'm coming to the GIMP as a new user, having tried it a few years ago and then
preferred other software; I am returning now because of the features.

In a spirit of trying to help, may I share a few observations about the online
documentation that would make my reading of it easier?

1. There is no link off the manual to the GIMP site. I wanted that.

2. I'd much prefer a clearer layout of the manual web pages. For example the
first page shows just a logo, until I scroll down, and the contents are spread
over multiple screens (impossible to get an overview). Images would be better
right or left aligned, definitely not inline as at present. Black text on white
is clearer than orange on grey. And so on.

3. Section 1.2 needs to tell me *how* to install the context sensitive help (I
installed GIMP as recommended, onto Windows, but no context sensitive or local
help is installed.)

I can share further specific points if there is interest

This is me trying to help, not moan ;) - I've written help for another open
source project, and have had around a million hits on those pages.

David

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-08-31 21:04:13 UTC (over 1 year ago)

From: Kolbjørn Stuestøl

a new user perspective

permalink

David wrote:
> I'm coming to the GIMP as a new user, having tried it a few years ago and then
> preferred other software; I am returning now because of the features.
>
> In a spirit of trying to help, may I share a few observations about the online
> documentation that would make my reading of it easier?
>
> 1. There is no link off the manual to the GIMP site. I wanted that.
>
> 2. I'd much prefer a clearer layout of the manual web pages. For example the
> first page shows just a logo, until I scroll down, and the contents are spread
> over multiple screens (impossible to get an overview). Images would be better
> right or left aligned, definitely not inline as at present. Black text on white
> is clearer than orange on grey. And so on.
>
This is a matter of taste, but I agree with you in some ways. The main
problem in my opinion is that it is a lot of work to change the layout.
Example: By using the gimp-help-custom.css style sheet you may change
all the classes used in GIMP without doing any harm to the common style
sheets. I tried black print on a white background. It works quite well,
but perhaps not so nice as the original layout. More complicated: I made
the images floating to the right (by adding "float: right" to the class
"mediaobject"). In a way you are right, but the images overwrote some
other elements on the side. So I had to change the command a bit. Then
... etc. Another problem is that not all users use "standard" browsers.
Not all commands used in the stylesheets shows up the same way an all
browsers. (Today a minor problem as most browsers follows the
"standards", but still a problem.
> 3. Section 1.2 needs to tell me *how* to install the context sensitive help (I
> installed GIMP as recommended, onto Windows, but no context sensitive or local
> help is installed.)
>
Yes. I have got several questions about where to find the help files for
downloading and how to install them. Most people finds the online help,
but not the ftp download and if they find them, how to open them? To the
average Windows user the ".tar.bz2" is a totally unknown file formate.
Many unzip programs running in Windows are unable to read this formate.
It could look a bit inconsistent to have a receipt on how to install
help files as you have to install them before you can read the files.
But all users connected to internet can read the online help.
> I can share further specific points if there is interest
>
> This is me trying to help, not moan ;) - I've written help for another open
> source project, and have had around a million hits on those pages.
>
We needs all the help and new thoughts we can get. You are welcome.
Working on the GIMP manual for some years results in a kind of blindness
to both the contents and the layout.
You made me think about what does the average GIMP user really needs.
Thank you, David.

Kolbjoern

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-01 01:11:58 UTC (over 1 year ago)

From: David

a new user perspective

permalink

Hi Kolbjørn

Thanks for your positive comments

>> 2. I'd much prefer a clearer layout of the manual web pages.

> This is a matter of taste, but I agree with you in some ways. The main
> problem in my opinion is that it is a lot of work to change the layout.

I wonder if using a wiki would help? It means you lower the author entry
barriers, and it's easier to work collaboratively. I know the help pages I wrote
(in a wiki) have been tweaked by worthy souls (although to be fair rather rarely).

Do you also publish a pdf? Are you committed to Docbook? (am I right that that's
what the manual is written in?) I've not used it, but perhaps a difficulty might
be that it tends to force a single layout, whereas info on the web should be
presented differently from info in print/pdf.

On my system, 1280x1024, the table of contents goes on for 26 pages/screens -
that's too much ;) ("more is less")

Could the contents be kept to say 3 screens? Two ways: firstly don't nest 4
deep, maybe just 2 deep; or secondly use DHTML to collapse the contents (and
expand as requested).

I accept your point about browser compatibilty/DHTML, but the main GIMP page
pulls in a number of scripts (though why I don't know).

By the way a zip compress of the help files is much the same size as the tar.bz2
- I don't know whether standard Win can open .tar.bz2 but it can handle zip of
course.

A few rather random thoughts, then. You've got loads of really good info
available - so this is merely by way of honing.

David

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-01 11:56:41 UTC (over 1 year ago)

From: David

a new user perspective

permalink

> I wonder if using a wiki would help?

On second thoughts, I think not - there is a huge amount of content (500+
pages), so the work would be in layout, rather than authoring. I guess it would
have to be a page by page thing, rather than just a change of css.

I *am* finding navigation a problem

D

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-01 14:51:43 UTC (over 1 year ago)

From: Ulf-D. Ehlert

a new user perspective

permalink

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-01 19:02:56 UTC (over 1 year ago)

From: Kolbjørn Stuestøl

a new user perspective

permalink

Ulf-D. Ehlert skreiv:
> David (Monday, 30. August 2010)
>
>> In a spirit of trying to help, may I share a few observations about
>> the online documentation that would make my reading of it easier?
>>
>
> Feedback is always welcome! :-)
>
>
>> 1. There is no link off the manual to the GIMP site. I wanted that.
>>
>
> The HTML manual contains more than 500 HTML pages. IMHO using your
> browser's bookmark feature will probably much easier and faster than
> searching for a link somewhere in the manual...
>
>
>> 2. I'd much prefer a clearer layout of the manual web pages. For
>> example the first page shows just a logo, until I scroll down,
>>
>
> What's wrong with the nice logo? ;-)
>
I think nothing, but as I understood David think the place could be
better user for text to avoid scrolling?
>
>> and the contents are spread over multiple screens (impossible to get
>> an overview).
>>
>
> Ok, the table of contents *is* a bit confusing.
>
>
>> Images would be better right or left aligned,
>> definitely not inline as at present.
>>
>
> I don't see the problem (but that doesn't mean anything...). Can you
> provide some examples (e.g. GIMP vs. $OTHER_PROG manual)?
>
Just as in (many) books. The images are mostly placed to the left or
right side with the text surrounding it. Often more readable that the
way it is set up now. Well, perhaps a matter pf taste?
>
>> Black text on white is clearer than orange on grey.
>>
>
> We changed the style when the layout of the gimp home page changed.
> But you can switch to the old GIMP-2.2 ("gimp22") style (check the
> "View" menu of your browser). This works for online and offline
> version.
>
>
>> 3. Section 1.2 needs to tell me *how* to install the context
>> sensitive help (I installed GIMP as recommended, onto Windows, but
>> no context sensitive or local help is installed.)
>>
>
> This seems to be a common Windows problem. Linux
> distributions should install the GIMP manual package ("gimp-doc" or
> "gimp-help") if the "gimp" package is selected.
>
> Since I'm a Linux-only user, I have no clue about the Windows way of
> installing packages.
>
In Windows installing programs are much simpler than in Linux. Mostly
you start an installer and that's it. The average Windows user normally
do not know how to install packages like in Linux.

But the main problem to the Windows user, in my opinion at least, is how
to find the download site and zip files. The ".bz2" is unknown to most
users and the formate is not handled by (most?) unzip program used in
Windows. So a solution could be to add the necessary files in ".zip"
formate (which is readable by Windows) reachable from the common
download (html) sites? I guess the average Windows user is not familiar
with the ftp protocol either.

Somewhere there also has to be a description on where to put the help
files in the gimp catalog. Something like: "Unzip the help files to the
GIMP-2.0 -> share -> gimp -> 2.0 -> help folder". Simple?

This suggestions are more changes in the gimp.org sites than for the manual.

>> I can share further specific points if there is interest
>>
>
> Definitely yes. :-)
>
> Ulf
>
Yes.
I know there are lots of people in this forum knowing much more about
the styling and contents etc. of the GIMP manual than I do. Some
thoughts on David's suggestions?

Kolbjoern

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-01 21:28:47 UTC (over 1 year ago)

From: David

a new user perspective

permalink

I've quickly mocked up an alternative contents page, using headings up to 2
deep. It uses just more than one screen on my system.

A copy/paste of those contents is:

==================
Preface
1. GIMP User Manual Authors and Contributors

I. Getting Started
1. Introduction
2. Fire up the GIMP
3. First Steps with Wilber
4. Getting Unstuck

II. How do I Become a GIMP Wizard?
5. Getting Images into GIMP
6. Getting Images out of GIMP
7. Painting with GIMP
8. Combining Images
9. Enhancing Photographs
10. Color Management with GIMP
11. Pimp my GIMP
12. Scripting

III. Function Reference
13. Toolbox
14. Dialogs
15. Menus
16. Filters
I. Keys and Mouse Reference

Glossary
Bibliography
A. GIMP History
B. Reporting Bugs and Requesting Enhancements
C. GNU Free Documentation License
D. Eeek! There is Missing Help
Index
=============

Now, I might be wrong, but it looks illogical to me ;). If it's a tree structure
(and it ought to be, surely) then the numbering after:
II. How do I Become a GIMP Wizard?
should be:
1. Getting Images into GIMP and so on

Then:
I. Keys and Mouse Reference
is an anomaly - it doesn't fit on the tree.

A. GIMP History
B. Reporting Bugs and Requesting Enhancements
C. GNU Free Documentation License
D. Eeek! There is Missing Help
could/should all be on a separate branch: Appendices, probably placed before
Glossary.

I guess it's only by removing the clutter that the structure of the thing
becomes clear.

To be honest, I can't see what information the headings I, II, and III add. For
example:
5. Getting Images into GIMP
6. Getting Images out of GIMP
is little more than File Open/Save - scarcely GIMP Wizardry :)

However, having said that, the important discussion of colour models is actually
within 5. - you'd never guess that from the heading, so wouldn't it be better
relocated?

If it would help anyone to see my (crude) webpage mock-up I can send it
privately as a zip - I assume the list will not permit attachments.

Goodness, I hope this is helpful and not just a pain ;)

David

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-01 23:25:59 UTC (over 1 year ago)

From: Kolbjørn Stuestøl

a new user perspective

permalink

David skreiv:
> I've quickly mocked up an alternative contents page, using headings up to 2
> deep. It uses just more than one screen on my system.
>
> A copy/paste of those contents is:
>
> ==================
> Preface
> 1. GIMP User Manual Authors and Contributors
>
> I. Getting Started
> 1. Introduction
> 2. Fire up the GIMP
> 3. First Steps with Wilber
> 4. Getting Unstuck
>
> II. How do I Become a GIMP Wizard?
> 5. Getting Images into GIMP
> 6. Getting Images out of GIMP
> 7. Painting with GIMP
> 8. Combining Images
> 9. Enhancing Photographs
> 10. Color Management with GIMP
> 11. Pimp my GIMP
> 12. Scripting
>
> III. Function Reference
> 13. Toolbox
> 14. Dialogs
> 15. Menus
> 16. Filters
> I. Keys and Mouse Reference
>
> Glossary
> Bibliography
> A. GIMP History
> B. Reporting Bugs and Requesting Enhancements
> C. GNU Free Documentation License
> D. Eeek! There is Missing Help
> Index
> =============
>
>
> Now, I might be wrong, but it looks illogical to me ;). If it's a tree structure
> (and it ought to be, surely) then the numbering after:
> II. How do I Become a GIMP Wizard?
> should be:
> 1. Getting Images into GIMP and so on
>
It is obviously not a real tree. More a random list. The numbers
referrers to the chapter numbers I think.
>
> Then:
> I. Keys and Mouse Reference
> is an anomaly - it doesn't fit on the tree.
>
>
> A. GIMP History
> B. Reporting Bugs and Requesting Enhancements
> C. GNU Free Documentation License
> D. Eeek! There is Missing Help
> could/should all be on a separate branch: Appendices, probably placed before
> Glossary.
>
Yes. Why not only put the A, B, C, and D into a common Appendices?

Perhaps also the 1. GIMP User Manual Authors and Contributors could be
moved hereto? The user is more interested in how tos than who made the
manual. I do am aware of that it is a common habit to start with the
authors etc.
>
> I guess it's only by removing the clutter that the structure of the thing
> becomes clear.
>
>
> To be honest, I can't see what information the headings I, II, and III add. For
> example:
> 5. Getting Images into GIMP
> 6. Getting Images out of GIMP
> is little more than File Open/Save - scarcely GIMP Wizardry :)
>
Amen
> However, having said that, the important discussion of colour models is actually
> within 5. - you'd never guess that from the heading, so wouldn't it be better
> relocated?
>
Better under10. Color Management with GIMP?

>
> If it would help anyone to see my (crude) webpage mock-up I can send it
> privately as a zip - I assume the list will not permit attachments.
>
> Goodness, I hope this is helpful and not just a pain ;)
>
> David
Some rapid comments late in the evening. Should perhaps had thought it
over before sending?
I think it is possible to rebuild the index without major difficulties.
Not even the GIMP manual is perfect.

Kolbjoern

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-02 11:29:20 UTC (over 1 year ago)

From: David

a new user perspective

permalink

Hi Kolbjørn

So you'd go for something like this?:
=============
1. Introduction
2. Fire up the GIMP
3. First Steps with Wilber
4. Getting Unstuck
5. Getting Images into GIMP
6. Getting Images out of GIMP
7. Painting with GIMP
8. Combining Images
9. Enhancing Photographs
10. Color Management with GIMP
11. Pimp my GIMP
12. Scripting
13. Toolbox
14. Dialogs
15. Menus
16. Filters

Appendices
A. Keys and Mouse Reference
B. GIMP User Manual Authors and Contributors
C. GIMP History
D. Reporting Bugs and Requesting Enhancements
E. GNU Free Documentation License
F. Eeek! There is Missing Help

Glossary
Bibliography
Index
=============

Looks better to me.

I'd also prefer to rename
2. Fire up the GIMP
3. First Steps with Wilber
to
2. Starting the GIMP
3. Basic Concepts
which to me sounds more professional, and explains more clearly.

And under 'Basic Concepts' the entire first screen on my system says
"The Wilber_Construction_Kit (in src/images/) allows you to give the mascot a
different appearance. It is the work of Tuomas Kuosmanen...". This really,
really is not a basic concept. Really... no-one who needs to know basic concepts
wants to know that ;).

David

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-02 12:06:00 UTC (over 1 year ago)

From: Roland

a new user perspective

permalink

Sent: 2010-09-02 12:17:28 UTC (over 1 year ago)

From: Kolbjørn Stuestøl

a new user perspective

permalink

David skreiv:
> Hi Kolbjørn
>
> So you'd go for something like this?:
> =============
> 1. Introduction
> 2. Fire up the GIMP
> 3. First Steps with Wilber
> 4. Getting Unstuck
> 5. Getting Images into GIMP
> 6. Getting Images out of GIMP
> 7. Painting with GIMP
> 8. Combining Images
> 9. Enhancing Photographs
> 10. Color Management with GIMP
> 11. Pimp my GIMP
> 12. Scripting
> 13. Toolbox
> 14. Dialogs
> 15. Menus
> 16. Filters
>
> Appendices
> A. Keys and Mouse Reference
> B. GIMP User Manual Authors and Contributors
> C. GIMP History
> D. Reporting Bugs and Requesting Enhancements
> E. GNU Free Documentation License
> F. Eeek! There is Missing Help
>
> Glossary
> Bibliography
> Index
> =============
>
> Looks better to me.
>
> I'd also prefer to rename
> 2. Fire up the GIMP
> 3. First Steps with Wilber
> to
> 2. Starting the GIMP
> 3. Basic Concepts
> which to me sounds more professional, and explains more clearly.
>
> And under 'Basic Concepts' the entire first screen on my system says
> "The Wilber_Construction_Kit (in src/images/) allows you to give the mascot a
> different appearance. It is the work of Tuomas Kuosmanen...". This really,
> really is not a basic concept. Really... no-one who needs to know basic concepts
> wants to know that ;).
>
>
> David
>
I'll be buzzy this weekend and the first days of next week, but will
give it a thought then.
Obviously there is a need of fresh ayes looking at the content of the help.
Perhaps putting the points 5 and 6 togethr in one sentence?
I think we could find some other misplaced texts around in the files.
But where to put the credit to Tuomas?
More in a few days.
Kolbjoern

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-02 20:59:06 UTC (over 1 year ago)

From: David

a new user perspective

permalink

Hi Ulf

I probably should have replied specifically to your points.

> The HTML manual contains more than 500 HTML pages. IMHO using your
> browser's bookmark feature will probably much easier and faster than
> searching for a link somewhere in the manual...

The trouble is that *nowhere* is there a link out. The manual is a dead end;
isn't that poor web practice?

However the solution may be very simple. Use a layout like
http://www.gimp.org/docs/
with "wilber | GIMP" in the top orange bar to the left, linked to gimp.org.
That's how I did it in my mock-up.

>> Images would be better right or left aligned,
>> definitely not inline as at present.
>
> I don't see the problem (but that doesn't mean anything...). Can you
> provide some examples (e.g. GIMP vs. $OTHER_PROG manual)?

Are you familiar with the F shaped scan that readers' eyes are supposed to use
on web pages? It's all to do with getting at the info quickly. So, I'm
suggesting putting the readable info where the eye goes. I'll mock up some pages
where I feel I'm currently being overwhelmed by images, if that seems likely to
help.

> We changed the style when the layout of the gimp home page changed.
> But you can switch to the old GIMP-2.2 ("gimp22") style (check the
> "View" menu of your browser). This works for online and offline
> version.

I just learnt something - thank you.

>> 3. Section 1.2 needs to tell me *how* to install the context
>> sensitive help

> This seems to be a common Windows problem.

A good idea to have it in the manual then :)

>> I can share further specific points if there is interest
>
> Definitely yes. :-)

OK, then :) :
section I.3.1
"Channels
In GIMP, Channels are the smallest units of subdivision in the stack of
layers from which the image is constructed."

That's wrong! The 'smallest unit of subdivision in a stack of layers' is
(probably) 'one layer'. I actually thought GIMP had a different
definition/concept to everyone else on reading that, and I read it several times
before deciding to ignore it. The manual needs rewriting here with a small
picture to clarify. I'm a bit hesitant to give specific text, because I'm not
clear how GIMP views itself.

Incidentally, at the top of that page we have:
"everything mentioned here is so high-level that you can easily locate it in the
index" - so
Try looking for 'channel'...
Confusing number of entries, aren't there? Unfortunately not one to I.3.1. :(
Only one looks promising:
Introduction, Glossary
"A Channel is a single component of a pixel's color."

Oh dear, that's not the same as
http://en.wikipedia.org/wiki/Channel_(digital_image)
nor I believe is it what Section I.3.1 is trying to define.

There's an alternative definition further down, but it's too late then - the
user (me) is already confused.

Noting that the glossary (presumably intended to be the 'full' explanation of
'channel') has much the same length of text as in Section I.3.1, my suggestion
here would be to nail the thing properly in Section I.3.1.

David

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-02 21:11:36 UTC (over 1 year ago)

From: Sven Neumann

a new user perspective

permalink

On Wed, 2010-09-01 at 19:02 +0200, Kolbjørn Stuestøl wrote:

> In Windows installing programs are much simpler than in Linux. Mostly
> you start an installer and that's it. The average Windows user normally
> do not know how to install packages like in Linux.

Actually on Linux, you are using a package installer software provided
by your distribution. This is even simpler than on Windows. No average
user on Linux knows how to install from source either and shouldn't have
to know.

> But the main problem to the Windows user, in my opinion at least, is how
> to find the download site and zip files. The ".bz2" is unknown to most
> users and the formate is not handled by (most?) unzip program used in
> Windows. So a solution could be to add the necessary files in ".zip"
> formate (which is readable by Windows) reachable from the common
> download (html) sites? I guess the average Windows user is not familiar
> with the ftp protocol either.
>
> Somewhere there also has to be a description on where to put the help
> files in the gimp catalog. Something like: "Unzip the help files to the
> GIMP-2.0 -> share -> gimp -> 2.0 -> help folder". Simple?

The tarballs are not targeted at users. Users are supposed to install
the manual by means of an installer (Win32) or by installing a package
created for their distribution (Linux). The tarballs that are provided
on ftp.gimp.org are the source that packages are supposed to use.
Nothing more, nothing less.

You should try to play well with packagers and distributions and make
releases frequently so that users can pick up updates easily. It is not
our job to educate them how to install the manual from source. And I
consider the generated HTML the source. It's not something users should
have to deal with.

Sven

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-02 22:55:45 UTC (over 1 year ago)

From: David

a new user perspective

permalink

On 02/09/2010 20:11, Sven Neumann wrote:

> You should try to play well with packagers and distributions and make
> releases frequently so that users can pick up updates easily. It is not
> our job to educate them how to install the manual from source. And I
> consider the generated HTML the source. It's not something users should
> have to deal with.

Fully agree with that. And indeed it turns out that the person who made the
2.6.0 installer for Windows has also packaged the help files as a separate
installer....

I found this by googling a few times and discovered:
http://www.referpages.com/reference/web/37-web-design/81-gimp.html
which points to a sourceforge site. I tried it - it works.

So the problem is simply that the damn thing is not on the GIMP web site, so
no-one knows about it; considering that lack of local Win help files is a common
problem, surely to goodness someone can fix that....?

D

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-04 18:57:19 UTC (over 1 year ago)

From: David

a new user perspective

permalink

>> I can share further specific points if there is interest
>
> Definitely yes. :-)

Just come across this little one:

=====
2.4. Open

The Open command activates a dialog that lets you load an existing image from
your hard-drive or an external medium. For alternative, and sometimes more
convenient, ways of opening files, see the Files section.
=====

The "Files section" link is incorrect - there is nothing about opening files there

D

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-05 10:33:25 UTC (over 1 year ago)

From: David

a new user perspective

permalink

Another specific issue:

======
13.2. Creating a Basic Shape

1.Drawing shapes is not the main purpose for using GIMP. However, you may
create shapes by either painting them using the technique described in Figure
7.35, “A new image” or...
==========

I suggest this would be better as:
======
13.2. Creating a Basic Shape

1.Drawing shapes is not the main purpose for using GIMP. However, you may
create shapes by either by drawing straight lines (Section 13.1) or...
==========

My reasons this text would be better:
1. it's shorter
2. it says what the technique is, so you don't need to click away from the page
3. Figure 7.35 does not itself describe a technique (wrong place to link to)

+++++++++++++

I hope you get the idea I'm trying to come up with positive ways to refine the
manual - but I'm not yet sure if I'm getting through to the right people... Am I
likely to make a difference, or should I quietly fade away? ;)

D

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-05 12:17:16 UTC (over 1 year ago)

From: Hugh Loebner

a new user perspective

permalink

Why not link to Inkscape, an open source drawing program?

On Sep 5, 2010 4:34 AM, "David" wrote:
Another specific issue:

======
13.2. Creating a Basic Shape

1.Drawing shapes is not the main purpose for using GIMP. However, you may
create shapes by either painting them using the technique described in
Figure
7.35, “A new image” or...
==========

I suggest this would be better as:
======
13.2. Creating a Basic Shape

1.Drawing shapes is not the main purpose for using GIMP. However, you may
create shapes by either by drawing straight lines (Section 13.1) or...
==========

My reasons this text would be better:
1. it's shorter
2. it says what the technique is, so you don't need to click away from the
page
3. Figure 7.35 does not itself describe a technique (wrong place to link to)

+++++++++++++

I hope you get the idea I'm trying to come up with positive ways to refine
the
manual - but I'm not yet sure if I'm getting through to the right people...
Am I
likely to make a difference, or should I quietly fade away? ;)

D

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berke...

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-05 13:58:31 UTC (over 1 year ago)

From: Ulf-D. Ehlert

a new user perspective

permalink

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-05 13:59:09 UTC (over 1 year ago)

From: Ulf-D. Ehlert

a new user perspective

permalink

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-05 14:19:45 UTC (over 1 year ago)

From: David

a new user perspective

permalink

On 05/09/2010 11:17, Hugh Loebner wrote:
> Why not link to Inkscape, an open source drawing program?

Because this part of the manual is about drawing shapes in GIMP (and only in GIMP).

People who read a manual generally do not want to read it. They generally want
to be using the application, but cannot figure out how. So the task is to give
them the information (and only that information) as quickly/succinctly as possible.

"More is less". More information than needed makes the manual less useful.

Am I preaching to the converted, or is that a heretical view? ;)

D

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-05 18:06:25 UTC (over 1 year ago)

From: Bill Skaggs

a new user perspective

permalink

On Sun, Sep 5, 2010 at 5:19 AM, David wrote:

> On 05/09/2010 11:17, Hugh Loebner wrote:
> > Why not link to Inkscape, an open source drawing program?
>
> Because this part of the manual is about drawing shapes in GIMP (and only
> in GIMP).
>
> People who read a manual generally do not want to read it. They generally
> want
> to be using the application, but cannot figure out how. So the task is to
> give
> them the information (and only that information) as quickly/succinctly as
> possible.
>
> "More is less". More information than needed makes the manual less useful.

That's partly a good principle, but needs to be used in a balanced way. It
strikes me that
a brief explanation that Gimp is not designed to be used for drawing shapes,
whereas
other programs such as Inkscape are specifically intended for that purpose,
might save
the user considerable time and effort.

But beyond that, it's also true that the manual *can* be something that
people will be
able to read in order to learn how the program works, rather than just
something to
consult when there is a problem. The ideal is to make it both. I did a lot
of work on
Gimp Help about five years ago, and was definitely aiming to make it
something that
people could read.

-- Bill

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-05 20:14:15 UTC (over 1 year ago)

From: David

a new user perspective

permalink

Hi Bill

> On 05/09/2010 11:17, Hugh Loebner wrote:
> > Why not link to Inkscape, an open source drawing program?
>
> Because this part of the manual is about drawing shapes in GIMP (and only in
> GIMP).

> "More is less". More information than needed makes the manual less useful.
>
> That's partly a good principle, but needs to be used in a balanced way. It
> strikes me that
> a brief explanation that Gimp is not designed to be used for drawing shapes, whereas
> other programs such as Inkscape are specifically intended for that purpose,
> might save
> the user considerable time and effort.

That's true - but I do feel that this is the *wrong place* for it. The same
('link to Inkscape') argument applies to section 1.5, and to section 7.13.1, as
well as to section 7.13.2 (which I previously incorrectly identified as section
13.2, due to that being the way the page identifies itself ;) ). It's possible
that someone using paths might like to know about Inkscape too.

Surely we would not want 3 or more similar references out to Inkscape?

It would certainly be possible clarify the difference between vector and pixel
based programs under 'basic concepts' - and link out there...

> But beyond that, it's also true that the manual *can* be something that people
> will be
> able to read in order to learn how the program works, rather than just something to
> consult when there is a problem. The ideal is to make it both. I did a lot of
> work on
> Gimp Help about five years ago, and was definitely aiming to make it something that
> people could read.

It's certainly readable - there's *loads* of good information :). My main
concern is that it needs organising (and some editing). It feels as if it has
grown and grown, with different people adding different bits, but without an
overall structure....?

I'm not suggesting that it's merely a problem solver - clearly people who come
to the program for the first time have to read the manual to learn how the
program works - but you can bet on it that they'll stop reading as soon as they can.

David

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-05 20:25:08 UTC (over 1 year ago)

From: David

a new user perspective

permalink

Hi Ulf

> An example would still be useful, however, (especially an
> example where the GIMP manual is hard to read due to misplaced
> images).

I'll mock something up - but not for a little while - getting swamped..

>>>> 3. Section 1.2 needs to tell me *how* to install the context
>>>> sensitive help
[...]
> Maybe, but I can't do anything here.

It can be solved by putting the *existing Win help installer* on the GIMP
website (see my previous message)

> (BTW, glossary entries should be short, providing e.g. a
> simplified summary/definition of the respective item, IMHO.)

Yes, I agree :)

> Ok, so it looks like we have to
> (1) rewrite I.3.1 (based on the - adapted - wikipedia article and
> the glossary entry?),
> (2) add an index entry which refers to I.3.1, and
> (3) write a new (short and basic) glossary definition.
>
> Correct?
>
> I volunteer myself for (2).

The easy one, eh? ;)

I don't mind having a shot at it if no-one else bites, but again not for a
little while, and furthermore I fear I'm not yet familiar enough with the GIMP.
So preferably someone else will volunteer?

D

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-07 20:44:11 UTC (over 1 year ago)

From: Sven Neumann

a new user perspective

permalink

On Mon, 2010-09-06 at 23:48 +0100, David wrote:
> > It's there already, on the offical GIMP for Windows site, right next to
> > the latest GIMP for Windows installer, linked prominentely from
> > www.gimp.org: http://gimp-win.sourceforge.net/stable.html
> >
> > What change exactly are you suggesting?
>
> If I want GIMP I go to
>
> http://www.gimp.org/downloads/
>
> The thing that is prominent there is
>
> **Download GIMP 2.6.10 – Installer for Windows XP SP2 or later**
>
> That is what I click on. Obvious and clear.

Ah, OK. That page is dependent on the operating system you are visiting
it with. So I have no idea what it looks like for Windows users. If I
want to see the Windows downloads, then I go to
http://www.gimp.org/windows/ and follow the link there which leads to me
the page that I showed you.

You are at the wrong mailing-list though. If you want to suggest changes
to www.gimp.org then you should suggest this on the gimp-web list.

Sven

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-08 12:10:56 UTC (over 1 year ago)

From: David

a new user perspective

permalink

> You are at the wrong mailing-list though. If you want to suggest changes
> to www.gimp.org then you should suggest this on the gimp-web list.

OK - thank you, Sven, I've raised it there.

I think it was on this (doc) list originally because the help identifies the
problem (missing help files) but does not describe the solution (*how* to
install them).

D

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-09-08 17:54:39 UTC (over 1 year ago)

From: Ulf-D. Ehlert

a new user perspective

permalink

_______________________________________________
Gimp-docs mailing list
Gimp-docs@lists.XCF.Berkeley.EDU
https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-docs

Sent: 2010-10-27 16:16:25 UTC (over 1 year ago)

From: Ulf-D. Ehlert

a new user perspective

permalink

David (Sunday, 05. September 2010)
> > Ok, so it looks like we have to
> > (1) rewrite I.3.1 (based on the - adapted - wikipedia article and
> >
> > the glossary entry?),
> >
> > (2) add an index entry which refers to I.3.1, and
> > (3) write a new (short and basic) glossary definition.
> >
> > Correct?
> >
> > I volunteer myself for (2).
>
> The easy one, eh? ;)
>
> I don't mind having a shot at it if no-one else bites, but again
> not for a little while, and furthermore I fear I'm not yet
> familiar enough with the GIMP. So preferably someone else will
> volunteer?

My first attempt/suggestion:

We swap the glossary entry with the Channel description of the Basic
Concepts section (and modify both texts a little bit).
This way, a user will find a detailed (and better) description of
channels where he will expect it to be (is this true?) and we
have a short overview in the glossary.

IMHO, whenever a text explains how to do something (here: how to
create a channel) it's definitely not a text for the glossary.

My current glossary entry reads:

"A channel refers to a certain component of an image.[*] For
instance, the components of an RGB image are the three primary
colors red, green, blue, and sometimes transparency (alpha).
[*] stolen from the Wikipedia article

Every channel is a grayscale image of exactly the same size as the
image and, consequently, consists of the same number of pixels.
Every pixel of this grayscale image can be regarded as a container
which can be filled with a value ranging from 0 to 255. The exact
meaning of this value depends on the type of channel, e.g. in the
RGB color model the value in the R-channel means the amount of red
which is added to the color of the different pixels; in the
selection channel, the value denotes how strongly the pixels are
selected; and in the alpha channel the values denote how opaque the
corresponding pixels are."

Still not perfect, but it seems better than current situation. At
least we should have a good starting point for further
enhancements/corrections.

(I wonder if we should move the "Mask" entry of the glossary to the
Basic Concepts too.)

Ulf

--
Daß Glaube etwas ganz anderes sei als Aberglaube,
ist unter allem Aberglauben der größte.
-- Karlheinz Deschner

Sent: 2010-10-28 09:51:15 UTC (over 1 year ago)

From: David

a new user perspective

permalink

On 27/10/2010 17:16, Ulf-D. Ehlert wrote:
> IMHO, whenever a text explains how to do something (here: how to
> create a channel) it's definitely not a text for the glossary.

I agree!

> My current glossary entry reads:
....
> Still not perfect, but it seems better than current situation.

Reads pretty well to me :)

> (I wonder if we should move the "Mask" entry of the glossary to the
> Basic Concepts too.)

The contents structure isn't quite right, is it? My view would be to have very
simple Basic Concepts but link from there to, for example, sections 7 and 8 -
where selections, layers etc ought to be more fully explained.

So my hunch would be to put the 'mask' stuff in sections 7/8 too - it's not
really a basic concept - it's a more advanced use of layers/selections.

I have actually re-written some of the Basic Concepts - will share with you
later - away for the weekend now. I've rewritten some of the selection mask
stuff too.

Another couple of ideas:
In the Glossary it might help to link to the fuller descriptions?

"Section 8: Combining Images" really needs to be renamed (using layers is not
the only way to combine images, and text has little to do with combining
images). I'd prefer it split - "Section 8: Layers", and then a new section
"Section 9: Text". Of course everything below then has to be renumbered

David

Sent: 2010-11-01 18:49:45 UTC (over 1 year ago)

From: Ulf-D. Ehlert

a new user perspective

permalink

David (Thursday, 28. October 2010)
> On 27/10/2010 17:16, Ulf-D. Ehlert wrote:
> > My current glossary entry reads:
[...]

> Reads pretty well to me :)

Since there are no other comments (and no objections) I will push my
changes in the next days.

> So my hunch would be to put the 'mask' stuff in sections 7/8 too -
> it's not really a basic concept - it's a more advanced use of
> layers/selections.

Hmm, sounds reasonable to me...

> I have actually re-written some of the Basic Concepts - will share
> with you later - away for the weekend now. I've rewritten some of
> the selection mask stuff too.

Aah! :-)

> Another couple of ideas:
> In the Glossary it might help to link to the fuller descriptions?

If a detailed description exists: yes, of course. (It's just so easy
to forget it.)

> "Section 8: Combining Images" really needs to be renamed

Fine with me.

> (using layers is not the only way to combine images,

That's no problem, but there are no other ways described.

> and text has little to do with combining images).

Quite apart from "Font Problems"...

> I'd prefer it split - "Section
> 8: Layers", and then a new section "Section 9: Text".

Again, sounds reasonable.

> Of course everything below then has to be renumbered

Numbering is done automatically by the DocBook stylesheets.

Ulf

--
Verdient eine Menschheit, die Trilliarden Tiere
tötet, nicht eben das, was sie dem Tier antut?
-- Karlheinz Deschner

Sent: 2010-11-02 08:30:30 UTC (over 1 year ago)

From: David

a new user perspective

permalink

On 01/11/2010 18:49, Ulf-D. Ehlert wrote:
>> Reads pretty well to me :)
>
> Since there are no other comments (and no objections) I will push my
> changes in the next days.

I've had a late thought....

I think Basic Concepts should be an overview, just to get people started, and
should link out to the fuller descriptions. Currently we have fuller
descriptions for Layers (albeit currently called 'Combining Images'), for
Selections (called 'Painting with GIMP'), for Undo (actually called 'Undoing' ;)
) and for Scripting (with Plug-ins thrown in there).

There doesn't seem to be a section with a fuller description for Channels - and
my suggestion would be that there *ought* to be - and that would be the best
place to put the current Glossary content.

I'm not sure whether that could be done now, or whether it should be split out
later.

Sorry I'm not faster at making contributions - just a matter of finding time.

>> Of course everything below then has to be renumbered
>
> Numbering is done automatically by the DocBook stylesheets.

Oh good :)

David

Sent: 2010-11-02 19:00:11 UTC (over 1 year ago)

From: Ulf-D. Ehlert

a new user perspective

permalink

David (Tuesday, 02. November 2010)
> I think Basic Concepts should be an overview, just to get people
> started, and should link out to the fuller descriptions. Currently
> we have fuller descriptions for Layers (albeit currently called
> 'Combining Images'), for Selections (called 'Painting with GIMP'),

No, there's no "Selections" section called "Painting with GIMP":
II.7.1+2 ("Selection" and "Creating and Using Selections") are
subsections of II.7 ("Painting with GIMP").
BTW, maybe we should merge 7.1 + 7.2...

> for Undo (actually called 'Undoing' ;) )

Is 'Undoing' wrong?

> and for Scripting (with Plug-ins thrown in there).
>
> There doesn't seem to be a section with a fuller description for
> Channels - and my suggestion would be that there *ought* to be -

Hmm, this would be logical.

> and that would be the best place to put the current Glossary
> content.

Yes, but then (IMHO) this text had to be expanded, e.g. by stealing
some stuff from the "Channels Dialog" chapter, adding examples and
figures, etc.

And if/when we change it, we should also handle
https://bugzilla.gnome.org/show_bug.cgi?id=569487
("effect of deactivating RGBA channels"),

so ...

> I'm not sure whether that could be done now, or whether it should
> be split out later.

... I think we should do it later.

Bye,
Ulf

--
Mißtraut denen, die da sagen, dass Gott auf ihrer Seite steht.
Sie sind nur so nah ihrem Gott, weil sie so fern dem Menschen sind.
-- Michael Schmidt-Salomon

Sent: 2010-11-02 19:58:30 UTC (over 1 year ago)

From: David

a new user perspective

permalink

Hi Ulf

>> for Layers (albeit currently called
>> 'Combining Images'), for Selections (called 'Painting with GIMP'),
>
> No, there's no "Selections" section called "Painting with GIMP":
> II.7.1+2 ("Selection" and "Creating and Using Selections") are
> subsections of II.7 ("Painting with GIMP").

OK - but what I really meant was that Selections are not really a sub-section of
Painting - for example you can cut and paste a selection, which is not painting.
It might be better to have Selections as a separate section...

> BTW, maybe we should merge 7.1 + 7.2...

As a separate section? :)

>> for Undo (actually called 'Undoing' ;) )
> Is 'Undoing' wrong?

No, indeed - my smile was because it seems to be the only one which is correctly
titled

>> There doesn't seem to be a section with a fuller description for
>> Channels - and my suggestion would be that there *ought* to be -
>
> Hmm, this would be logical.
>
>> and that would be the best place to put the current Glossary
>> content.
>
> Yes, but then (IMHO) this text had to be expanded, e.g. by stealing
> some stuff from the "Channels Dialog" chapter, adding examples and
> figures, etc.
>
> And if/when we change it, we should also handle
> https://bugzilla.gnome.org/show_bug.cgi?id=569487

OK

>> I'm not sure whether that could be done now, or whether it should
>> be split out later.
> ... I think we should do it later.

OK

D

Sent: 2010-11-05 07:04:31 UTC (about 1 year ago)

From: David

a new user perspective

permalink

In the spirit of contributing, I have mocked up a suggested new format for the
html documentation at:

http://drking.webstarts.com/index.html

It merely shows the ideas. Most of the links don't work (only 'home' works for
the navigation). Most of the pages aren't there (* in the contents = available).

I realise it's a bit radical, but almost all of the existing documentation
content would be re-used, just in a different order.

The major change is that the contents are structured and brief, on 1 screen
rather than 27; I think I'd know where to click to get the information I wanted.

I've used the main GIMP site style, and have put navigation buttons at both top
and bottom. In terms of actual content, see the Basic Concepts page, which I've
re-written: images are closer to the relevant text; they are smaller, but there
are more of them. There are links out to the relevant sections.

You'll probably find errors/omissions - but I thought it might be good to share,
warts and all.

What do you think? Practical or not? Improved or not?

David

Sent: 2010-11-05 19:38:22 UTC (about 1 year ago)

From: Ulf-D. Ehlert

a new user perspective

permalink

David (Tuesday, 02. November 2010)
> OK - but what I really meant was that Selections are not really a
> sub-section of Painting - for example you can cut and paste a
> selection, which is not painting. It might be better to have
> Selections as a separate section...

"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").

Ok, meanwhile I have committed my changed channel docs - I hope it
*is* an improvement...

@David:
BTW, I think you did never mention: are you working on cloned copy of
the git repository, i.e. on the source files?

Bye,
Ulf

--
Theologe - einziger Experte ohne Ahnung von seinem
Forschungsgebiet.
-- Karlheinz Deschner

Sent: 2010-11-06 06:21:13 UTC (about 1 year ago)

From: David

a new user perspective

permalink

> @David:
> BTW, I think you did never mention: are you working on cloned copy of
> the git repository, i.e. on the source files?

I do have a cloned copy, and have submitted one minor change from it.

However the webpages at

http://drking.webstarts.com/index.html

are a quick mock-up using (rather imperfect) html/css. To do this from the
docbook source would mean moving to my Ubuntu machine and, in the absence of the
instructions which I believe were once on the wiki, I'd expect to spend hours
getting the thing to generate html from docbook, and hours learning which
docbook tags are useful, and hours playing with gimp-doc style sheets. In other
words the technology is in the way.

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. 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? ;)

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.

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

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.

David

Sent: 2010-11-06 07:02:44 UTC (about 1 year ago)

From: David

a new user perspective

permalink

@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.

"Painting" suggests brushes, fill tools, etc to me. I wouldn't immediately look
there for help on selecting. I might possibly look under "Toolbox" I suppose,
having seen some of the selection tools, although that is on the 8th screen of
the current contents so I might miss it.

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 ;).

It's just my view of course...

D

Sent: 2010-11-08 19:39:27 UTC (about 1 year ago)

From: Ulf-D. Ehlert

a new user perspective

permalink

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. :-)

Bye,
Ulf

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

Sent: 2010-11-09 09:31:51 UTC (about 1 year ago)

From: David

a new user perspective

permalink

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

:)

> 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? ;-)

That *is* me, isn't it? ("a new user perspective")

>> 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.

Actually I was referring to the page content on eg the 'basic concepts' page,
where the writing and the pictures are closer together in my version than in the
existing version - allows you to see more on one screen

> (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.)

It would be, although even with 2 levels it would still miss basic concepts,
layers, selections. But that would be a vast improvement in my view :). And if
people could not find what they wanted from that, we'd know the structure was
wrong...

David

Sent: 2010-11-10 08:43:08 UTC (about 1 year ago)

From: Roman Joost

a new user perspective

permalink

Hi,

IMHO this should be discussed in a new thread, but anyway.

On Fri, Nov 05, 2010 at 07:04:31AM +0000, David wrote:
> In the spirit of contributing, I have mocked up a suggested new format for the
> html documentation at:
>
> http://drking.webstarts.com/index.html
>
> It merely shows the ideas. Most of the links don't work (only 'home' works for
> the navigation). Most of the pages aren't there (* in the contents = available).
Perhaps it would be a good idea to split up the documentation into two
books: the first would be a function reference and the second a more
helpful tutorial based manual. Currently the manual is a reference with
helpful tutorials.

After that you could address people who are just looking for a quick
help for a topic and people who would like to start working with GIMP
step by step.

Cheers,
--
Roman Joost
www: http://www.romanofski.de
email: romanofski@gimp.org

Sent: 2010-11-11 13:16:57 UTC (about 1 year ago)

From: David

a new user perspective

permalink

Hi Roman

> IMHO this should be discussed in a new thread, but anyway.

Up to you - but it results from my experience as a new user...

> Perhaps it would be a good idea to split up the documentation into two
> books: the first would be a function reference and the second a more
> helpful tutorial based manual.

Sorry - but I don't understand what you mean by 'function reference'. The
current 'function reference' section isn't - it contains menus, for example,
which are not functions. It may be a language/translation problem...?

What would you include if there was a book called 'function reference'? Would it
be different to the existing section (which is misnamed in my view)?

D

Sent: 2010-11-14 19:51:03 UTC (about 1 year ago)

From: Ulf-D. Ehlert

a new user perspective

permalink

David (Tuesday, 09. November 2010)
> > So shouldn't we ask someone who had never worked with
> > GIMP or had never tried to read the manual? ;-)
>
> That *is* me, isn't it? ("a new user perspective")

Are you kidding?! ;-)

> Actually I was referring to the page content on eg the 'basic
> concepts' page, where the writing and the pictures are closer
> together in my version than in the existing version - allows you
> to see more on one screen

(Oops, I didn't check the links...)
Yes, your Basic Concepts page looks fine. :-)

So we have several proposed improvements, and if I see it correctly
they are more or less independent of each other:

(1) Compact layout.
This is mostly a matter of the chosen style(sheet):
We (you?) could create an alternate stylesheet , e.g. "compact.css"
(starting with a copy of gimp-help-screen.css) and change text layout
etc. according to your suggestions. (And we can make it the default
stylesheet at any time.)

BTW, the HTML pages read "gimp-help-custom.css" if this stylesheet
exists (by default it does not), so that's a good place to apply and
test your changes in the real world.

(1.1) Floating images.
It seems that too ;-) many people like them, so we should provide a
way to enable floating images.
Of course it is possible to make *all* images (exception: icons)
float, but I'd prefer to add a modified DocBook-XSL template which
passes some attribute to HTML (e.g.
),
where we can select it with CSS.
Then we can control which images should float (I think the most
figures - especially large figures - should not).

I can add the appropriate changes for inlinemediaobjects - graphics
without title or caption. If needed we can do the same for
mediaobjects - graphics without title but with optional caption - and
figures - graphics with title and optional caption. Ok?

(Alternative approach: create an alternate stylesheet.)

> It would be, although even with 2 levels it would still miss basic
> concepts, layers, selections. But that would be a vast improvement
> in my view :). And if people could not find what they wanted from
> that, we'd know the structure was wrong...

(2) Compact tocs (without changes).
This is simple, just change the controlling xslt parameters. (If we
really do this, we should try to generate a deep toc as appendix or
so.)

(3) Rename some chapters.
Just list your suggested changes, and unless there are any
objections/problems we will apply them.

(4) Changed Basic Concepts.
Hmm, looks good to me - any comments?

(5) Rearrange (resort, merge, etc.) chapters (concepts and usage).
Looks good too. IMO we should try to implement and test this in a new
branch and see if we like it.

Bye,
Ulf

--
Allein bin ich manchmal einsam; mit anderen oft;
in Gesellschaft fast immer. Was mich mehr als alles
krank macht, sind die unheilbar Gesunden.
-- Karlheinz Deschner

Sent: 2010-11-15 08:48:12 UTC (about 1 year ago)

From: Roman Joost

a new user perspective

permalink

Hi David,

On Thu, Nov 11, 2010 at 01:16:57PM +0000, David wrote:
> > Perhaps it would be a good idea to split up the documentation into two
> > books: the first would be a function reference and the second a more
> > helpful tutorial based manual.
>
> Sorry - but I don't understand what you mean by 'function reference'. The
> current 'function reference' section isn't - it contains menus, for example,
> which are not functions. It may be a language/translation problem...?
Sorry for the use of my technical term.

> What would you include if there was a book called 'function
> reference'? Would it be different to the existing section (which is
> misnamed in my view)?
The current manual is currently two types of books. Part I and II is a
descriptive manual with tutorials. It describes how to do "things" with
GIMP.

The Part which is currently labeled or mislabeled as a "function
reference" is a reference for almost every item you can find in GIMP.
Perhaps "User Interface Reference" or simply "GIMP Reference" is more
descriptive.

Cheers,
--
Roman Joost
www: http://www.romanofski.de
email: romanofski@gimp.org

Sent: 2010-11-16 00:17:54 UTC (about 1 year ago)

From: Roman Joost

a new user perspective

permalink

Hi Ulf,

On Sun, Nov 14, 2010 at 08:51:03PM +0100, Ulf-D. Ehlert wrote:
> (1) Compact layout.
> This is mostly a matter of the chosen style(sheet):
> We (you?) could create an alternate stylesheet , e.g. "compact.css"
> (starting with a copy of gimp-help-screen.css) and change text layout
> etc. according to your suggestions. (And we can make it the default
> stylesheet at any time.)
>
> BTW, the HTML pages read "gimp-help-custom.css" if this stylesheet
> exists (by default it does not), so that's a good place to apply and
> test your changes in the real world.
Just keep in mind with those changes, that the GIMP Help browser uses
almost the same stylesheets. Perhaps it is not the desirable goal to
have a compact layout for the user who downloaded the manual or uses the
help browser to browse the manual.

Cheers,
--
Roman Joost
www: http://www.romanofski.de
email: romanofski@gimp.org

Sent: 2010-11-16 13:03:00 UTC (about 1 year ago)

From: David

a new user perspective

permalink

Thanks Ulf, Roman

>> (1) Compact layout.
>> This is mostly a matter of the chosen style(sheet):
>> We (you?) could create an alternate stylesheet , e.g. "compact.css"

Some of it can be done by stylesheet - for example perhaps, the empty space
around figures. But I suspect in practice a lot of what I'd like to see means
reducing image size on screen, and repositioning / floating some (but only some)
images so that the text flows round - in short getting the text near the image.

That would mean rewriting the docbook source - so it may be better to
concentrate on the other suggestions first?

To that end, I'll try to get the thing set up on my Ubuntu machine; may ask
privately for some help ;)

Re:
(2) Compact tocs (changing the controlling xslt parameters)
We currently display I.1.1.1, although it appears as
I
1.
1.
1.1

The most conservative change would be to remove just the last '1.1' - this alone
would save many screenfuls - any takers for that?

D

Sent: 2010-11-17 12:25:15 UTC (about 1 year ago)

From: Ulf-D. Ehlert

a new user perspective

permalink

Roman Joost (Tuesday, 16. November 2010)
> Just keep in mind with those changes, that the GIMP Help browser
> uses almost the same stylesheets. Perhaps it is not the desirable
> goal to have a compact layout for the user who downloaded the
> manual or uses the help browser to browse the manual.

As long as we experiment on alternate stylesheets there should be no
problem, the GIMP help browser doesn't use them.

If we eventually decide to switch to a more compact layout, we would
do this because we (all) think it's an improvement (for the users).
After all, without feedback we just can hope that users like what we
like...

Ulf

--
Die guten Christen sind am gefährlichsten - man verwechselt
sie mit dem Christentum.
-- Karlheinz Deschner

Sent: 2010-11-18 19:58:10 UTC (about 1 year ago)

From: Ulf-D. Ehlert

a new user perspective

permalink

David (Tuesday, 16. November 2010)
> Some of it can be done by stylesheet - for example perhaps, the
> empty space around figures. But I suspect in practice a lot of
> what I'd like to see means reducing image size on screen, and
> repositioning / floating some (but only some) images so that the
> text flows round - in short getting the text near the image.

Making (some) images float is easy. I'm going to commit the changes
below (see attachment) which enable floating for inlinemediaobjects
and mediaobjects without caption. All you have to do is to add the
attribute 'condition="float"' to the respective elements.

Bye,
Ulf

--
Nichts macht deutlicher, dass die Religion von Menschen erschaffen
wurde, als das kranke Hirn, das sich die Hölle ausdachte, ...
-- Christopher Hitchens, "Der Herr ist kein Hirte"