maemo.org Bugzilla – Bug 101
Use the wiki for developer documentation
Last modified: 2010-05-17 16:39:14 UTC
You need to
before you can comment on or make changes to this bug.
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.
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.
Changing target milestone and assigning.
Reassigned to Ferenc
We will shortly move from the old XML based documentation to the new and fresh
Midgard CMS . 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' :)
Quim, you might want to be interested in this bug.
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.
(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
(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
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:
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. :)
Juha is our new doc manager. :) Reassigning to him. Juha, let's discuss this
once you have somewhat landed.
"Ready for landing". Let's discuss what this issue is all about ;)
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
(removing ancient target milestone)
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.
Just update for this report: We now have official Diablo release documentation
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.
Jarmo: she's all yours.
@coment #7 bby Quim:
Someone's a 1984 fan.
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
I am interested in an asciidoc->Mediawiki approach which allows controlled
asciidoc sources to be imported and discussion comments to be added.
fwiw this is now a task listed at
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.
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.
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.
fwiw after the Fremantle Beta 2 release we have
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!
[Rearrangement of Documentation bug reports.]
Mass-moving old closed Developer Platform > Documentation tickets.
You can filter bugmail by searching for this comment.