ubuntu-docs Requirements?

[Matthew East]

Hi Kyle,

On Thu, Jan 21, 2010 at 1:18 AM, Kyle Nitzsche
<kyle.nitzsche at canonical.com> wrote:
> 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 don't think that what you've raised are really "requirements", but
I'll do my best to respond to them.

>  * 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.

The output format that you use is really a function of what sort of
help you are trying to write. PDF as a format is suitable for
standalone guides which cover a single subject entirely. A good
example would be a book about Ubuntu, or the Ubuntu Server Guide.
Docbook is good for writing help like this.

However desktop help should be different. Topic based help means
providing the user with what is preferably a single page of help which
covers the specific task that they are trying to achieve. Topic based
help pages interllink, are easy to read, and provide information in
small chunks. Docbook is a bit cumbersome for such help, because it is
not designed for it but with some effort can be forced into something
resembling topic based help. Mallard is specifically designed for this
type of help.

The current ubuntu-docs package does not provide good topic based help
yet. But our aim since 2005 has certainly been to do so (see
https://wiki.ubuntu.com/TopicBasedHelp). You'll see that this spec
mentions Mallard.

>  * 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?

This is a question of common sense, and is the same throughout the
Ubuntu community. The Ubuntu community is set up to be welcoming to
newcomers who don't necessarily have the skills to join
~ubuntu-core-doc right away, or to join ~ubuntu-dev right away. Our
goal, in every single team in the Ubuntu community, is *always* to
increase contributors. So any project lowering the barrier for entry
should be considered. The use of bzr in Ubuntu was born partly out of
this philosophy. Obviously if you are lowering the barrier to entry,
you also take care to try and ensure that your quality assurance is up
to scratch and one shouldn't adopt a technology that lowers barriers
to entry while at the same time making the eventual product worse, but
again that is just common sense.

>  * 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?

No, it doesn't. We avoid full size application or desktop screenshots
in desktop help on the basis that they are thought to be easy to
confuse by users with the actual application itself (which the user
may have open while reading the help) - see for example mpt's post
here and related links -
http://mail.gnome.org/archives/gnome-doc-list/2006-July/msg00154.html.
Having said that, I can definitely see that some graphics might be
helpful.

> Does mallard? A transition to mallard should be evaluated in light of
> this "requirement," whatever it is.

It certainly supports images
(http://projectmallard.org/about/learn/media.html), but no markup
language really supports localised images. It's the build system and
team processes that will define how images can be localised. Mallard
isn't a build system. I don't know how gnome-doc-utils currently deals
with the translation of screenshots but we can ask around. Given that
we don't currently do it, anything that can be added would be a bonus.

>  * 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.

That's correct. However if we want to seriously collaborate with
upstream and integrate with documentation they produce, I personally
see the move to mallard as more or less essential. Otherwise, we'll
keep doing what we do now, which is to write most of our material
ourselves, and link to upstream material occasionally.

I know that xfce is also on board with Mallard, and I'm really hoping
that the current discussions between Shaun and some of the KDE guys
will lead to at the least a positive collaboration between all our
desktop upstreams on desktop help.

>  * 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.

Well, I pointed out that this is essentially the role of the "New to
Ubuntu" document, which at the moment isn't doing a very good job of
it, or even any job at all. But we don't really have "requirements"
for specific documents, we just try to develop documents which we feel
suit the needs of our users, depending on the resources that we have
available at the moment. Those are currently contained in our bzr
branch, and there is a plan for an installation guide, which may be
partially implemented: I don't know what stage that is at, but Phil
will know more.

> 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.

Yes, obviously translation and the website are both things that we do
now which I can't see any justification for dropping.

> 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.

We could produce a document that sets out our aims for the system
documentation and for the wiki documentation. If it would helpful
newcomers to the project to understand our aims in a way that the wiki
pages currently do not do, I wouldn't be against it. Updating our
styleguide would be another thing that we should seriously look at in
the light of the transition towards topic based help.

-- 
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF