Short-n-sweet

[Carl Karsten]

Matthew Paul Thomas wrote:
> 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?)
> 

Yes.  I didn't realize how simple that was.

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

What are the pros-n-cons of folding/hiding/suppressing/visually segregating the 
GUI from the CLI instructions?  I realize it adds a level of complexity to the 
docs, but it might be worth it.

easy way: 2 wiki pages with cli/gui tags.  bleck.

interesting way: hide the CLI instructions in html

      = Frobnicating the wizzle =

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

<div  title="foo && bar && frob -g" >
      1.  First GUI step goes here.

      2.  Second GUI step goes here.

      3.  ...
</div>

Now if there was some wiki syntax to make it a bit easier to chew on.  Also, as 
a CLI user, I would probably find it annoying.  so lets not do that.

And then there are the cases where the GUI solution is limited.  For instance, 
WorldofWarcraft on wine, you can get a usable system with just the GUI, but if 
you want it even better you need to do some CLI things that don't have a GUI way.

Another thought is a user preference: show gui, show cli.  view a page, and 
initially see only what you want to see.  For someone with just GUI, the 
WorldofWarcraft would be pretty short (and sweet.)  Click the "show cli content" 
and get the cli stuff.    If you are like me, you would have gui turned off. 
one note: given the nature of wiki pages, authors, the community, etc. I am sure 
that the normal usage pattern of both groups would be "look at page, click to 
see the other view' which would seem to make this effort pointless.   But I 
believe there would be a population that would never click "Show CLI" and those 
are the folks I am concerned for.

Carl K