[sf-lug] SF-LUG meeting of Monday, 15 August 2016

[jim]

     The dash man page, in my opinion, is an exception
because of the lean design of the dash shell and the
clarity with which the dash man page is written.
     That said, there is the issue that the reader
has to understand the terms used within: someone who
already does, probably won't learn a lot from
reading; someone who does not may be able to learn a
lot by looking up the meanings of all terms not
understood.
     I've done that: It took hours but was an
interesting experience: read one or two sentences,
encounter a new term, look up an explanation of the
term, either resume reading or look up new terms
encountered in the explanation....
     The dash man page in my experience is exceptional.

$ echo $SHELL





On 08/16/2016 07:01 PM, Rick Moen wrote:
> Quoting Bobbie Sellers (bliss-sf4ever at dslextreme.com):
>
>>      I neglected to mention that Aaron and Erik discussed
>> CLI tools for disk formatting and the use of man to discover
>> operation of those tools.   Myself when I look at man pages
>> I get confused and that is one of the reasons I prefer to
>> use GUI tools.
> Ah, I can help, here.
>
> Sadly, man pages are generically a poor vehicle for learning about
> software -- because that's just not the _type_ of documentation they
> are.
>
> Computer documentation gets broadly divided into two categories:
>
> 1.  Tutorial: something you read to learn about a topic
> 2.  Reference: something you consult to find details about
>      something you're already familiar with.
>
> man pages are _not_ tutorial material.  They're reference material.
> Moreover, they're deliberately the most terse subcategory of reference
> material:  They're 'quick reference'.
>
> That means they're an ultra-compressed, minimalistic list of what each
> command switch and parameter does, a syntax spec, some very brief
> examples, a list of known bugs, and a 'See also' bit at the end.  No
> context for anything, no attempt to teach you what's going on or _why_
> you would use any part of the discussed software.
>
> I'm not saying 'Avoid trying to learn software from man pages.'
> Sometimes you can, in which case 'Yay, you.'  But you should not be even
> the slightest bit surprised when you cannot, because they're written
> with no aim to teach anything to people, _whatsoever_.
>
>
> Where are the tutorials?  Books, to be sure, but also, gosh, pretty much
> all over the goshdarned Internet.  And Web-searching is still _the_ key
> life-coping skill of the 21st Century so far.  Trying:
>
>    parted tutorial
>
> I find as the first hit:
> https://wiki.archlinux.org/index.php/GNU_Parted
>
> Hey, pretty good, and Arch Linux's wiki is renowned for the high quality
> and usefulness of its technical content, generally.  A few hits down:
>
> https://www.youtube.com/watch?v=i7j5H6AxO9w  PartEd Basic Tutorial
> https://www.youtube.com/watch?v=OcB6IGqG34Y  Creating Partitions with GNU PartEd
>
> Will you look at that!  Two video walkthroughs.
>
> http://www.tecmint.com/parted-command-to-create-resize-rescue-linux-disk-partitions/
>
>     8 'PartEd' Commands to Manage Linux Disks
>
>     [...]
>     In this tutorial you will learn the basics of parted and we will show
>     you some practical examples. If you don’t have any previous experience
>     with parted, please be aware that parted writes the changes immediately
>     to your disk, so be careful if you try to modify your disk partitions.
>
> Anyway, tutorials, not quick references.
>
> Attempting to learn a totally unknown piece of software from its man
> page is rather like driving nails with a screwdriver.
>
>
> Note:  Even the above tutorials assume that you merely want to learn
> about the particular _tool_ discussed, but assume you already have a
> basic fluency with partitioning in general.  Be careful what you ask
> for:  As Prof. Tolkien might have written if he'd lived in the current age,
> 'Ask not the Internet for advice, for it will give you verbatim what you
> asked for, good and hard.'  Point is, if you _first_ need basic
> background on disk partitioning, you should read up on that first.
>
>     partitioning tutorial
>
> First hit looks OK:
> http://www.porteus.org/tutorials/40-partitions/111-tutorial-understanding-partitioning-and-formatting.html
>