-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1

Hi list,

right now I'm sitting here and take a look at the GIMP manual at whole. Today the manual is available in over a dozen languages. Thanks to the docbook technology we choose (and that each of us hates sometimes :) we are able to produce the manual as html book, online help and pdf. The pdf version is over 600 pages for english and some of the more completely translated languages.

This achievements prove that we as team did a good job so far! Gladly I take the chance to thank everybody for their passion to put the project forward step by step.

The manual consists today of three parts:

I. Getting started II. How do I become a GIMP wizard?
III. The GIMP function reference

The division of the parts was done almost exactly one year ago and I think it was a good decision, because we needed to separate the reference section from the First steps as well as from the tutorials.

I think the aim of the parts can be described as:

I. Get people started - with the manual as well as with GIMP

Getting started with the manual: - tell them who we are, about the project and how the GIMP-docs people are related to the GIMP folks - tell them how to access and read the manual / GIMP help

Getting started with GIMP: - tell them what is GIMP good for
- tell them what happend recently
- tell them how to get an own GIMP working environment - guide them through the first start of GIMP - tell them what they see when GIMP is running - tell them the very basics of what they can do with GIMP

II. How do I become a GIMP wizard?
GIMP concepts
- tell them about and explain the principles, ideas and structures behind GIMP

Working with GIMP - tell them how to use the power of GIMP by explaining techniques and fields of interest

III. The GIMP function reference

GIMP toolbox - tell them everything about the toolbox and all the tools

GIMP dialogs - tell them everything about the dialogs

GIMP commands - tell them everything about the menu entries (except tools, dialogs, filters)

GIMP filters - tell them everything about the filters

So how the parts work today?

From my point of view the reference part is pretty complete and very good usable as context sensitive online help as well as to read about a specific tool or filter. Some work is still to do for filters that are not explained yet or examples which would help to understand some of the commands, but the overall structure fits the needs.

For the other parts I think we need to think over the chapter and section structure once more - at least if we all agree to the aim for that parts as described above.

The structure of the first part is today:

I. Getting started with The GIMP 1. Introduction
1. Welcome to The GIMP
2. What's New in The GIMP?
2.1. Interoperability and standards support 2.2. Shortcut editor
2.3. Plug-in previews
2.4. Real-time previews of transform operations 2.5. GNOME Human Interface Guide conformance 2.6. GTK+ 2.4 migration
2.7. Basic vector support
2.8. Also . . .
3. Running GIMP
3.1. Command Line Arguments
3.2. Known platforms
3.3. Language
4. Starting GIMP the first time
2. GIMP Concepts
1. Main Windows in GIMP
1.1. The Main Toolbox
1.2. Image Window
1.3. Dialogs and Docking
2. Working with Images
2.1. Opening Images
2.2. Altering Images
2.3. Saving Images
3. Basic GIMP Concepts
3.1. Image types
3.2. QuickMask
3.3. Layers
3.4. Layer modes
3.5. The Selection
3.6. Undoing
3.7. Grids and Guides
3.8. Paths
3.9. Brushes
3.10. Gradients
3.11. Patterns
3.12. Palettes
3.13. Text and Fonts
3. Getting Unstuck
1. Stuck!
2. Common causes of GIMP non-responsiveness

to make it short, I'd suggest the following structure instead (3rd level stripped for readability reasons): I. Getting started with The GIMP
1. Introduction
1. Welcome to The GIMP project
2. What's New in The GIMP?

2. Fire up the GIMP 1. Running GIMP
2. Starting GIMP the first time
3. Main Windows in GIMP
4. Working with Images

3. Getting Unstuck 1. Stuck!
2. Common causes of GIMP non-responsiveness
As you can see, I'd relocate the concepts completely to part II. Although they describe GIMP basics, most of them are (and have to be) very detailed and technically. Much to complicated for the users first touch with GIMP. Instead I'd suggest to enhance the Working with Images section a bit for ONE step by step tutorial that is sexy and makes the reader "hot" for GIMP and the more detailed parts of the manual.

The most problems I've right now with part II. Today the structure is:

II. How do I become a GIMP wizard?

