[MeeGo-SDK] SDK documentation system

[Quim Gil]

Hi,

ext Adrian Yanes wrote:
> In my opinion, one of the most common failure in documentation and
> open source projects is that we use a doc systems easy to maintain for
> developers and easy to check for users, but sometimes we loose the
> "control" of them. When the project is very big , always a lot of
> people start asking about "a book" or "official manual", and this
> involves more consistent information ( the wikis can be tedious when
> we are talking about a lot of doc).

In terms of documentation, the difference is not between open source
projects and proprietary software projects. One difference is between
projects with doc writers appointed and projects where documentation is
that thing you do as a side, if you have time and will. You can also see
a difference between projects done for fun and projects that need happy
customers in order to be successful.

MeeGo is an open source project that in fact has significant
documentation resources available (Nokia + Intel + upstream
documentation to start with). It is also a project that needs commercial
success. For these reasons I believe we have the ingredients for
producing great developer documentation no matter what are the tools.

And we will have a community or open source developers, brave testers
and early adopters, happy to download and try out fresh meat released.
'Release soon, release often' can also apply to documentation. VCS is a
great tool for managing collaborative code, and wiki is a great tool for
managing collaborative writing. There is no DocBookpedia but there is a
successful Wikipedia, for a reason.

About structure, of course it is important! We can have a Table of
Contents that is agreed and maintained by someone, where someone new
don't just come and start adding their own things. The ToC can be
handled and improved during the release timeline, adding pages and
filling them with good content and links to the good sources. At some
point you release a beta and you can convert the ToC into a PDF with a
"BETA" label. At some point you reach MeeGo 1 final and then you can
release also a PDF export of the developer guide with a "1" label. etc.
In the meantime, the wiki pages show the latest info available. Google
knows that, developers searching for specific things know that.

See for instance
http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide  It's not
the best developer guide of the world but is useful enough for Maemo 5
developers and it contains plenty of improvements contributed by the
community during the alpha/beta phase, and after the final release.
Maemo 5 took us in the middle of the process of moving the master to the
wiki (before it was DocBook btw, so we know well the pain). For
Harmattan (and MeeGo if you are happy with the idea) we start from the
beginning with a wiki-centric approach, and a ToC that is organized by
areas (Multimedia, Location...) and use cases (how to embed an
interactive map, how to manage a music playlist...). Templates are
available so anybody in additional to the dedicated doc writers can
start a new use case. The use case template has also a structure
inviting contributions like links to additional code examples, tips and
tricks, external tutorials...

I guess this is clearer with concrete examples. Ronan wished me already
a nice weekend  ;) but next week he will show where are we with the
Harmattan documentation.

-- 
Quim Gil
open source advocate
Maemo Devices @ Nokia