[maemo-developers] Publishing developer documentation (was Re: The role of the docmaster)

[From: Quim Gil]

I have been silent on this thread about the role of the docmaster (even
if I started it). Couldn't find the words for my thoughts.

It is clear that we have structural problems to handle developer
documentation: its production, update, contribution, publishing methods,
quality...

First of all, let's remember the defined goals:
http://wiki.maemo.org/Objective:Co-production_of_official_%26_community_documentation

Some progress has been done patching the current processes, but for
further progress some deeper changes are needed.

First of all, we need to look at 3 very different types of developer
documentation:

- API references. Generated from source code. Their publishing and
contribution processes are as open and collaborative as their related
source code. No less, no more. Always on-line on HTML pages updated
directly from the code. The tools are specific, bug reports and code
repositories to commit contributions. Owned by Maemo Devices and
published in maemo.org. We have already contacted Fred Peters, creator
of http://library.gnome.org/ , to have a good solution in place by the
Maemo 5 final release. The quality is defined by valid references
(mapped to current code) and working code. The descriptions of the APIs
need to be clear and undestandable by developers.

- Technical documentation. The Maemo Reference Guide, derived directly
from the API references: what Maemo allows application and also platform
developers to do. Human readable but without much flourishing. Always
on-line with only a marginal case for printed versions. Wiki is an ideal
support for fast an easy contributions. Everybody can add feedback in
the Talk pages an contributors with special permissions can edit the
main content. Then something like
http://www.mediawiki.org/wiki/Extension:Pdf_Book could be used to allow
Nokia and whoever else to create PDF files directly out of the wiki
content, that would be the one and only source. This needs more
discussion and an agreement on how to proceed. Target: Harmattan since
we have a process in place already for Fremantle. Owned by Maemo
Devices. The quality criteria are the same as in API references + even
more accuracy in language and good provision of examples in the form of
graphics, code snippets and demo apps.

- Generic developer documentation. Tutorials, training materials and
other educational/introductory/marketing documentation. Derived mainly
from the technical documentation and ready to be published in many
formats, including videos, books, PDFs... Online editable formats e.g.
wiki pages can be possible too, but the default scenario are stable and
consolidated documents published once and updated only when really
needed. Improvements to be proposed via bug reports unless the specific
document has a more direct way to apply changes. The quality criteria
are the same as in the technical documentation with a special emphasis
in the language, the structure of the content, the visual appearance and
the cleverness of the content and the examples provided. Forum Nokia is
responsible of this kind of documentation, and they are getting ready
for this in Fremantle and even more in Harmattan & onwards.

I'm confident that we are doing the right steps in the API and generic
documentation. But more thought and perhaps a change of direction is
needed in the very important layer of technical documentation. If this
one doesn't work flawlessly inside Maemo Devices and in maemo.org then
Forum Nokia and the avantgarde of Maemo developers will have a much
harder time producing the generic documentation that most developers
(and specially newcomers, visitors, tech media etc) will look at.

As I see it, it's basic to have that technical documentation in a wiki
or a similar system easy to contribute and moderate. Now the axis is an
infrastructure ready for publishing PDFs and printed documents, but this
is imo a secondary use case compared to having the documentation online
with a process allowing fast and easy improvements.

The Maemo developer platform team and the Nokia internal developers
would start creating such technical documentation in an internal wiki
when needed (for instance now for the new components in Harmattan), and
as soon as those components would be published in unstable releases,
those wiki pages would be copied/moved to the public wiki, being used
and improved there by the same Nokia teams but also by the community
developers.

Then frozen versions on PDF could be created with the right wiki tool
when needed e.g. beta and final releases. This looks much easier and
efficient than trying to combine a Latex master maintained by Maemo onyl
with a wiki copy where contributions would be made. And the result would
be the same, or better: living docs in wiki pages useful for Nokia and
community developers + static exports of those docs frozen for specific
releases.

-- 
Quim Gil
open source advocate
Maemo Devices @ Nokia