[maemo-community] The role of the docmaster

[From: Murray Cumming]

On Mon, 2009-05-25 at 12:52 +0200, Jarmo.Tikka at nokia.com wrote:
> 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/

This is a combination of all the existing documentation, right, as one
big PDF?

Or does this contain information or modifications that are not in the
regular API reference. For instance,
http://maemo.org/api_refs/5.0/beta/hildon/index.html

By the way, though I understand that big printable PDFs are useful and
important for certain customers, it really shouldn't be your priority.
The most important stuff is what google can find and what people can
paste as URLs when discussing the APIs.

>  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

The developers who are able to help you are used to editing DocBook XML,
gtk-doc and doxygen. The tools they use (library.gnome.org, DevHelp) use
these formats.

DocBook (and DocBook processors) has no particular problem with large
files.

DocBook is very standard and popular and can output to these formats
with fop (or one of the even-better proprietary processors). Well it
probably does not generate Mediawiki markup, because why on earth would
you want to generate content for a wiki. Generated content should not be
edited in the generated form.
 
I can probably help you to do what you need with DocBook.
And I sincerely hope that you are not thinking of forcing the gtk-doc
and doxygen content into latex.

> 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
[snip]

Sorry, but this is all so terribly wrong. I can only suggest that you
read my email again.

The main problem is that the content is currently not good enough. This
awful system is stopping us from identifying problems and fixing them.

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