[Tfug] Another poser

[Bexley Hall]

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

> 
> On Jul 11, 2007, at 5:10 pm, Bexley Hall wrote:
> 
> > E.g., [...] the floobydust command [...] you could
> > set it in bold courier, etc. and, thus, set it
> > apart from "regular text".
> >
> > But, if you have to resort to straight ASCII text
> > to document something (i.e. in your sources or
> > supporting documents w/o the benefit of
> web/tangle)
> > then that "notational shorthand" really is worth
> > its weight in lead!  :-)
> 
> So we're talking technical writing rather than a
> straight  
> philosophical debate? In that case, because it's new
> and unfamiliar,  
> you'd resort to grammatical and editorial cues,
> e.g.:
> 
> 	"The new command 'floobydust' is used to
> confragulate etc."

This is fine if you are writing "linear" documentation
(like a book).  But, if you are refering to the
floobydust command pervasively, you can't keep
adding that sort of parenthetical baggage.  I.e.,
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 ..."

I think the Principle of Least Surprise would
advocate a notation like "tar(-)" instead.
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...

> Use of quotes around the command would only be used
> first time  
> around, pretty much like any text where you
> introduce an unfamiliar  
> term.
> 
> In this case, I'd recommend *not* saying
> 
> 	"If you're really stuck with deconfragulation in
> your  
> whatchamacallits, you should use floobydust(1)."
> 
> because that *implies* there's a manual to be read.
> If there isn't  
> one but it gives options with '--help', you could
> get away with:
> 
> 	"If you're really stuck with deconfragulation in
> your  
> whatchamacallits, you should use floobydust (try
> 'floobydust --help'  
> for options)."
> 
> And the reason for this last example is that if
> indeed "--help"  
> *doesn't* give any useful results, then these two
> end up being as  
> useful as one another:
> 
> 	floobydust(1)
> 	floobydust --help
> 
> 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)


 
____________________________________________________________________________________
Food fight? Enjoy some healthy debate 
in the Yahoo! Answers Food & Drink Q&A.
http://answers.yahoo.com/dir/?link=list&sid=396545367