Joshua Facemyer / Impressus Art <faceman@...1...> writes:

I think the things that need to happen first, though, are getting a sensible TOC worked out and then populating an xml file with the new TOC, then copying over the existing contents into the correct places.

[...]

However, if there is opposition do doing all this right now, please just tell me and I'll work on something different.

Not from my side. I was doing this so that you have a chance to get a feel for the po format etc. and can start with it as soon as the outline is ready. (You would then rename the pot file to en.po and start on that file.)

Cheers Colin

On 10/19/07, Joshua Facemyer / Impressus Art wrote:

Alexandre, do you have a TOC yet that you can post to the wiki page for discussion and comparison? I'm excited to see what you have, and get things started. I'm ready to do the work!

Hi,

Here is the idea.

Documentation is usually written in three styles:

1) A reference, which is used for context-sensitive help: fire up a dialog, press F1 and then you see a window, where every dialog's option is explained.

2) A book that goes from basics (e.g. what is vector graphics, what is different about Inkscape in comparison to Adobe Illustrator/Corel DRAW/Xara Xtreme/etc.) to difficult subjects (e.g. creating a reliable color managed PDF oriented workflow)

3) A book that provides detailed hints, i.e. task-oriented approach, i.e. tutorials.

What we currently have is:

- a manual in form of a book by Tav (1); - a manual that seems to have both 1) and 2), by Kevin and Cedric and Elisa; - a number of tutorials (3).

I have a deep respect for Tav and I would like to avoid as much duplication of efforts as possible. At least at this stage of Inkscape's development.

My suggestion is to try following GIMP way in two directions:

1) Create a TOC that has elements of (1), but is more like (2) so that both context sensitive help (whenever we have it) and book-like representation make sense.

2) Investigate possibility to have this context-sensitive help that is really a must for a mature application (which Inkscape already is).

Now this might reveal a question, how tutorials would fit this model. What I'm thinking about is: tutorials should concentrate on practical use of Inkscape only and give only basic theory if any. Most background knowledge should come from the manual. Ideally, whenever a user reads a large chapter and wants to experiment, there should be a tutorial on the subject for him to give a number of advices and illustrations and a lot of place to practice.

As for the currently suggested outline (http://wiki.inkscape.org/wiki/index.php/UserManualOutline), there I things I like and things I dislike.

Let's take toolbox. I disagree on grouping. This is a difficult thing to do and I don't claim to be a Absolutely Right Guy :) Why this is difficult: it's easy to separate most tools into three groups:

1) Drawing tools: rectangle, ellipse, 3D box, star, spiral, pencil, pen, callygraphic pen 2) Transformation tools: node tool, tweak tool 3) Color tools: bucket fill, gradient fill, eye-drop

But note three problems arising immediately:

1) Tweak tool has two modes that fit the 3rd group (color tools) 2) A number of tools can't be grouped: selector, zoom, text, connector, 3) Object->Transform... cries for inclusion into 2nd group :)))

How can we solve these 3 issues? Here is an idea.

1) Describe color related modes inside Tweak tool chapter, but reference those in Color tools section.

2a) Create a single chapter on selecting. Update corresponding tutorial to match most recent changes like touch selection and provide a couple of difficult real-life samples for users to practice using this feature, and link to this turorial from online reference.

2b) Create a single chapter on using Text tool.

2c) Create a chapter on navigating documents with subchapters for zooming and panning. Let panning be a virtual tool with many faces :)

2d) Create a separate chapter on Connector tool (or make it a Diagramming Tools chapter that describes Connector too only -- I don't like this approach though).

3) Describe Transformations dialog in chapter on handling objects and link to this chapter from Transformation Tools chapter.

Then we go to "Advanced Topics" and other sections. I'm not quite sure this is a good approach. Using Fill'n'Stroke dialog is by no means advanced topic ;-) and you can easily make up scenarios where oher part of advanced/supr advanced are required for not advanced use cases as well.

Here is my proposal. Inkscape already has a really well logically separated menu. We could just borrow from it. Then we would have something like this:

