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

[Little Girl]

Hey there,

Alberto Salvia Novella wrote:

> These examples look like good resources. On the other hand I can't 
> figure out if they fit till I know real life cases where users copy 
> information from the wiki-page.

How about when you travel and don't have reliable internet service,
or have no internet service for extended periods of time?

How about people who live in areas where they pay for every moment
they spend online?

How about people who have unreliable internet service and would
prefer to do as much of their work offline as possible?

In all cases it would be nice to be able to grab something you're
researching and go offline before looking it over or working with it.

I could come up with more ideas, but you could probably do a
questionnaire to find out how others use their computers and come up
with a lot more than I can think of. (:

>  > This may seem trivial, but some pages are
>  > large, quite complex, and contain many links.
 
> This is why I favour atomization as much as possible, and not
> nuclear plants :-D

I understand why atomization is favored, but I don't favor it. I like
all my information in one place, and then it's left up to me how
much of it I read in one sitting. The best of both worlds is to offer
both and let the user choose which to use. (:

>  > 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.
 
> My original idea is to improve documentation regarding triaging,
> and triaging needs launchpad.net.

Ah, you didn't mention that. I probably wouldn't have even jumped in
on this thread if I'd known that, because I don't triage.
 
> Additionally the Internet is so widespread among the Ubuntu
> community that I cannot imagine many cases, except for individual
> applications, were having an offline copy of the documentation
> would help so much. But if you know any example, it will be nice to
> be aware of it.

Well, let's see what I can come up with off the top of my head:

	Documentation on how to adjust your operating system's
	settings (like graphics, input devices, etc.).

	Documentation on how to set up/maintain NFS or Samba for
	local networks (not on the internet),

	Documentation on any applications on the computer.

	Documentation on all available commands (you might be
	surprised to find how many commands have no man pages).

	Documentation on how to configure your desktop, screensaver,
	sound.

	Documentation on how to set up and/or troubleshoot your
	network connection so you *can* get online.

	Documentation on how to troubleshoot difficulties with
	installation of the operating system since you might not be
	online if you couldn't install the operating system.

	Documentation on how to configure your printer.

	Documentation on how to use your CD/DVD drive.

	Documentation on how to add or change hardware on your system.

	Documentation on how to troubleshoot issues with the
	operating system.

	Documentation on how to troubleshoot issues with your
	hardware.

	Etc., etc., etc. The sky's the limit. I could entertain
	myself quite nicely with this computer without the internet.
	Going online is just icing on the cake. (:

> I'm also considering an alternative, that is to use Unicode emojis 
> instead; as those in 
> <https://wiki.ubuntu.com/One%20Hundred%20Papercuts/Work-flow/Triage>. 
> What do you think of this?

I just see waffles where the emojis are in Firefox 33.0, and empty
boxes where the emojis are in Konqueror 4.8.5
 
> The problem is they are only supported by default starting by
> Utopic, and in the latest Android devices. In the rest of systems,
> the page shows a tofu character.

That would be why, then. I haven't updated Kubuntu since the last
LTS. (:

I tested how it behaves when I copy the page and paste the contents
into a text editor, and these at least make a better presentation
than the other graphics you had used. I won't paste the entire page
into this message, but here's a small portion of it to demonstrate
that it presents the lists in a tasteful and easy to read way:

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

Shine

    💬 It is written in English.

    👍 It seems it can be fixable.

    📄 It has enough information.

    🎯 The title is as specific as possible.

    🔳 The panel hasn't obvious errors for you. 

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

In my email program those look like waffles. In Kate (my text editor)
they're narrow boxes that look like two square brackets sandwiched
together. At any rate, the list items are indented, which is very
friendly.

One negative, to these emojis, though, is that the waffle/box
character does not let itself be globally replaced in a document.
Kate will replace one of them with the specified character, but will
not do a Replace All on them.

Your other graphics, on the bottom of that page, aren't nearly as
friendly when copied into a text editor:

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

To triage is to make a confirmed bug ready to be fixed by a developer.

Wink ;) You can triage papercuts simply by joining the Papercuts
Ninjas team.

Warning /!\ Work-flow bugs shall only be touched by the package
developers.

Warning /!\ If the future release isn't Utopic, update this page.

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

Notice that there's no indentation letting me know that the last
three lines are a list, and the graphics become text and ascii
graphics inserted at the beginning of each line. There would be lots
of clean-up for this one if it were a large page.

As a contrast to both of these, a standard bulleted list becomes
indented text (with no leading bullets or other characters) when
copied and pasted into a text editor.

-- 
Little Girl

There is no spoon.