[MeeGo-SDK] SDK documentation system
ronan.maclaverty at nokia.com
ronan.maclaverty at nokia.com
Mon Mar 8 09:31:18 UTC 2010
I think that we can all agree the Documentation/Maemo 5 Developer Guide is of good quality, and illustrate the power of user contributions. The point made about the need for a book for new members of the community is still valid; although the Qt documentation is very good most people I know have the C++ GUI Programming with Qt4 on their shelves).
IMO the issue is not a question of tooling but more of a content issue. The one thing that the Qt book has that the documentation does not, is that it gathers a range of APIs and uses them together to achieve a goal rather than focusing on APIs in isolation. We could take this approach for part of the content in the Meego wiki, to complement the Developer Guide.
The next question is what these should be and how should they be presented?
>On Fri, Mar 5, 2010 at 12:59 PM, Adrian Yanes <devel at ayanes.com> wrote:
>> Hi there,
>> For a long period of time, maemo.org has been used "Wiki" format to
>> recollect the documentation related with Maemo OS.
>What Quim is talking about is different. I think he is talking about
>the documentation as can be found AND edited here
>This part of the documentation is of a quality that way above any
>documentation I know of that can be found in a Wiki.
>If also is well formed and complete.
>> 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).
>Certainly and again this is somewhat different. The difference is the
>same as between a normal open source project that also has a wiki and
>the content of the wiki is checked (think wikipedia). In the first
>case anybody create pages edit's them a few times and goes on to doing
>In this case the wiki is the canonical source but this is also used to
>create "real" pdf documentation and there is QA.
>> It would very nice to prevent this kind of "error" and start to think
>> now in what type of doc system we have to use. To document the SDK.
>> Something like docbook (http://docbook.org/) would be a nice choice.
>As canonical source this makes it hard for people to contribute.
>> I am not talking about rule out the wiki ( of course not ). However,
>> more people would be looking for a big, complete and consistent (and
>> also with a nice printed output) documentation about MeeGoo SDK in the
>> next months and using this doc systems we will save time ( and also we
>> will reach the possibility to create books & e-books very easy).
>This is true and for producing quality,(centralized coherent)
>documentation one needs to have people dedicated to make the hole
>coherent and do things that don't
>happen on normal wiki (moving section etc). Using the Wiki as source
>doesn't mean there will not be other publishing formats available.
>> What do you think?
>I think it would be good to look at
>ttp://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide as example
>and see if you still have the same objections.
>MeeGo-sdk mailing list
>MeeGo-sdk at meego.com
More information about the MeeGo-sdk