Basics (already outlined, needs some refinement)

Documents - Document properties - Creating templates - Metadata

Toolbox - Selector - Navigation tools - Drawing tools - Transformation tools - Color tools - Text - Connector

Objects - copying and pasting (+ styles) - transformations - grouping - cloning - whatever else

Layers - you know what we need here

Paths

Colors - fill'n'stroke - swatches - color management - link to gradient tool - probably "clean up defs"

Patterns

Effects - modification effects - raster effects - Live Path Effects - SVG filters - creating new effects (i.e. Python scripts tutorial)

Setting up Inkscape (Preferences)

Additional help resources - everything from Help menu - copy of - mailing lists

Here is why I separate two setting up topic (documents and preferences) this way. We definitely want our users be productive and transparently teach them to work the right way. Starting with understanding concept of documents and templates would imply that reusing is a good thing and the right way to go from scratch. At the same time tuning Inkscape via Preferences dialog implies some actual experience.

This approach has its own weak sides (e.g. where Icon Preview and XML editor should go), feel free to annihilate it :)

Alexandre

Alexandre,

You've put a large amount of thought and effort into this - thank you!

I really like what you've done. I had attempted to start with nothing and come up with a logical workflow outline, but you've done far more than that by addressing issues and problems you've been thinking about for a while.

I especially like the idea of making the manual available as a context-sensitive help file. I was considering the possibility, but in a different manner. I think this addresses it nicely.

Can you post this to the wiki (if you haven't already)? I think it's easier to review and comment if it's in a hierarchical format with some markup available for emphasis.

I'll try to get to it in the next couple of days when my head is a little clearer than right now.

JF

Alexandre Prokoudine wrote:

On 10/19/07, Joshua Facemyer / Impressus Art wrote:

...

Alexandre, do you have a TOC yet that you can post to the wiki page for discussion and comparison? I'm excited to see what you have, and get things started. I'm ready to do the work!

Hi,

Here is the idea.

Documentation is usually written in three styles:

1. A reference, which is used for context-sensitive help: fire up a

dialog, press F1 and then you see a window, where every dialog's option is explained.

2. A book that goes from basics (e.g. what is vector graphics, what is

different about Inkscape in comparison to Adobe Illustrator/Corel DRAW/Xara Xtreme/etc.) to difficult subjects (e.g. creating a reliable color managed PDF oriented workflow)

3. A book that provides detailed hints, i.e. task-oriented approach,

i.e. tutorials.

What we currently have is:

• a manual in form of a book by Tav (1);
• a manual that seems to have both 1) and 2), by Kevin and Cedric and Elisa;
• a number of tutorials (3).

I have a deep respect for Tav and I would like to avoid as much duplication of efforts as possible. At least at this stage of Inkscape's development.

My suggestion is to try following GIMP way in two directions:

1. Create a TOC that has elements of (1), but is more like (2) so that

both context sensitive help (whenever we have it) and book-like representation make sense.

2. Investigate possibility to have this context-sensitive help that is

really a must for a mature application (which Inkscape already is).

Now this might reveal a question, how tutorials would fit this model. What I'm thinking about is: tutorials should concentrate on practical use of Inkscape only and give only basic theory if any. Most background knowledge should come from the manual. Ideally, whenever a user reads a large chapter and wants to experiment, there should be a tutorial on the subject for him to give a number of advices and illustrations and a lot of place to practice.

As for the currently suggested outline (http://wiki.inkscape.org/wiki/index.php/UserManualOutline), there I things I like and things I dislike.

Let's take toolbox. I disagree on grouping. This is a difficult thing to do and I don't claim to be a Absolutely Right Guy :) Why this is difficult: it's easy to separate most tools into three groups:

1. Drawing tools: rectangle, ellipse, 3D box, star, spiral, pencil,

pen, callygraphic pen 2) Transformation tools: node tool, tweak tool 3) Color tools: bucket fill, gradient fill, eye-drop

But note three problems arising immediately:

