On Sun, 12 Nov 2006, Charles Curley wrote:
> On Sun, Nov 12, 2006 at 05:31:56PM +0000, Timothy Murphy wrote:
> > Also a simple example of usage
> > (using script or a similar capture program)
> > is worth a ream of metadata.
> > It is usually perfectly obvious how to modify an example
> > to suit one's particular case, while something like
> > squiggle [options] <io> <xpd>
> > takes an age to decipher.
>
> I find it interesting that most of the people who commented on this
> did so on the info vs man issue. I think the more substantive issue is
> that of bad documentation, regardless of presentation.
BING!
Anything can be done badly.
> * I agree with you that lots of examples are a good idea. They are
> harder to write and maintain than straight prose.
A set that uses all the metasymbols would be nice.
The most important part of maintaining the examples
is getting rid of ones that don't work anymore.
If it's made clear which concrete items come from which metasymbols,
that would go a long way to ensuring that users aren't fooled by
stale examples.
Metasymbols will help you know what changes
will work and what changes won't work.
<filename> and <absolute-path-name> are different.
> * Procedural documentation is preferable to item documentation.
>
> By procedural documentation, I mean, how to do things the user is
> likely to want to do. In your case, how to resize a partition:
> first, go find a virgin. Second, umount the partition. Then shrink
> the file system. Only then do you resize the partition. Now offer
> the virgin to Murphy. Finally, mount the partition, not the virgin.
My next .sig .
> By item documentation, I mean, "This is the resize button. Use it to
> resize your partition." To which the appropriate response is, "No
> shit, Sherlock".
A comment or two about when to use it, what partition it will affect
and what size it will produce wold be good things.
Some people have the idea that if it has a GUI it doesn't need documentation.
--
Mike hennebry@xxxxxxxxxxxxxxxxxxxxx
"it stands to reason that they weren't always called the ancients."
-- Daniel Jackson
