I think there are at least two types of documentation being discussed here: that which a developer wants and that for an end user (the consumer). The tech writer here at Intel is writing the end user help, and that's something we can figure out how to open source after the first release. However, developer documentation is wide open, AFAIK. I think there is an SDK working group, and that might be the place to bring up this collaborative effort.
Margie -----Original Message----- From: Dave Neary [mailto:[email protected]] On Behalf Of Dave Neary Sent: Tuesday, March 30, 2010 5:50 AM To: [email protected] Cc: Foster, Margie; [email protected]; [email protected]; [email protected] Subject: Re: [MeeGo-dev] On device help framework Hi, [email protected] wrote: > There are pretty strict legal regulations, depending on sales > location, on what kind of documentation has to be available to the > person purchasing a mobile phone. > The legal requirements for netbooks are different, as are for > in-vehicle systems. So this will require a bit of differentiation > depending on system type. I understand - which is why I don't believe that documentation should be excluded from the general requirement that there be a maintainer who decides what gets in & what doesn't. It just happens that documentation is an area where many more people can contribute than code - although good docs writers & good coders are about equally uncommon, many more people know how to read & write English than know how to read & write C. So there's a potential for community contribution, and it would be a shame to set technical barriers to that happening by having the documentation created by one person & broadcast once it's finished, with no possibility for others to submit proposals, corrections, suggestions for document structure & organisation, etc. I would expect a maintainer to be able to explain when there are legal constraints on what can & can't be done in the same way that a project maintainer often does. > A lot of the documentation, for example for the default applications, > could be written by anybody who is qualified in technical writing. Absolutely - all we need are the processes & toolchains in place which allow that to happen. As I said, source control with DocBook or DocBook Lite would allow community contribution, but sets an entry bar in terms of the toolchain for submitting changes & "building" documentation, and proposing patches. You can explain to someone how to build documentation & submit their first patch via git in maybe half an hour, but they won't do it to fix a typo. They might do it to document an application as a favour to a developer who asked them to. Im my dream world, there would be a web application with a wiki-like interface, which would be a view to docbook sources, where changes were sent to a submission queue rather than being immediately displayed, where a maintainer could review and modify/reject/accept proposed changes, and anyone could view the review queue to see what the status for their proposed patch was. I don't know of any such application :( > It might be worth looking at what formats robohelp produces and see > if those can be done with other tools as well. Or maybe write directly in > xml (in whatever dialect is necessary) and convert that to po and html > as necessary. Certainly there will need to be a conversion of whatever the source format is to po or whatever for transifex. However, if the reference source isn't available in some format where anyone can propose changes (even if that's docbook or latex or whatever in git) then we're going back to a situation we had in Maemo, where anyone who doesn't have access to the sources is essentially locked out of contributing to documentation. So I would strongly suggest that if there's a choice to be made that we lean towards your second suggestion, or something like it, and have the docs written directly in an open format, and made available somewhere where anyone can see it and propose changes (which may or may not be accepted by the maintainer afterwards). The important thing is that the docs sources be visible, and that the maintainer team act publicly, in the same way we expect code maintainers to act (and that includes not making a big "code dump" just before release time as the documentation subcontractors send all the docs they've been working on at once). > In one sentence, the majority of the documentation could use > community love, but parts of it are regulated by laws. In one sentence, I don't expect documentation to be a special case in MeeGo - of course a maintainer will decide what is accepted, and of course we should have access to the source code and the means to propose patches. Cheers, Dave. -- maemo.org docsmaster Email: [email protected] Jabber: [email protected] _______________________________________________ MeeGo-dev mailing list [email protected] http://lists.meego.com/listinfo/meego-dev
