[maemo-community] The role of the docmaster

[From: Murray Cumming]

At the risk of "me too"ing, I've been loosely involved in various random
parts of the Maemo documentation, and I've been a (often dissatisfied)
reader of the rest. The problems are totally fixable. These would be my
priorities:


1.
Get a library.maemo.org up and running ASAP, like library.gnome.org. It
would use mostly just published source tarballs.

That would end the weird practice of manual HTML uploads for each SDK
release, with different versions of the same documentation at various
random and unguessable URLs if they are uploaded at all.


2.
Get the Nokia documentation people to use standard tools, such as
DocBook XML, instead of half-generating stuff and then editing the HTML.
That means, find someone to order them to do it, because they aren't
figuring it out themselves so far - well some people are better than
others. If they don't use a sane process then nobody can contribute.

library.maemo.org would show them how this should be done so they don't
need to think about it.

And where they even want to work in the open this will give them a way
to do that.


3.
Widely publish direct links to submit Maemo documentation bugs in
bugzilla without needing people to guess their way through the
bugs.maemo.org maze to the correct product and component.


4.
Get native English speakers to review documentation. At best it is just
embarrassing - at worst it is incomprehensible. No non-native speakers
can write perfect English, no matter how good they think they are.


5.
Give the Nokia developers (and contractors) time to take documentation
bugs seriously. I know that they are currently not allowed to spend time
on them.


-- 
murrayc at murrayc.com
www.murrayc.com
www.openismus.com