Bug 101 - Use the wiki for developer documentation
: Use the wiki for developer documentation
Product: Developer Guide
maemo.org wiki
: unspecified
: All Linux
: Medium enhancement (vote)
: 5.0-final
Assigned To: Jarmo Tikka
: Ferenc Szekely
: 1877
  Show dependency tree
Reported: 2005-10-10 12:50 UTC by Tomas Junnonen
Modified: 2010-05-17 16:39 UTC (History)
6 users (show)

See Also:



You need to log in before you can comment on or make changes to this bug.

Description Tomas Junnonen (reporter) nokia 2005-10-10 12:50:50 UTC
The Maemo.org SDK tutorial is huge and filled with bad grammar. It is also
written as a monolithic document without links to other available resources such
as the application installer documentation, causing overlap. Finally, having to
mail your changes to maemo.org and learning the Apache Forrest format is a huge
barrier that few contributors will care enough about to overcome.

I propose that all the developer documentation be moved to the Maemo Wiki in
order to solve these problems. This would ideally be done so that first the
existing content is replicated "as is" in the Wiki, divided into logical pieces,
and finally the old documentation is removed. When the content is in the Wiki it
will be easy to contribute new tutorials and review the grammar.
Comment 1 Erkko Anttila nokia 2005-11-01 09:36:24 UTC
Moving the tutorial into a Wiki document is a great idea. Even now if you want
it is possible to check out the website XML and thus get the source of the tutorial.

We could try to inniate this through the community, but i dont think its going
to happen yet and internally we dont really have the resources to do this at the
moment. The idea is great and would really improve the documentation, resources
for doing it is the problem.
Comment 2 Ferenc Szekely maemo.org 2006-01-12 15:11:52 UTC
changing target
Comment 3 Maemo QA (deprecated) 2006-04-18 12:48:01 UTC
Changing target milestone and assigning.
Comment 4 Jake Kunnari 2006-12-28 16:12:29 UTC
Reassigned to Ferenc
Comment 5 Ferenc Szekely maemo.org 2007-01-29 22:30:20 UTC
We will shortly move from the old XML based documentation to the new and fresh
Midgard CMS [1]. Authoring documents will be a lot easier and hopefully the long
and bloated Maemo Tutorial will be split into smaller, more manageable sections.
I am not responsible for the document itself, but I can tell you that the
infrastructure will support easy and quick editing.
I personally don't think that all the developer docs will be moved to wiki.
Midgard offers a nice, browser based editor with a lot of feature concerning the
layout. Unfortunately the wiki does not really meet these features yet. The
possibility of moving the docs is there however, so I mark this bug to an
optimistic 'Later' :)

[1] http://test.maemo.org
Comment 6 Ferenc Szekely maemo.org 2007-05-07 00:56:00 UTC
Quim, you might want to be interested in this bug.
Comment 7 Quim Gil nokia 2007-05-07 08:28:07 UTC
Bug 101!!!!

Thanks, yes I'll take it. All the official developer documentation needs to be
under Development and out of the wiki, whnich is a communioty tool. Now we face
a transition period with two processes:

- Each maemo component needs to have at least one web responsible who is
working directly with that component, instead of going everything through the
web admins. For example Hildon documentation will be maintained by the Hildon

- A doc manager will join us one of these days (really, we found him!). He will
make sure that everything is consistent, comprehensive, without missing pieces.
He will need to learn at the beginning and everything but justa the fact of
having someone concentrated in documentation at maemo.org will help a lot.
Comment 8 Jussi Kukkonen 2007-05-08 15:42:21 UTC
(In reply to comment #5)
> I personally don't think that all the developer docs will be moved to wiki.
> Midgard offers a nice, browser based editor with a lot of feature concerning
> the layout. Unfortunately the wiki does not really meet these features yet. 
> The possibility of moving the docs is there however, so I mark this bug to an
> optimistic "Later" :)

I'm not sure if Midgard-based documentation means write-access to the general
community? I don't really care about the format, but I would like to state my
support for more general write-access. It's quite hard to convince oneself to
write a bug report on a simple flaw in a document (something that one could fix
in 5 seconds), especially knowing that similar bugs are turning 1 years old in
the bugzilla...

