ubuntu-docs Requirements?
Kyle Nitzsche
kyle.nitzsche at canonical.com
Thu Jan 21 01:18:17 UTC 2010
Although I am usually the *last* person to suggest formality, I've
noticed in these various threads that there have been misunderstandings
about the core *requirements* that inform and govern decisions made
regarding ubuntu-docs.
* I, for example, didn't realize that pdfs were simply unimportant.
With docbook, they can easily be made using existing toolchains, whereas
with mallard, I'm not so sure. See these two ubuntu-doc sub projects
that I just made (using doctemplate)
http://people.canonical.com/~knitzsche. And the ubuntu manual project
seems to be satisfied with only pdfs. In general, the list of output
formats that are required is a critical decision point for a
documentation project.
* I also may have overestimated the skill level it is appropriate to
expect of contributors. I think perhaps from the perspective that
packagers and developers are required to have a degree of capability
with some tools and processes, and I applied that notion here. Whereas
it may be that if the goal is to increase the number of contributors,
one way to do this is to lower the skills required, which argues in
favor of mallard. Another way is to improve communication/training about
using docbook. It may be that a higher level of skill is desirable. So
what are the requirements and how do they balance?
* I note there are no (or very few) images in ubuntu-docs, including no
inline icons for apps (yes, I know they can change with theme). Was this
not a requirement? Generally, graphics and images make for effective
communications. And of course, they have to be localized, and they
create work. Does the current build system support localized images?
Does mallard? A transition to mallard should be evaluated in light of
this "requirement," whatever it is.
* Is there a technical (or social) requirement that ubuntu-docs
implement mallard? My understanding is that mallard *adds* support for
mallard without taking away it's support for docbook. ghelp links to
gnome content would still work, presumably.
* There is no current requirement for a "Getting Started Guide" or a
"Troubleshooting Guide." And so they don't exist, nor do clear plans for
them, as far as I know, anyway.
There are other requirements, obviously, such as the need to produce
html versions for https://help.ubuntu.com. I've recently raised the
potential requirement that they be customizable without excessive
difficulty. i18n/l10n. Etc.
Do such requirements exist?
Without a working set of published, high-level requirements, it is
difficult to evaluate proposed changes, such as a transition to mallard.
Or plan and prioritize new work, identify shortcomings, etc. I do *not*
think requirements should be excessively detailed or lengthy. Nor can
they ever be fully correct. And they must change with circumstances (for
which there should be some public process with public input). But
without this, there is no consensus "true north" by which decisions can
be made by all concerned.
Perhaps most importantly, a working set of requirements facilitates a
community in which people believe their input is evaluated against some
objective criteria, which makes for a healthy and expressive community.
I propose that if such high-level requirements do not exist, we forms
plans to bring them into existence, along with a process for modifying them.
Cheers,
Kyle
More information about the ubuntu-doc
mailing list