Re: Nine Months in Six Months

[Alan Horkan <horkana maths tcd ie>]

On Sat, 9 Sep 2006, Shaun McCance wrote:

> Date: Sat, 09 Sep 2006 14:32:00 -0500
> From: Shaun McCance <shaunm gnome org>
> To: Nickolay V. Shmyrev <nshmyrev yandex ru>
> Cc: desktop-devel-list gnome org
> Subject: Re: Nine Months in Six Months
>
> On Sat, 2006-09-09 at 09:41 +0400, Nickolay V. Shmyrev wrote:
> > В Сбт, 09/09/2006 в 04:55 +0200, BJörn Lindqvist пишет:
> > > On 9/8/06, Don Scorgie <DonScorgie blueyonder co uk> wrote:

> > > > Doc people do not have enough time.  Its as simple as that.  As shaunm

> > > > I've known it.  Most of the docs are now pretty out of date.  Add in a

> > > * Five months were developers play and pretty much destroy all the
> > > docs we make.

Presumably this is not out of malice.  Developers who make the changes can
take another step beyond the changelog and flag exactly what needs to be
updated in the documentation and take out some of the guess work for those
interested in improving the documentation.

> > > * Four weeks were we can undo the damage caused and make GNOME
> > > understandable.

One of the ideas I considered in the past was that it should be easier to
post frequent documentation point releases.  If library.gnome.org ever
happens and we had an online copy, showing the most up to date version of
the documentation it would serve the same purpose, release early release
often.  The payoff for smaller improvements to the documentation would
increase.

> > > Maybe this problem can be solved by elevating the documentations and
> > > the translations status in the project? For example, patches are very
> > > seldom accepted if they introduce regressions in the software. But

Obviously we dont want to turn away contributors but most developers
require patches that more than barely work but that actually use the right
patch format, correct style/indentation, inlcude comments, and a changelog
entry.  This could be a small requirement if we figured the
right way to go about doing it.

> You'll notice one of the new things in my proposal
> was the idea of a string review.  There are a lot
> of crappy strings in our interfaces, often because
> many of our programmers just don't have very good
> English skills.

The supposedly native English speakers are among worst offenders because
they often dont even realise when they are using incomprehensible slang,
or when they "utilize" poor word choices instead of other suitable words
not requiring further localisation.

> And that's fine.  Hey, my German pretty much sucks,
> although I can get by with it.  I can't expect the
> world to have perfect English.  So we'll do some
> string reviews instead, where we can fix problems.

I dont think anyone is expecting perfection but it is not unreasonble to
expect spellchecking, it just isn't particularly convenient at the moment.

I think a docbook editor* which could do spelling and grammar checking
would help in a big way.  I was also thinking documentation is the perfect
source to run against GNU Style and Diction[1] (two programs barely anyone
seems to have heard of). It would be a big help if the Gnome documentation
project could decide on a quantifyable style level we were aiming for
against GNU style.

What makes the HIG so great is how it empowers** users users out there who
want a more usable and consistent Gnome, and gives them a good way to
express to developers more specific improvements they would like to see.
The right tools and perhaps better knowledge of the Gnome Documentation
style guide could help empower users to make things happen.

> I find myself shooting down this idea every single
> release cycle.

How do you think developers can make things easier for documentation
writers and conversely are there ways documentation writers can be helped
to give developers better feedback?  Your the expert, you must have
ideas?

Sincerely

Alan Horkan
http://alanhorkan.livejournal.com


[1] GNU Style and Diction
http://www.gnu.org/software/diction/diction.html

* The docbook support in Abiword has been substantially improved as part
of the summer of code but I do not know if that would be enough to make it
suitable to help with maintaining the Gnome documentation but I like
Abiword so I mention it anyway.

** Apologies for the bullshit buzzwords but sometimes they are
appropriate.



Sincerely

Alan Horkan

Inkscape http://inkscape.org
Abiword http://www.abisource.com
Open Clip Art http://OpenClipArt.org

Alan's Diary http://advogato.org/person/AlanHorkan/