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 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. So you see the wiki as being the source version of the documentation? Is the quality of print documentation compromised by the choice of a wiki? Layout options are much more limited than they are with either DocBook and laTeX. I'm all for the master being in the wiki, if we can accomplish all the goals I mentioned earlier. The main ones which would be difficult are the review of community contributions and the availability of high quality print documentation, and perhaps also the maintenance of private and public branches of documentation. (as an aside, git or any other distributed SCM would be the ideal tool for maintaining this configuration, the private branch would be free to pull changesets from the public branch throughout the development cycle, and push everything live with version history when the decision is made to publish). Cheers, Dave. -- maemo.org docsmaster Email: dne...@maemo.org Jabber: bo...@jabber.org _______________________________________________ maemo-developers mailing list maemo-developers@maemo.org https://lists.maemo.org/mailman/listinfo/maemo-developers
