Re: Documentation tool proposal

[Phil Bull <philbull gmail com>]

Hi Anirudh,

On Mon, 2010-03-22 at 22:57 +0530, Anirudh Sanjeev wrote:
> Over the past few weeks, I've been designing and implementing a new tool to
> improve the quality and quantity of documentation for Gnome, by greatly
> enhancing the workflow of documentation.
> 
> It's called "Tuxtorial", soon to be in alpha at http://tuxtorial.com . It
> aims to crowdsource the creation of screenshot supplemented tutorials by
> means of a specialized clientside tool and a system to host them online.
[...]
> Clearly, this is a far superior method of creating documentation, and since
> all non-human elements of the workflow are eliminated, I'm speculating that
> less technically skilled people will be able to share their knowledge and
> upload to the site, which can pass community review, and eventually make
> it's way into yelp.

Thanks for letting us know about this. It looks like it could be a
really useful tool for a certain type of documentation, but we don't use
that type very much I'm afraid.

The annotated screenshot format is great for highly visual walkthroughs
(a good example would be an Inkscape tutorial), but for desktop help it
has limited utility. We tend to recommend using screenshots sparingly,
to provide high-impact illustrations which really clarify the text. They
are important for visual learners and we could definitely use them
better, but using them for absolutely everything is a bad idea.

The absolute deal breaker is the difficulty of making this sort of
format accessible to vision-impaired users. You just can't, without
writing the explanatory text. Then there are issues with visual overload
(too many images distracts from the important information) and file size
and bandwidth (this stuff often needs to fit on a CD). Trying to do
desktop help in this way doesn't mesh with the requirements of users -
most people are looking for one or two bits of information to help them
quickly fix a problem or find a feature, so they don't want to have to
scroll through tens of images to find what they need.

Please take a look at the Empathy help to see the direction we're taking
with the desktop help. We aim for short, to-the-point topics with simple
navigation, so that the user can spend as little time distracted from
their work as possible. Linear tutorials are often inappropriate for
this sort of thing.

I can think of some other places where your tool would be a good fit,
like in Inkscape tutorials as mentioned above. Complicated, linear,
multi-step instructions (like hard disk partitioning!) are suitable, I
think. It would be interesting to see what it can do for something like
that.

Thanks again,

Phil

-- 
Phil Bull
https://launchpad.net/~philbull