Re: Publishing developer documentation (was Re: The role of the docmaster)
Hi, Quim Gil wrote: First of all, let's remember the defined goals: http://wiki.maemo.org/Objective:Co-production_of_official_%26_community_documentation One of the issues I've had is separating goals and means to attaining those goals. Co-production of documentation of documentation is clearly an end-goal. Making it easy(ier) for community members to help contribute documentation, and fix documentation issues, is also an end goal. Having documentation handled by the wiki is not an end goal, however, it is one possible means to the end goal of making contribution easier. - 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. Agreed - once the repository of a module is public, contributing documentation fixes here is as straightforward as submitting a patch. - 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. Here's the tricky bit - the current constraints for technical documentation that I have been given are: * It must be possible to have both private and public updates of documentation (due to product embargoes, and documentation documenting not-yet-announced features) * High quality printed documentation must be possible * Lower the barrier to community contribution * Documentation contributions from the community must undergo review before being integrated into official documentation I have suggested making a public SCM for all public releases of documentation in their source format, to allow patches to be submitted. This should happen after the next release. My major concern with plans I have seen for the moment is that there will be major issues bringing changes made to the wiki back to the official documentation, and vice versa. We're in a classic situation where you have to merge two branches, but without the proper tools to do so. Last year when we discussed this in Bugzilla, you said that the plan was to have official docs published read-only in the wiki, with people making suggestions on the Talk pages, and these suggestions would be integrated back into the official documentation. Is that still the plan? - 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. In general, I would like to see the sources (whether they be docbook or latex) available in a public SCM for all published documentation. This would allow people to generate their owm PDFs, web versions, integrate with Yelp or DevHelp, etc. It will also allow people to submit patches using standard tools and reduce the maintenance burden of developers. Is this something you see happening for these types of documentation? As I see
Publishing developer documentation (was Re: The role of the docmaster)
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
