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.
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!
> 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)
> - Document properties
> - Creating templates
> - Metadata
> - Selector
> - Navigation tools
> - Drawing tools
> - Transformation tools
> - Color tools
> - Text
> - Connector
> - copying and pasting (+ styles)
> - transformations
> - grouping
> - cloning
> - whatever else
> - you know what we need here
> - fill'n'stroke
> - swatches
> - color management
> - link to gradient tool
> - probably "clean up defs"
> - 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
> This approach has its own weak sides (e.g. where Icon Preview and XML
> editor should go), feel free to annihilate it :)
> 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