[Tfug] Another poser

[Bexley Hall]

--- Rich <r-lists at studiosprocket.com> wrote:

> On Jul 14, 2007, at 11:00 am, Bexley Hall wrote:
> 
> > imagine writing documentation that refers to
> > tar(1) and having to constantly say things like:
> >
> > "Use tar (which is the tape archiving command) to
> > package the group of files into ..."
> 
> If that's a problem, then write the man page. Then
> you can refer to  
> "floobydust(1)" without being disingenuous.

I don't have control over the product -- or its
documentation -- that *has* the undocumented man
pages!  :>
 
> You *have* to be clear, otherwise you end up with an
> undocumented  
> pile of garbage, like many of Microsoft's products.
> 
> > I think the Principle of Least Surprise would
> > advocate a notation like "tar(-)" instead.
> 
> Instead of exploring this principle to work around
> not having a  
> manual, why not just learn the roff syntax, muscle
> your way into the  
> floobydust development team, and get the thing
> repackaged with a  

The product is a commercial one -- not open source.
I have a small interest in documenting how to *do*
things with it -- but no interest in taking on
*their* (commercial) tasks!

Had I more of a masochistic side, I could similarly
undertake documenting Microsoft's products for
*them*!  :-/

> manual! Yes, I know we're in a philosophical debate,
> but it sounds  
> like another technical fix (magical dangling
> references) for a social  
> problem (lack of documentation).
> 
> Think about this in another way: you don't have the
> "floobydust"  
> program installed, so you
> 	touch /usr/local/bin/floobydust
> 	chmod a+rx /usr/local/bin/floobydust
> Great! Now my script doesn't exit:
> 
> 	[ -x /usr/local/bin/floobydust ] && floobydust -C
> /var/ 
> whatchamacallit/* || exit
> 
> Only it doesn't actually *do* anything. That's the
> executable  
> parallel to what we're philosophizing on.
> 
> > Someone used to reading *NIX documentation
> > might falter for a moment -- wondering what that
> > parenthetical suffix represented ("Gee, is that
> > a function invocation?  Hmmm, an argument *or*
> > an ellipsis would make sense within the parens
> > but that hyphen dash...   Ah, maybe a man page
> > reference?  In which case, what *section* is
> > represented by '-'??) but would, regardless,
> > understand that "tar" is a magical word and
> > not a reference to a petroleum based substance...
> 
> And what about the people who don't get the
> punchline? They're stuck  
> with greater misunderstandings:
> 
>   - "What type of argument does function
> floobydust() expect?"
>   - "I'm looking for the footnote '-'. I don't see
> it."
> 
> Or even:
> 
>   - "Oh? I'll try 'man - floobydust'. Hm. No manual
> entry for - / No  
> manual entry for floobydust."
> 
> And the punchline they make up for themselves is:
>   - "This documentation sucks almost as hard as it
> blows!"

Then don't *use* "my" documentation!  :>  Instead,
call the vendor and complain to *him* about his
piss-poor product/documentation.

> Cue package removal.
> 
> Some people don't have time for tenacity, and others
> are even  
> incapable of Googling... wouldn't you rather they
> *didn't* hit you  
> with a million emails? So document it!

Even more selfishly:  prepare "my" documentation
FOR MYSELF -- adopting whatever scheme *I* want
to refer to nonexistent man pages -- and then just
not *share* it with anyone!  :>  Let them flounder
with the vendor's documentation and either b*tch
to their vendor contact or stop using the product.

That way, I don't have to take on the vendor's
task *or* worry about a million emails!!  :>

> >> Referring to a nonexistent man page doesn't
> really
> >> help.
> >
> > No, but indicating that a manual page *should*
> > have existed (i.e. this is a command, etc.)
> > conveys information in a concise form.  And,
> > when/if such a man page becomes available,
> > you only have to replace the hyphens (instead of
> > having to edit a bunch of now superfluous text)
> 
> Using a hyphen leaves your original poser
> floundering, which was to  
> describe what *type* of a command it is. That number
> is indicative of  
> how dangerous the command can be. The advantage of

You are assuming a particular significance to man
page sections.  Solaris's idea of "section 9" is very
different from Inferno's, etc.  OpusV doesn't even
*have* a section 9, etc.

> using a number  
> rather than a hyphen is that, when the man page
> becomes available,  
> bingo, the original referencing docs magically work!

No.  You are assuming I can foresee which section
said command will reside in when/*if* it is ever
documented.  And, by referencing *any* section,
it now has readers looking for the documentation
*in* that section -- a clear "error" in "my"
documentation (just like documenting how something
is *supposed* to work is an error!)
 
> See, without proper documentation, code is junk.
> Isn't this the sole  
> motivation behind higher-level languages? Take
> machine language:  
> assembly language forces the programmer to reveal
> his hand. It also  
> encourages him to annotate the code. Then stepping
> up to high-level  
> languages, it encourages even more use of meaningful
> variable names,  
> etc. Skip a few decades, then JavaDoc comes along to
> tell you to behave!

None of these really do anything to "force"/coerce
better documumentaqtion out of the developer.  If
you look at big pieces of code, you're hard pressed
to figure out which end is *up*.  Comments are
written as if you already understood the code
(i.e. for the benefit of the original writer; not
as instructional for his successors).

And, there is nothing that forces/encourages a
writer to debug his/her comments.  Or "maintain"
them.

I suspect most developers don't worry about long-term
maintenance issues.  And, perhaps, a good deal of code
is just discarded/reinvented with each subsequent
new product/release (I had a colleague who would
routinely REbug the floating point libraries in
our products in an alleged attempt to "improve" them).

I've found that I just can't remember all of the
details of many of the algorithms I have used if I
don't leave copious notes ("for myself" -- hopefully
benefitting others, as well).  That is the genesis
of this "poser" -- coming up with a scheme by which
I can refer to undocumented commands in the docs
I prepare for myself!  (See?  I truly *am* writing
things that are not intended for others to read...
though I make them available to select persons as
need be)

> My favorite CS lecturer wouldn't even look at code
> without comments  
> -- so yeah, it was drilled into me a long time ago.
> Documenting a  
> system or a software suite is no different.

Most CS instructors IME have written very little
real-world code -- rarely entire *projects*.  :>

The best advice I ever got was to design languages
in which a single *page* could express a "program"
(module, etc.).  At the time, it sounded like an
arbitrary criterion; in hindsight, I find it *most*
admirable!

Unfortunately, those bits of code often need a fair
bit of paper to describe their operation and theory.
:<

> As usual, I didn't have time to write a shorter
> post...
> 
> I'll see if I can come up with some posers of my
> own!

"If the skins of three alligators can be harvested
to create six women's handbags, two pair of men's
cowboy boots, three wallets and a small valise,
how long does it take an elephant with a wooden
leg to kick a hole through a pickle?"


       
____________________________________________________________________________________
Yahoo! oneSearch: Finally, mobile search 
that gives answers, not web links. 
http://mobile.yahoo.com/mobileweb/onesearch?refer=1ONXIC