(In reply to comment #5)
> A doc manager will join us one of these days (really, we found him!). He will
> make sure that everything is consistent, comprehensive, without missing 
> pieces.
I'm sure you know as well as anyone that this is impossible. Documentation is
_always_ lousy, too old or missing (this is probably a yet-unfound law of
nature). A doc manager will no doubt help, but the law will still stand...

If you are not ready to give full edit-access to all maemo.org accounts, maybe
there are other alternatives:
 * allow editing for all, but require confirmation by "doc manager" 
   (this isn't much better than current bugzilla)
 * give edit-permissions to users on request
   (see Mozilla bugzilla permission upgrade advice: 
Comment 9 Quim Gil nokia 2007-05-10 18:01:02 UTC
An element to think:

maemo is a project sponsored by Nokia and the official documentation is a
product Nokia responds of. At some point this official documentation is going
to be packaged in proper (and hopefully nice-looking) documents, delivered to
developers for training purposes, delivered to partners and software companies
to develop software for the tablets... We are already doing most of this but we
want to improve and put better quality control and guarantee.

This is a reason why we can't open the editing of the official documentation at
the same level as the community docs aka wiki.

Said that, I totally agree with you that fixing one line is trivial and many
people would help while filing a bug is boring and unefficient. As said
previously somewhere, perhaps we need a notation system à la GPL3 discussion,
or a similar system.

I won't comment more on this until a) the big issues in the wiki are solved and
b) the doc manager has joined. After a+b are solved this will move forward
pretty fast, I tell you. We will share plans and ideas with the community,
since you are the audience number one.  :)
Comment 10 Quim Gil nokia 2007-06-04 10:35:05 UTC
Juha is our new doc manager.  :)  Reassigning to him. Juha, let's discuss this
once you have somewhat landed.
Comment 11 Juha Tukkinen nokia 2007-06-18 09:27:19 UTC
"Ready for landing". Let's discuss what this issue is all about ;)
Comment 12 Dave Neary maemo.org 2008-06-10 18:28:38 UTC
You can follow the progress of this bug at
http://wiki.maemo.org/Maemowiki_Action_Group and the categorisation/review of
old content in the categorization page at

If you would like to review and edit content pages migrated from the Midgard
wiki and not yet reviewed are gathered together at
Comment 13 Andre Klapper maemo.org 2008-06-17 18:07:30 UTC
(removing ancient target milestone)
Comment 14 Quim Gil nokia 2008-06-19 10:19:43 UTC

About the official documentation, the plan is 

- To release the Diablo documentation still in the old way (with improvements:
all HowTos are now published under a Maemo reference guide).

- To move the official documentation to the MediaWiki putting clear banners
stating that this is Nokia documentation in-progress and referring to the web
pages / PDF with the latest stable version. These pages would be immutable and
users can post their comments in the discussion page.

- The docs in the wiki would be updated there for Fremantle and once they are
considered final a new PDF would be extracted from the wiki pages and released
by Forum Nokia, the entity to handle all the official Nokia delivers (so
maemo.org can go fully community-driven).

There are some challenges dealing with the current DocBook/Latex format of the
documentation and WikiMedia, though. We will look at this during the Summer and
hopefully all problems will be solved at the end.
Comment 15 Jarmo Tikka nokia 2008-06-26 14:37:54 UTC
Just update for this report: We now have official Diablo release documentation
here: http://maemo.org/maemo_release_documentation/maemo4.1.x/

This (maemo Manual) covers all release specific documentation for Diablo
release. Documentation is now Latex based e.g. we generate docs from origin
Latex files (as html and PDF). Next we will make an study are we able to import
release docs better to the Midgard and MediaWiki. Based on these studies we
will decide how docs will be published in future.
Comment 16 Dave Neary maemo.org 2008-06-30 22:37:07 UTC
Jarmo: she's all yours.

Comment 17 Kyle Jones 2008-07-17 09:51:51 UTC
@coment #7 bby Quim:

Someone's a 1984 fan.
Comment 18 David Greaves 2008-07-17 10:39:41 UTC
This python based tool is used by several projects, notably 'git' the kernel
version control system.

The focus is (clearly) on the text, not the rendering. Having said that, it
renders to almost everything useful: PDF, XHTML, HTML Help, manpage, plain text
and LaTeX.


I am interested in an asciidoc->Mediawiki approach which allows controlled
asciidoc sources to be imported and discussion comments to be added.
Comment 19 Quim Gil nokia 2008-08-09 00:47:38 UTC
fwiw this is now a task listed at
Comment 20 Andre Klapper maemo.org 2008-10-30 18:52:13 UTC
Moving Documentation component from maemo.org to Development Platform since the
bugs there refer to official developer documentation and this falls out of the
responsibility of the community.
Sorry for the noise, you can filter your bugmail by searching for this comment.
Comment 21 Jarmo Tikka nokia 2008-11-27 15:04:53 UTC
We now have new Latex based infrastructure for official maemo documentation.
Implementation to integrate docs to Midgard are still ongoing (importing html
docs with Midgard docimport) as are import to MediaWiki for community support.
Bookmarked anyhow link to AsciiDoc. 

Closing this bug.
Comment 22 Dave Neary maemo.org 2009-06-02 11:54:22 UTC
Let's close this bug when we have a system in place & in use by the community.

Given that we don't yet have any plan for keeping the documentation sources in
sync with the wiki I'm not convinced that this problem has been completely
solved, or that no more discussion is needed.

I'll follow up with a more detailed comment in a little while.
Comment 23 Quim Gil nokia 2009-08-04 15:22:30 UTC
fwiw after the Fremantle Beta 2 release we have
Comment 24 Quim Gil nokia 2009-09-14 09:16:15 UTC
The current process is based on the fact that wiki.maemo.org is the master
location from developer documentation during the unstable releases. From there
the stable versions are exported to PDF and other formats.

We can finally resolve this old report as FIXED!
Comment 25 Andre Klapper maemo.org 2010-05-17 16:39:14 UTC
[Rearrangement of Documentation bug reports.]
Mass-moving old closed Developer Platform > Documentation tickets.
You can filter bugmail by searching for this comment.