[Tfug] Another poser

[Bexley Hall]

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

> On Jul 16, 2007, at 2:07 pm, Bexley Hall wrote:
> 
> > 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"...

That's exactly the situation I am in -- *I* need
to leave notes for myself.  *I* have to refer to
commands that are undocumented.  It is possible that
I will never consult these these notes in the future
so "maintaining" them is dubious.  Yet, I would
like to ensure *I* can understand them at some
future date *and* if I happen to pass a copy on to
some other person, it would be nice if he/she
could *also* make sense of them (N.B. My "notes"
are "publication quality" -- typeset with nice
DTP tools, photographs, etc. -- making them 
valuable enough not to casually "misplace")

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

Hmmm... I'd be willing to bet I can find at least
one manual that differs from your expectations!  :>
(ignoring the obvious things like section 3 vs. 3c
vs. 3f ...)

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

Yes, but I have no idea where someone will opt to
*put* that page!  Granted, once it has been "put",
it will typically STAY put...
 
> >  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.

I've written a lot of assembly language code over
the years.  You'd be amazed at the sorts of
useless comments you would come across  :<
(e.g., INR (M)  ; increment memory location)

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

I used to hear folks put the blame on their bosses,
management, etc.  "They don't give me *time* to
{test,document,revise,whatever}..." which, to some
degree, is true.

However, with the prevalence of open software,
I see the same sorts of quality problems (suggesting
a lack of testing, documentation, etc.).  "Gee,
who was your *boss* on *that* project??"  :-/

So, I firmly believe people don't {test,document,etc.}
simply because they really don't *want* to
{test,document, etc.} their code and the "blame
the boss" cry is just a ruse...  :<

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

<grin>  No, *old*!  :-/
 
> 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.

Exactly.  If all you do is the same sort of
thing over and over again, you usually don't
*need* "notes".  But, the more varied your
work experience and the more "exotic" the
tasks, the greater the chance of forgetting
some annoying little detail that makes a
big difference in the time/quality of a particular
task.

Sort of like Kelly Bundy; once your head fills
up with "stuff", each new datum forces an old
datum out the other end  ;-)

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

You're lucky.  Most of my professors never left the
ivory tower.  :<  Tremendous intellects and a great
variety of *ideas* but damn little *practical*
experience  :<

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

ROTFL!  Touche!


 
____________________________________________________________________________________
Never miss an email again!
Yahoo! Toolbar alerts you the instant new Mail arrives.
http://tools.search.yahoo.com/toolbar/features/mail/