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 _______________________________________________ maemo-developers mailing list maemo-developers@maemo.org https://lists.maemo.org/mailman/listinfo/maemo-developers
