[maemo-community] maemo-community Digest, Vol 32, Issue 22

[From: Jarmo.Tikka at nokia.com]

Hi,

As an acting maemo doc manager (and when I now had time to read also this mailing list) I added my comments to this thread.

Let me start by saying that you had very good points below Murray!!

Date: Mon, 25 May 2009 10:11:47 +0200
From: Murray Cumming <murrayc at murrayc.com>
Subject: Re: The role of the docmaster
To: List for community development <maemo-community at maemo.org>
Message-ID: <1243239107.10207.7.camel at murrayc-desktop>
Content-Type: text/plain

On Tue, 2009-05-19 at 14:56 +0200, Murray Cumming wrote:
> 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:
> 

My priorities have been following (since about year and half ago e.g. since Chinook).

1. Cleanup existing Chinook documentation for Diablo
 - end result for that was Diablo Reference Manual and example apps in Garge
 http://maemo.org/maemo_release_documentation/maemo4.1.x/
 https://garage.maemo.org/svn/maemoexamples/tags/maemo_4.1/
 - base reference manual to the example applications so that all example code used in manual is testable

2. Rise Diablo release documentatin about to the same level as Chinook/Diablo training material was
 - e.g. Diablo Reference Manual (release documentation) was based mostly to the training material
 - existing separate Chinook how-tos were (somewhat) unified and added to the Reference Manual

3. Create documentation infrastructure that can handle very big documents and is independent from format that is used to publish documents
  - Diablo Reference Manual and Training Material is now in Latex format and Latex can handle very big documents 
  - From latex we are able to generate all needed release formats e.g. for Frementle we are able to release same docs wit high quality as PDF docs, HTML docs and MediaWiki docs.
  - next output format will be Eclipse xhtml

4. Allow maemo community to contribute maemo docs in future and still release official reviewed versions
  - plan is that we release prereleases from maemo documentation together with SDK prereleases in maemo.org wiki so that maemo community can contribute
  - plan is that official (final releases) for docs are releases as HTML docs in Midgard (snapshots for final releases)
  - plan (in future when we have latex -> xhtml conversion done) is that official (final releases) for docs are releases as Eclipse XHTML to gether with Eclipse Integration

Current status is that we are cole to have this new doc infrastructure ready and I hope we are able to test releasing parts of Fremantle Reference Manual (those parts that have initially reviewed by Nokia teams so that there are no totally wrong docs) in maemo.org MediaWiki sometimes soon.

In future I plan to release also latex infrastructure we use so that people outside Nokia are able to regenerate our docs if needed. I am still developing this infra so this will not happen anytime soon.

Some more comments below...

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

Having library.maemo.org as one service we pubish our official documentation sound very good. It needs to support either Midgard HTML or plain HTML/PDF as publishing format.

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

With Chinook we used to edit html docs (as Midgard text editor is not very good) but since Diabloo we have edited latex instead :).

DocBook was considered yuear ago but as it does not allow different publishing formats (and I was not sure how big documents it can really handle) we ended up using latex. Also OppenOffice Writer (and couple of other tools were considered) but as they really are not true documentation management tools we ended up using latex.

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

Any comments and porposals what to do better are very wellcome.


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

I think bugs.mameo.org has components for documentation. Any exact proposals how to change bugzilla structure to better serve managing documentation bug are also welcome.

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

This is true. I concentrated cleaning up doc infra and content and I did nto have time to do language check to the final Diablo Reference Manual. We will do better on this respect for Frementle manual.

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

This is one reason we have not published Frementle Manual yet with beta SDK. First reviews are still ongoing...

Thanks again about good comments Murray (and interes on maemo documentation) !!

Cheers,
//Jarmo


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