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

[Little Girl]

Hey there,

Alberto Salvia Novella wrote:

> Little Girl wrote:
>  > 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.
 
> It's a matter of psychology: after a few seconds you really don't 
> remember how the page looked like, but you invent the details
> without noticing it.

I guess I did it differently. I had them open in two tabs and just
kept going back and forth between them without spending a few seconds
on either. I compared them word for word.

> And this usually leads to self-deception, because you invent these 
> details to fit your expected model of reality; as the brain is more 
> explanatory than logical.

Not this brain. (:
 
> Yes, we are programmed to breast-feed children and to vote the same 
> party over and over. So better to provide a one view comparison,
> than to trust in people faith regarding GUI vs CLI churches.

That's fine if you feel that way, and for that Meld can be used quite
nicely, as Svetlana suggested. It's a great comparison program.

> Little Girl:
> > This is important in documentation because you
> > never know how someone will be using the information.
 
> Could you provide some examples?

I assume you would like examples of expanding the links rather than
how someone will be using the information, since I did provide
examples of that. Okay, I took the Workflow page and expanded the
links into a separate section of the page in various ways below.

Here's an example adding a level 2 heading with a list of links under
it:

====================

## CategoryPapercutsInformation

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

 * Its software hasn't been [[One Hundred Papercuts/Software packages|packaged]] by Ubuntu, but by a '''third party''' (the [[One Hundred Papercuts/Work-flow/Triage/Fixable/rmadison|rmadison]] application can help).
 * It is an '''idea''' for a new feature in a software developed outside [[One Hundred Papercuts/Launchpad|Launchpad]].
 * It is a '''support request'''.
 * The user '''misconfigured''' the system.

== Links used in this page ==
 * [[https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Software%20packages]]
 * [[https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Work-flow/Triage/Fixable/rmadison]]
 * [[https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Launchpad]]

====================

Here's an example adding an admonition with a list of links in it:

====================

## CategoryPapercutsInformation

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

 * Its software hasn't been [[One Hundred Papercuts/Software packages|packaged]] by Ubuntu, but by a '''third party''' (the [[One Hundred Papercuts/Work-flow/Triage/Fixable/rmadison|rmadison]] application can help).
 * It is an '''idea''' for a new feature in a software developed outside [[One Hundred Papercuts/Launchpad|Launchpad]].
 * It is a '''support request'''.
 * The user '''misconfigured''' the system.

{{{#!wiki note
Links used in this page:
 * [[https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Software%20packages]]
 * [[https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Work-flow/Triage/Fixable/rmadison]]
 * [[https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Launchpad]]
}}}
 
====================

Here's an example adding a colored div with a list of links in it:

====================

## CategoryPapercutsInformation

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

 * Its software hasn't been [[One Hundred Papercuts/Software packages|packaged]] by Ubuntu, but by a '''third party''' (the [[One Hundred Papercuts/Work-flow/Triage/Fixable/rmadison|rmadison]] application can help).
 * It is an '''idea''' for a new feature in a software developed outside [[One Hundred Papercuts/Launchpad|Launchpad]].
 * It is a '''support request'''.
 * The user '''misconfigured''' the system.

{{{#!wiki yellow/solid
Links used in this page:
 * [[https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Software%20packages]]
 * [[https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Work-flow/Triage/Fixable/rmadison]]
 * [[https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Launchpad]]
}}}

====================

And last, but not least, here's an example adding some plain bold text
above a list of links:

====================

## CategoryPapercutsInformation

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

 * Its software hasn't been [[One Hundred Papercuts/Software packages|packaged]] by Ubuntu, but by a '''third party''' (the [[One Hundred Papercuts/Work-flow/Triage/Fixable/rmadison|rmadison]] application can help).
 * It is an '''idea''' for a new feature in a software developed outside [[One Hundred Papercuts/Launchpad|Launchpad]].
 * It is a '''support request'''.
 * The user '''misconfigured''' the system.

'''Links used in this page:'''
  * [[https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Software%20packages]]
  * [[https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Work-flow/Triage/Fixable/rmadison]]
  * [[https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Launchpad]]

====================

> Little Girl:
>  > I know that unexpanded links are pretty, but in documentation,
>  > usefulness should always trump beauty.
 
> I normally would agree with this. But in this case I think what is
> lost is not the aesthetics that unexpanded information gives, but
> actually the ability of the information to be understandable.

Perhaps my examples will change your mind, or at least show you a way
of doing it that doesn't interfere with the existing content and
simply "bolts on" a list of links from the page.
 
> In fact, seeing the examples, at this time I perceive the
> difference is huge; and loosing this ability to express information
> in a so easy way I feel cannot be compensated by having the ability
> of copying it directly, specially when it's related with tasks that
> require online connection themselves.

Please keep in mind that not every task covered by the Ubuntu wiki
requires an online connection. In fact, I would venture to guess
(and hope, even!) that most don't.

Also, keep in mind that, by not providing expanded links, you're
alienating a group of people who have to either go elsewhere for
information or spend varying amounts of time cleaning up the contents
you provide by finding and manually copying the links into the text
they copied from the page. This may seem trivial, but some pages are
large, quite complex, and contain many links.
 
> Moreover, I have all the sensation that this is the single most 
> important thing for attracting new contributors: having a manual
> that turns difficult tasks that normally people would be unwilling
> to do into easy tasks.

I agree. (:

> This is why triaging is not getting done, this is why bugs go into
> Ubuntu, and this is why Ubuntu isn't still jumping to the next
> level.

I'll take your word for it since I haven't formulated an official
opinion. (:

-- 
Little Girl

There is no spoon.