[Tfug] Another poser
r-lists at studiosprocket.com
Mon Jul 16 16:41:00 MST 2007
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
> 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.
> 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
> And, there is nothing that forces/encourages a
> writer to debug his/her comments. Or "maintain"
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
> 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*
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?
More information about the tfug