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

[Alberto Salvia Novella]

Tommy Trussell:
 > HOWEVER to propose "dressing up" a whole (section of) a wiki with
 > such attention to graphical elements might be overwhelming for
 > authors to create and maintain.

In which regard? In finding images, or in maintaining the wiki-code?


Tommy Trussell:
 > Failing changing the procedures themselves, there are several
 > textual/graphical techniques that might be used to improve the Triage
 > page's usability by "hiding" superfluous detail, yet keeping the
 > high-level information readily accessible.

I found that atomizing information as much as possible is one of the 
most clarifying practises when writing documentation. Here's an 
unfinished example:

  - <https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Work-flow/Triage>.
  - <https://wiki.ubuntu.com/Bugs/Triage>


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.

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.

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.


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

Could you provide some examples?


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.

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.

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


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

This is what I first thought, because of it looking more uncluttered. 
But after using pages with graphics for a while in the One Hundred 
Papercuts project I realized that isn't true.

It is true for the first time but; as the brain can process graphics 
65000 times faster than sounds; not for consecutive ones, where you 
search based in the memorized page composition.

This is why icons were invented, and why to look for items on the 
desktop would be tedious if they only had text instead. Moreover, they 
make the experience enjoyable.


Have a nice day :-)


-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 3748 bytes
Desc: S/MIME Cryptographic Signature
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20141017/0142ce85/attachment.bin>