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