[Tfug] Another poser

[Rich]

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.

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

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!

>> 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 using a number  
rather than a hyphen is that, when the man page becomes available,  
bingo, the original referencing docs magically work!

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!

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.

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!

R.