proposal for section reordering
This discussion is connected to the gimp-docs-list.gnome.org mailing list which is provided by the GIMP developers and not related to gimpusers.com.
This is a read-only list on gimpusers.com so this discussion thread is read-only, too.
proposal for section reordering | Axel Wernicke | 11 Feb 15:06 |
proposal for section reordering | julien | 12 Feb 07:59 |
proposal for section reordering | Axel Wernicke | 17 Feb 22:12 |
proposal for section reordering | Sven Neumann | 18 Feb 11:01 |
proposal for section reordering | Axel Wernicke | 18 Feb 11:27 |
proposal for section reordering | Roman Joost | 17 Feb 10:20 |
proposal for section reordering | Axel Wernicke | 17 Feb 22:47 |
proposal for section reordering
-----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-----
proposal for section reordering
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 Images3. 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 Guides3. Workflow concepts 3.6. Undoing
3.9. Brushes
3.10. Gradients
3.11. Patterns
3.12. Palettes
3.13. Text and Fonts4. Extension concepts 1. Plugins
2. Script-Fu5. Getting work done with GIMP 1. Getting an Image
1.1. Creating new Files
1.2. Opening Files
x.x. Scanning2. Creating and Using Selections 1. Using the Quickmask
3.1. Moving a Selection
3.2. Creating a Free Selection3. Working with Paths
4. Working with Layers
5. Drawing Simple Objects 2.1. Drawing a Straight Line
2.2. Creating a Basic Shape6. Working with Text in Images
7. Working with Digital Camera Photos
8. Scripting the GIMP 8.1 A Script-Fu Tutorial
9. Pimp my GIMP10. Storing Images 1.3. Saving Files for later
5. Preparing your Images for the Web x.x. Printing with GIMPWhat 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
proposal for section reordering
Hi Axel,
my apologize - I just haven't had the time to read and think about your proposal.
On Sun, Feb 11, 2007 at 03:06:18PM +0100, Axel Wernicke wrote:
[...] current status of the parts
So how the parts work today?
[...]The structure of the first part is today:
I. Getting started with The GIMP [...]
to make it short, I'd suggest the following structure instead (3rd level stripped for readability reasons): [...]
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: [...]
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.
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.
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.
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.
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.
What do you think Axel and the other authors? Axel, I think it will fit in nicely in your reorganization :)
Cheers!
proposal for section reordering
-----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. HelpB. 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 Images3. 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 Guides3. Workflow concepts 3.6. Undoing
3.9. Brushes
3.10. Gradients
3.11. Patterns
3.12. Palettes
3.13. Text and Fonts4. Extension concepts 1. Plugins
2. Script-Fu5. Getting work done with GIMP 1. Getting an Image
1.1. Creating new Files
1.2. Opening Files
x.x. Scanning2. Creating and Using Selections 1. Using the Quickmask
3.1. Moving a Selection
3.2. Creating a Free Selection3. Working with Paths
4. Working with Layers
5. Drawing Simple Objects 2.1. Drawing a Straight Line
2.2. Creating a Basic Shape6. Working with Text in Images
7. Working with Digital Camera Photos
8. Scripting the GIMP 8.1 A Script-Fu Tutorial
9. Pimp my GIMP10. Storing Images 1.3. Saving Files for later
5. Preparing your Images for the Web x.x. Printing with GIMPWhat 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
proposal for section reordering
-----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!
proposal for section reordering
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.
Sven
proposal for section reordering
-----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-----