Short-n-sweet

[Matthew Paul Thomas]

On Oct 23, 2007, at 11:38 PM, Mads Peter Rommedahl wrote:
>
> 2007/10/23, Jonathan Jesse <jjesse at iserv.net>:
> ...
>> I would echo the hpe that we can eliminate the "run this simple 
>> command" from our documents.  might be a good task for some people 
>> who are looking fo a job
> ...
> Generally, it'd be cool if we had two solutions in two different 
> sections of the same page: A CLI-one which has the "run this simple 
> command"-solution and a GUI-one which guides you through GNOME - maybe 
> with pictures to help.
> ...

So, there are two separate issues here.

First, avoid describing instructions as "simple", or telling people to 
"simply" or "just" do something. For people who are comfortable 
following the instructions, those words won't make them feel any 
better. And for people who *aren't* comfortable following the 
instructions, it's irritating. <http://urlx.org/google.com/41e77>

("Simply" is in the "Words to avoid" list I suggested last year.
<https://lists.ubuntu.com/archives/ubuntu-doc/2006-July/006669.html> 
Perhaps I should put this list on the wiki?)

Second, how to present GUI vs. terminal instructions for doing the same 
thing. I think this depends on how long each of them are. I think GUI 
instructions should normally go first. But if the GUI instructions are 
long and the terminal instructions are very short, reversing the order 
may be better for readers on average. Something like this:

     = Frobnicating the wizzle =

     If the wizzle is lolloping gangrously, you may need to
     frobnicate it.

     If you are comfortable using the terminal, enter this command:

         foo && bar && frob -g

     Otherwise:

     1.  First GUI step goes here.

     2.  Second GUI step goes here.

     3.  ...

Cheers
-- 
Matthew Paul Thomas
http://mpt.net.nz/