[maemo-community] The role of the docmaster

[From: Dave Neary]

Hi,

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

...

> 2.
> Get the Nokia documentation people to use standard tools, such as
> DocBook XML, instead of half-generating stuff and then editing the HTML.

...

(Just to point out that 2 would have to happen before 1)

Along with these 2, there is one other which I would like to see happen, 
but I'm not sure where to start with it, which is related to your next 2 
suggestions:

> 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.

I would like to see documentation managed in a public subversion 
repository, with a clearly documented process for submitting diffs, 
"building" the docs, etc. Currently, the official docs are published as 
static HTML + PDF - even if we do build up a group of proof-readers and 
improve the reporting of bugs against documentation (which, to be 
honest, I don't think is terrible right now), I'm currently in a 
situation where I don't really know what to do with bugs to official docs.


My top priority, having drifted away from docs over the past months, is 
to get a good understanding of how the official docs team works, and 
figure out how to move to creating the docs in a public svn. As I said 
previously, an important step towards true co-production is that the 
official documents be created in a publicly accessible system, with 
tools, norms and procedures all publicly available and documented.

That is my first and top priority. A publishing system for 
auto-generated docs (library.maemo.org) would be the second.

Apologies for the delay in replying to your mail Murray - I was working 
on another project last week, which then ran into a long weekend here in 
France.

Cheers,
Dave.

-- 
maemo.org docsmaster
Email: dneary at maemo.org
Jabber: bolsh at jabber.org