[MeeGo-dev] On device help framework
margie.foster at intel.com
Tue Mar 30 10:26:07 CDT 2010
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.
From: Dave Neary [mailto:nearyd at gmail.com] On Behalf Of Dave Neary
Sent: Tuesday, March 30, 2010 5:50 AM
To: tero.kojo at nokia.com
Cc: Foster, Margie; meego-dev at meego.com; meego-il10n at meego.com; lfl at soeiro.com.br
Subject: Re: [MeeGo-dev] On device help framework
tero.kojo at nokia.com 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
Email: dneary at maemo.org
Jabber: bolsh at jabber.org
More information about the MeeGo-dev