ubuntu-docs Requirements?

[Kyle Nitzsche]

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