4. Concepts for the Intermediate 1. Plugins
1.1. Introduction
1.2. Using Plugins
1.3. Installing New Plugins
1.4. Writing Plugins
2. Using Script-Fu Scripts
2.1. Script-Fu?
2.2. Installing Script-Fus
2.3. Do's and Don'ts
2.4. Different Kinds Of Script-Fus 2.5. Standalone Scripts
2.6. Image-Dependent Scripts
5. Using GIMP as a Beginner
1. Files
1.1. Creating new Files
1.2. Opening Files
1.3. Saving Files
2. Drawing Simple Objects
2.1. Drawing a Straight Line
2.2. Creating a Basic Shape
3. Creating and Using Selections
3.1. Moving a Selection
3.2. Creating a Free Selection
4. Dialogs and Docking
4.1. Creating Docking Dialogs
4.2. Removing Tabs
5. How to Set Your Tile Cache

6. Using GIMP as an Intermediate 1. Using the Quickmask
2. Creating New Layers
3. Paths
3.1. Path creating
3.2. Stroking a Path
3.3. Transforming Paths
4. Working with Digital Camera Photos 4.1. Introduction
4.2. Improving Composition
4.3. Improving Colors
4.4. Adjusting Sharpness
4.5. Removing Unwanted Objects from an Image 4.6. Saving Your Results
5. Preparing your Images for the Web 5.1. Images with an Optimal Size/Quality Ratio 5.2. Reducing the File Size Even More 5.3. Saving Images with Transparency 6. Adding New Brushes
7. Using GIMP as an Expert
1. Text
1.1. Embellishing Text
1.2. Adding Fonts
1.3. Font Problems
2. Rendering a Grid
3. A Script-Fu Tutorial
3.1. Getting Acquainted With Scheme 3.2. Variables And Functions
3.3. Lists, Lists And More Lists
3.4. Your First Script-Fu Script
3.5. Giving Our Script Some Guts
3.6. Extending The Text Box Script 4. Creating Shortcuts to Menu Functions 5. The GIH dialog box
6. Creating a brush with variable size

I just can't follow the idea of making a 3 step difference between beginners, advanced users and experts. For sure these experience levels exist, but does it make any sense to differentiate the manual this way? Sure we have to build an entrance to GIMP for the absolute beginners, but is "sharpening an image" really a topic for an Intermediate while "Setting the tile cache" is for Beginners? I doubt so.
The question is now, how to reorganize all the great content we have already?
What about a structure that has a in depth concepts chapter and is in the rest of the part more "field of interest" oriented structured?

How about: II. How do I become a GIMP wizard?

4. Concepts 1. Image concepts
3.1. Image types
3.2. QuickMask
3.3. Layers
3.4. Layer modes
3.5. The Selection
3.8. Paths

2. User Interface concepts
x.x. Toolbox and image windows
x.x. Dialogs and Docking
3.7. Grids and Guides

3. Workflow concepts 3.6. Undoing
3.9. Brushes
3.10. Gradients
3.11. Patterns
3.12. Palettes
3.13. Text and Fonts

4. Extension concepts 1. Plugins
2. Script-Fu

5. Getting work done with GIMP 1. Getting an Image
1.1. Creating new Files
1.2. Opening Files
x.x. Scanning

2. Creating and Using Selections 1. Using the Quickmask
3.1. Moving a Selection
3.2. Creating a Free Selection

3. Working with Paths

4. Working with Layers

5. Drawing Simple Objects 2.1. Drawing a Straight Line
2.2. Creating a Basic Shape

6. Working with Text in Images

7. Working with Digital Camera Photos

8. Scripting the GIMP 8.1 A Script-Fu Tutorial

9. Pimp my GIMP

10. Storing Images 1.3. Saving Files for later
5. Preparing your Images for the Web x.x. Printing with GIMP

What do you think about this? May be we can use the time until 2.4 comes to life to sort this out and shuffle the sections around. Again - - I think all the content we wrote so far is valuable but needs a reordering for some sections and here and there the removal of redundancies.

Greetings, lexA

- --- Live is like a chocolate box, you never know what you wanna get... GPG Signatur auf http://wernicke-online.net/Impressum/ pr?fen

- --- Remember: There are only two tools in life. WD-40, for when something doesn't move, and should, and Duct Tape, for when something is moving and it shouldn't.
So does the universe explode if you spray duct tape with WD-40?

-----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.5 (Darwin)

