[MeeGo-SDK] SDK documentation system

[Felix Rommel]

Hello Adrian,

I send the points below with reference to the wrong e-mail. So here we 
go again:

= Collection extension for creating books =

I want to mention the following extension for MediaWiki where you can 
create a book with drag and drop and download it as PDF or editable ODT:

http://www.mediawiki.org/wiki/Extension:Collection

= Disadvantages of Wiki =

Nevertheless a Wiki has some disadvantages:

* No numbered labels for tables or images. so it's not possible to 
create hyperlinks to it easily (don't create numbers manually, that's 
too much work!).
* Headers are only numbered in table of contents but not numbered in the 
content.

= Printed documentation =

If you want to create printed documentation I don't think Wiki is the 
best choice. Otherwise a Wiki isn't that bad.

= Styleguide =

There should be created a styleguide for creating documentation in the 
Wiki. For example which formatting to use for product names. Otherwise 
you are lost if you use '''xyz''' for bold text for example for product 
names and want to change the appearance a few weeks later!

I have never seen in a Wiki that there were used stylesheets. But 
without that changing the appearance of hundreds of pages will be a 
nightmare or nearly impossible.

What do you think of the following:

Use of markup like the following in Wiki documentation:

  <span class="product">MeeGo</span> is a new operating system.
  <div class="hint">If you increase it will load faster</div>
  <div class="warning">Warning: It will get deleted instantly.</div>

Yes it will be harder to write but you will be able to distinguish more 
different text styles and change the appearance for hundreds of pages 
within a few seconds by changing the stylesheets.


Am 05.03.2010 12:59, schrieb Adrian Yanes:
> Hi there,
>
> For a long period of time, maemo.org has been used "Wiki" format to
> recollect the documentation related with Maemo OS.
>
> 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).
>
> 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.
>
> 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).
>
> What do you think?
>
> Regards,
>
> Adrian Yanes.
> _______________________________________________
> MeeGo-sdk mailing list
> MeeGo-sdk at meego.com
> http://lists.meego.com/listinfo/meego-sdk