ubuntu-docs Requirements?

[Kyle Nitzsche]

Thank you for your detailed responses, Matthew. For the record, I have 
no doubt that you and this team have good reasons for your choices.

However, I raised these "requirements confusions" not to get into the 
details of them per se.

Rather, they were examples of confusion about "true north" for 
ubuntu-docs and how this may affect community members.

So, I'd like restate my essential point:

"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."
 
Otherwise, decisions may feel arbitrary. We have seen some emails in which people have expressed this exact concern. So in a helpful vein, I am proposing that keeping the working set of high-level requirements on a wiki, perhaps overall and for each doc project, such as the "New to Ubuntu" revision project, and referring to them explicitly in deliberations when making decisions and evaluating possibilities in this list, will help foster an even more connected and excellent ubuntu-docs community.
 
cheers,
Kyle



Matthew East wrote:
> 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.
>
>