Please, could you give your opinion on these documentation styles?

[Little Girl]

Hey there,

Alberto Salvia Novella wrote:

> Look, I'm trying to improve the quality on how Ubuntu documentation
> is written to make it better to non-technical users. It happens
> that there's an aspect right now that is unclear if it good or not,
> so I was wondering if you could give your opinion on that.

Documentation is like breathing for me, so I'd be happy to jump in
here. (:
 
> In particular I would like to know which one do you prefer, why,
> and what would you change from that chosen one.

Okay.
 
> But remember having both versions at view at the same time on your 
> screen, or the experiment wouldn't be valid. This means you'll need
> a desktop with a wide screen or two screens.

Not necessary. They're both short pages, so you can open them in two
tabs and click back and forth to compare them line by line.
 
> Here you have the pages:
>   - 
> <https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Work-flow/Triage/Fixable>
>   - 
> <https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Work-flow/Triage/Workable>

Okay, I prefer the Workable one (the one without images).

Why? For a couple of reasons:

First of all, the one with images is too busy and takes the focus off
of the contents, which are the most important part.

Second of all, if you copy and paste the contents of each into a text
file, you'll notice a significant difference between them.

This is what you get if you copy the contents of the Workable one
into a text editor (note that it may wrap in your email program, but
it doesn't in my text editor):

====================
Common situations where a bug isn't workable by
Ubuntu are:

    Its software hasn't been packaged by Ubuntu, but by a third party
    (the rmadison application can help).

    It is an idea for a new feature in a software developed outside
    Launchpad.

    It is a support request.

    The user misconfigured the system. 
====================

Those results are clean and readable and would be immediately useful
outside of the wiki. It's especially nice that the list items are
indented.

This is what you get if you copy and paste the contents of the
Fixable one into a text editor (note that it may wrap in your email
program, but it doesn't in my text editor):

====================
Common situations where a bug isn't fixable by
Ubuntu are:

Pictographs/1F4BE Floppy Disk.svg
	

Its software has not been packaged by Ubuntu, but by a third party
(the rmadison application can help).

Pictographs/1F4A1 Electric Light Bulb.svg
	

It is an idea for a new feature in a software developed outside
Launchpad.

Pictographs/1F526 Electric Torch.svg
	

It is a support request.

Pictographs/1F527 Wrench.svg
	

The user misconfigured the system.
====================

This one needs some clean-up before it can be clean, readable, or
useful outside of the wiki since it has text representations of the
images, it has excess white space, and it's missing the layout (the
indentation that the other one has) to let you know that those are
list items.

What would I change from the chosen one? The links should either be
expanded within the text or should be listed in expanded form
somewhere on the page (maybe a section entitled Links In This Page or
something like that). This is important in documentation because you
never know how someone will be using the information. Some people
print it or copy and paste it into a text file, and links that
aren't expanded will be useless to them (and possibly
indistinguishable as links if printing is black and white or if the
information is pasted into a text file). I know that unexpanded links
are pretty, but in documentation, usefulness should always trump
beauty.

P.S. My son took a look at it, too, and likes the icons you used as
bullets in the Fixable one. (:

-- 
Little Girl

There is no spoon.