No Subject

[Shaun McCance]

On Sun, 2010-04-04 at 06:09 +0530, Anirudh Sanjeev wrote:
> Hi Phil,
> 
> Thank you for your response.
> 
> Excerpts from Phil Bull's message of Sun Apr 04 04:40:25 +0530 2010:
> > 1. I agree that the tool would make it significantly easier for writers
> > to *create* screenshot walkthroughs, but what benefit will this have to
> > *consumers* of the tutorials? Are there any plans to subject initial
> > versions of the tool's output to usability testing?
> Since the tutorials are available in unformatted screenshot/text format, it
> will be trivial to export them into whatever means the user wishes to view
> them in - PDF, HTML, etc.
> 
> Also, my long term vision is to write a separate application which will be
> shipped along with Ubuntu which will solely be used for delivery. The user
> can search for help which will query the updated database and download all
> the documentation for consumption in an efficient and usable format.

Is this something that could just be built into Yelp, perhaps
as a plugin? I've already talked with other documentation teams
about making Yelp able to query the package manager for extra
documentation.

If the delivery format is something Yelp understands, then we
can just use it as a viewer. Then you can focus on building
tools for writers.

> > 2. Making documentation tools easier to use can encourage good
> > contributions, but it also makes it easier for inexperienced people to
> > create poor-quality work. You say that "less technically skilled people
> > will be able to share their knowledge"[1], but is it wise for people to
> > take advice from non-experts? How will users be able to find the
> > good-quality tutorials in amongst the low-quality ones which will
> > invariably appear?
> The answer for this is the same that ensures the Wiki model works. All
> tutorials can be subjected to peer review, commenting functionality will
> exist, and a user can "fork" the tutorial by downloading the project files
> and modifying them and re-upload correct version.

I just want to point out that the wiki model only works for
a very small percentage of the wikis in the world. For wikis
to work effectively, you must have people actively gardening
them. Otherwise they get crowded out by weeds.

> What I am not hoping to see is different distros, communities, languages,
> etc hosting their own copy of this which makes it eventually harder to find
> for someone looking for that information.

I understand your concern with this. We have the same sorts
of issues in Gnome, with distros overriding much of what we
do to keep users downstream.

But unless you keep the server completely closed, there will
be alternative installations. And if you keep it closed, then
either people won't use it, or they'll reverse engineer it.
Rather than fighting this, maybe you should investigate ways
to federate the content.

> > 7. How will internationalisation and accessibility be addressed?
> I am looking at the option of exporting .po files inside the project model,
> so users can open it in their favorite editor and modify it and all tools
> pick up this information.
> 
> Also, I am planning to add an option for the users to translate directly on
> the website. I like launchpad's approach, and might even consider directly
> trying to integrate with Launchpad when the time comes.
> 
> But the entire application will be written with i18n in mind.

The text portion is the easy part for translators. Taking
new screenshots is the hard part. Note that translators
aren't usually the expert users that the writers are, so
they might have to do a lot of setup to get to the point
where they can take equivalent screenshots.

The format you choose for storing the text can have an
impact on translations, though. As long as it's XML, and
you don't do anything silly like put translatable text
inside attributes, translators will be reasonably happy.

But there are some exceptional cases where some formats
shine over others. You should look at some of the things
Mallard does for translators (and I should finish writing
the documentation for those things). Or just use Mallard
as your underlying format.

--
Shaun McCance
http://syllogist.net/