[Tfug] Another poser

[Rich]

On Jul 16, 2007, at 2:07 pm, Bexley Hall wrote:

> I don't have control over the product -- or its
> documentation -- that *has* the undocumented man
> pages!  :>
Damned good point! That kinda pulls the rug from under my argument :-)

> Had I more of a masochistic side, I could similarly
> undertake documenting Microsoft's products for
> *them*!  :-/
Indeed -- but this is something that many sysadmins and programmers  
end up doing! Except "them" = "themselves"...

>> 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.
Footnote on every page of your documentation? :-)

> 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!!  :>
I've taken this approach once or twice...

> 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.
True, but the lower section numbers are the same across platforms, so...

>> 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!)
...but a multi-platform package would generally have the man page in  
the same section on each platform.

> None of these really do anything to "force"/coerce
> better documumentaqtion out of the developer.
That's true.

>  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 while it doesn't help us, this neglect isn't something we  
should expect. Shoddy documentation is a worse bug than absent  
documentation.

> And, there is nothing that forces/encourages a
> writer to debug his/her comments.  Or "maintain"
> them.
That's a product of the $/line mentality.

> I suspect most developers don't worry about long-term
> maintenance issues.
You'd be right. I'd say this is due to the psychology of the  
programmer. For those with less than 'virtuosic' skills, A project  
often starts with a hack, which doesn't get documented. It's a battle  
to get people to document anything.

>   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).
That's the problem -- teams who know the code intimately aren't going  
to believe that there'll ever be a time when their code needs full  
documentation, but then someone leaves, someone goes on maternity  
leave, someone else retires. Then the team isn't the same team any more.

> 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).
So you're HUMAN?!

hehe -- I'm the same way. I've written several cheatsheets for  
different sysadmin tasks and procedures. How big was the blocksize  
for cloning a disk with dd? How do OpenSSH and commercial SSH keys  
differ? MySQL, FlexLM, etc.

>   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)
Now that you've made your aim clearer, it makes much more sense.

> Most CS instructors IME have written very little
> real-world code -- rarely entire *projects*.  :>
That's the reason I respect him. He'd worked a couple of decades in  
industry.

> 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!
Sounds like Rebol! (http://rebol.com/)

> Unfortunately, those bits of code often need a fair
> bit of paper to describe their operation and theory.
> :<
Well, you should *always* have a proposal, a design brief, and a  
project plan, right? So what's one more big document to describe how  
to use it?

> "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?"

African or Indian?

R.