Comment 1 Erkko Anttila 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 2006-01-12 15:11:52 UTC

changing target

Changing target milestone and assigning.

Reassigned to Ferenc

Comment 5 Ferenc Szekely 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 2007-05-07 00:56:00 UTC

Quim, you might want to be interested in this bug.

Comment 7 Quim Gil 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
developers.

- 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
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: 
   http://www.gerv.net/hacking/before-you-mail-gerv.html)

Comment 9 Quim Gil 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 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 2007-06-18 09:27:19 UTC

"Ready for landing". Let's discuss what this issue is all about ;)

Comment 12 Dave Neary 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
http://wiki.maemo.org/MAG:Categorization

If you would like to review and edit content pages migrated from the Midgard
wiki and not yet reviewed are gathered together at
http://wiki.maemo.org/Category:Midgard_wiki

Comment 13 Andre Klapper 2008-06-17 18:07:30 UTC

(removing ancient target milestone)

Comment 14 Quim Gil 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 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 2008-06-30 22:37:07 UTC

Jarmo: she's all yours.

Dave.

@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
and LaTeX.

http://www.methods.co.nz/asciidoc/

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 2008-08-09 00:47:38 UTC

fwiw this is now a task listed at
https://wiki.maemo.org/Objective:Co-production_of_official_%26_community_documentation

Comment 20 Andre Klapper 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 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 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 2009-08-04 15:22:30 UTC

fwiw after the Fremantle Beta 2 release we have
http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide

Comment 24 Quim Gil 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 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.