[MeeGo-SDK] SDK documentation system

[quim.gil at nokia.com]

> > 2. It potentially bottlenecks production (though managing it through
> git
> > could reduce this, as people could supply patches or make branches to
> be
> > merged - but these tools are harder for technical writers).
> 
> If they are technical writers, so they know how to do a git commit &
> update repository won't be a difficult task. (and the benefits to use
> the git repositories in the doc is very good).

A 'technical writer' of the MeeGo developer guide can be any of the following:

- Someone that found a typo and wants to ammend.

- Someone that knows about a missing URL to an external useful resource and just wants to add it.

- Someone that got a useful tip in IRC or some mailing lists and wants to document it in the right page of the guide.

- Someone that wants to contribute a code snippet illustrating better the point.

- Even someone finding a page unclear or with missing information and willing to leave a comment in the discussion page (not optimal but again easier than sending an email to this list or file a bug).

You see the point. each of these actions alone are not that relevant to make a difference worth the hassle of publishing through wiki as opposed to the very efficient DocBook. But if you happen to get about 100 contributions from non-regular doc contributors during the months of unstable releases you start making a big difference.

A known risk to avoid is to have decent documentation not very simple to contribute, making casual contributors end up posting their knowledge in mailing lists and blogs. Then you are more in the hands of search engines and busy community experts remembering (if you are lucky) who answered your question somewhere some time ago.


-- 
Quim Gil + N900
open source advocate
Maemo Devices @ Nokia