1. Tweak tool has two modes that fit the 3rd group (color tools)
2. A number of tools can't be grouped: selector, zoom, text, connector,
3. Object->Transform... cries for inclusion into 2nd group :)))

How can we solve these 3 issues? Here is an idea.

1. Describe color related modes inside Tweak tool chapter, but

reference those in Color tools section.

2a) Create a single chapter on selecting. Update corresponding tutorial to match most recent changes like touch selection and provide a couple of difficult real-life samples for users to practice using this feature, and link to this turorial from online reference.

2b) Create a single chapter on using Text tool.

2c) Create a chapter on navigating documents with subchapters for zooming and panning. Let panning be a virtual tool with many faces :)

2d) Create a separate chapter on Connector tool (or make it a Diagramming Tools chapter that describes Connector too only -- I don't like this approach though).

3. Describe Transformations dialog in chapter on handling objects and

link to this chapter from Transformation Tools chapter.

Then we go to "Advanced Topics" and other sections. I'm not quite sure this is a good approach. Using Fill'n'Stroke dialog is by no means advanced topic ;-) and you can easily make up scenarios where oher part of advanced/supr advanced are required for not advanced use cases as well.

Here is my proposal. Inkscape already has a really well logically separated menu. We could just borrow from it. Then we would have something like this:

Basics (already outlined, needs some refinement)

Documents

• Document properties
• Creating templates
• Metadata

Toolbox

• Selector
• Navigation tools
• Drawing tools
• Transformation tools
• Color tools
• Text
• Connector

Objects

• copying and pasting (+ styles)
• transformations
• grouping
• cloning
• whatever else

Layers

• you know what we need here

Paths

Colors

• fill'n'stroke
• swatches
• color management
• link to gradient tool
• probably "clean up defs"

Patterns

Effects

• modification effects
• raster effects
• Live Path Effects
• SVG filters
• creating new effects (i.e. Python scripts tutorial)

Setting up Inkscape (Preferences)

Additional help resources

• everything from Help menu
• copy of
• mailing lists

Here is why I separate two setting up topic (documents and preferences) this way. We definitely want our users be productive and transparently teach them to work the right way. Starting with understanding concept of documents and templates would imply that reusing is a good thing and the right way to go from scratch. At the same time tuning Inkscape via Preferences dialog implies some actual experience.

This approach has its own weak sides (e.g. where Icon Preview and XML editor should go), feel free to annihilate it :)

Alexandre

---

This SF.net email is sponsored by: Splunk Inc. Still grepping through log files to find problems? Stop. Now Search log events and configuration files using AJAX and a browser. Download your FREE copy of Splunk now >> http://get.splunk.com/ _______________________________________________ Inkscape-docs mailing list Inkscape-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-docs

Hi,

"radar.map35@...6..." <radar.map35@...6...> writes:

It will be time to split the file and switch it to po.

I'll need few days or may be this WE.

I won't be here over the weekend, but if you want to play with xml2po, going into .../inkscape_svn/doc_docbook/basic/ and playing with the targets from the Makefile there gives you the options etc. needed - if you do "make -n <target>", it prints what it would execute.

I'll fix and extend the Makefile in user_manual after the splitting is done (which will probably lead to some renaming/moving of files to make this automatic stuff easier, but I'll announce that here before).

Joshua, are you in IRC or the Jabber room sometimes? It's quicker to do some things in near-realtime there. We often have pygmee and yemanja and prokoudine there, and I'm cmarqu (mostly away from the keyboard, but I can read the backlog).

Cheers Colin

Joshua, i'm often on IRC (it seems my pidgin can't use jabber now).

i often stay until midnight to 02:00 (french time). My nick is pygmee

pygmee.

Joshua Facemyer / Impressus Art <faceman@...1...> writes:

An idea I had - I may be able to set up a jabber chat room somewhere (since gristle isn't really working well for a lot of people) that we could use for docs. Would that be welcome? I'll look into it tomorrow early, if it's something you would want.

I'd rather have an extra IRC room, since I can idle in IRC all day, but not so for Jabber.

Cheers Colin