iD8DBQFFzyLbR9mXLVsAbiQRApchAKDBA8cYuALEaTrFGOPzCw02QUUUgACgvGJU yjEm/kHK0t80TMAJAaZScak=
=Ao+y
-----END PGP SIGNATURE-----

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1

Hi Julien,

thanks for your thoughts about the structure of the reference section. In general I agree with you. With only one difference: The tools, as well as the dialogs[1] have a much more important than any command to show or hide rulers. Therefore I think they should not be placed at the very end of the part (as in your suggestion), but instead moved out of the pure menu structure and put at the very beginning of the reference part.

Greetings, lexA

[1] A dialog in GIMP is defined roughly as anything that is dockable. So, the dialog windows that pop up when you're saving a file or applying a filter are not dialogs for that definition.

Am 12.02.2007 um 07:59 schrieb julien:

You are right. The help is now (almost) complete, and we can have a general view over it.
I agree with the changes you propose.

My suggestion is about the GIMP function reference you didn't develop. I
think it must reproduce the Toolbox and Image menus : only one structure
for the interface and the help:

III- The GIMP function reference A. Toolbox Menu
1. File
2. Xtns
3. Help

B. Image Menu 1. File
2. Edit
3. Selection
4. Display
5. Image
6. Layer
7. Tools
8. Dialogs (only dialogs listed in this menu entry)

C.Filters

Greetings

Julien

To make it short, I'd suggest the following structure instead (3rd level stripped for readability reasons): I. Getting started with The GIMP
1. Introduction
1. Welcome to The GIMP project
2. What's New in The GIMP?

2. Fire up the GIMP 1. Running GIMP
2. Starting GIMP the first time
3. Main Windows in GIMP
4. Working with Images

3. Getting Unstuck 1. Stuck!
2. Common causes of GIMP non-responsiveness
II. How do I become a GIMP wizard?

4. Concepts 1. Image concepts
3.1. Image types
3.2. QuickMask
3.3. Layers
3.4. Layer modes
3.5. The Selection
3.8. Paths

2. User Interface concepts
x.x. Toolbox and image windows
x.x. Dialogs and Docking
3.7. Grids and Guides

3. Workflow concepts 3.6. Undoing
3.9. Brushes
3.10. Gradients
3.11. Patterns
3.12. Palettes
3.13. Text and Fonts

4. Extension concepts 1. Plugins
2. Script-Fu

5. Getting work done with GIMP 1. Getting an Image
1.1. Creating new Files
1.2. Opening Files
x.x. Scanning

2. Creating and Using Selections 1. Using the Quickmask
3.1. Moving a Selection
3.2. Creating a Free Selection

3. Working with Paths

4. Working with Layers

5. Drawing Simple Objects 2.1. Drawing a Straight Line
2.2. Creating a Basic Shape

6. Working with Text in Images

7. Working with Digital Camera Photos

8. Scripting the GIMP 8.1 A Script-Fu Tutorial

9. Pimp my GIMP

10. Storing Images 1.3. Saving Files for later
5. Preparing your Images for the Web x.x. Printing with GIMP

What do you think about this? May be we can use the time until 2.4 comes to life to sort this out and shuffle the sections around. Again - - I think all the content we wrote so far is valuable but needs a reordering for some sections and here and there the removal of redundancies.

Greetings, lexA

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1

Hi Roman,
Am 17.02.2007 um 10:20 schrieb Roman Joost:

Hi Axel,

my apologize - I just haven't had the time to read and think about your
proposal.

No problemo. Thinking is indeed very important at this point.

[...]
I just can't follow the idea of making a 3 step difference between beginners, advanced users and experts. For sure these experience levels exist, but does it make any sense to differentiate the manual this way? Sure we have to build an entrance to GIMP for the absolute beginners, but is "sharpening an image" really a topic for an Intermediate while "Setting the tile cache" is for Beginners? I doubt so.

Hm yes - we don't have to point out this too explicitly. Actually I think it became convenient to structure it like it is now. By splitting
the content into something for beginners, intermediate and advanced users we try to provide some kind of orientation for our readers.

No doubt we need some kind of kick fo for the users to get a feeling for GIMP in - lets say installation + 2 hours.

- -> Part I needs a very sexy chapter to get the first time user falling in love with GIMP. Some kind of "never as good as the first time" thing, you know :)

- --> Anybody any suggestions for the content of that? It should be something not to advanced but impressive that most of our users can identify with.

