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

[Bruce Hyatt]

I too prefer the one without the extra images, in this situation. It's easy
to find what I'm looking for.


Sincerely,
Bruce Hyatt


On Wed, Oct 15, 2014 at 8:45 PM, Little Girl <littlergirl at gmail.com> wrote:

> 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.
>
> --
> ubuntu-doc mailing list
> ubuntu-doc at lists.ubuntu.com
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20141016/a7a055c6/attachment.html>