How about:
II. How do I become a GIMP wizard?
[...]

I like the idea of a reorganisation, but let me post my thoughts about one too.

In short: I found it very handy to reading a section which assembles some concepts and tutorials. Because it kept me going to handle something complex.

[x] agreed

A few weekends ago, I found a very complex flight simulator (Falcon 4.0) in my cupboard which I bought several years ago but never got into
it. It features a very big manual (ow... the good old times where games
were shipped with printed manuals ;) and the way the authors trying to teach you flying a F-16 Fighting Falcon is very interesting. Not that I
want to compare GIMP with an airplane, but navigating and using might be
quite similar. In fact, both things are very complex.

Yeah, but crashing GIMP or an image doesn't hurt so much as smashing an F-16 into a rock :)
Btw. I've been reading in a PS 5 manual, as well as in some M$ Word / Excel manuals, a book about FrameMaker and an XPress manual -> each of them has a different approach. None of them has a reference part as we do (and which we can very proud of I think) and the ones that tried to explain the how to work with xy while explaining one command after another where as far the worst.

All of the more recent manuals do try to tell kind of a story. Specially Apples Manuals are all kind of "how do I get the job xy done" manuals. Even if they do not explain each and every command, they give you a very good feeling of how things work.

The overall structure of one chapter is like this:

1. They teach you several concepts, like what's displayed in the cockpit (incl. screenshots).
2. Followed by one or two tutorials where you need to use the concepts learned in the sections before.

Why not reorganizing our current first parts like this? For example:

1. Teach the user about what the main windows in GIMP are. 2. Tell him how to open new images or navigate and the like.

I can imagine that very well. So, we should identify a number of "fields of interest" or "main topics" may be some kind of user profile could help here. Didn't the usability efforts create something like that already?
After - and I mean AFTER - we got an idea of what the overall structure of part II should look like, we should reorder the content we already have. That needs to be clustered to the identified main topics. Afterwards we need to make sure that the transitions within each topic are smooth.

We can adjust the granularity of this. Of course you won't tell a beginner all the dirty little tricks you can do with GIMP in the first place. Just rise the level of experience you need with the chapters of concepts and tutorials.

[x] Agreed

What do you think Axel and the other authors? Axel, I think it will fit
in nicely in your reorganization :)

Yeah, kind of like it. How shall we progress?

Suggestion: (one more)

1. Get our hands on the user profiles (if there are any)

2. Identify the relevant main topics (guess we should limit ourself to 10 or less of them)
- -> Write a raw description of what should be part of the topic

3. scan through the tutorials and concepts we have today in Part I and II and relocate them one by one to the new topics

4. Identify what's missing in the topics of Part II

5. Write the sexy thing for Part I

6. Fill the gaps in Part II

7. Take a rest :)

So, how about that?

Greetings, lexA

Cheers!

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1

Hi,

Am 18.02.2007 um 11:01 schrieb Sven Neumann:

Hi,

On Sat, 2007-02-17 at 22:12 +0100, Axel Wernicke wrote:

[1]
A dialog in GIMP is defined roughly as anything that is dockable. So, the dialog windows that pop up when you're saving a file or applying a filter are not dialogs for that definition.

Actually, pretty much every window in GIMP is called a dialog. It would
probably be nice to come up with a better name for the dockable dialogs.

Usually a dialog is something modal. It pops up to allow the user to complete a certain task and closes again. Windows that stay around like
the dockable dialogs in GIMP are often called palettes. For some reason
though they are called dialogs in GIMP. Perhaps we should consider to change that at some point.

Well (many) other applications call such "palette". Don't they?! I would be more than happy to see this changed. But for now I think we need to make a difference between dialogs that should be named palettes and dialog windows that is what we call these modal windows.

lexA

Sven

- ---
Remember: There are only two tools in life. WD-40, for when something doesn't move, and should, and Duct Tape, for when something is moving and it shouldn't.
So does the universe explode if you spray duct tape with WD-40?

-----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.5 (Darwin)

iD8DBQFF2Cn4R9mXLVsAbiQRAp8cAJ96hNDUj2VVSYgRTWALBGf51UeSlACfdb72 Lqbk5g5QiTUolPAWqC2ayT8=
=7NFV
-----END PGP SIGNATURE-----