[Pulp-list] --help standards for client tools

Jason L Connor jconnor at redhat.com
Mon Sep 27 16:41:01 UTC 2010


On Mon, 2010-09-27 at 12:28 -0400, Todd B. Sanders wrote:
>   On 09/27/2010 12:07 PM, Jason Dobies wrote:
> > -----BEGIN PGP SIGNED MESSAGE-----
> > Hash: SHA1
> >
> >> Yuck!
> >>
> >> I'm personally a fan of sentences in the help, and would like to
> see us
> >> standardize in the other direction. I think the all lower case and
> >> semi-colons looks too much like code instead of documentation.
> >>
> > My problem with sentence structure is that most times, people aren't
> > writing in full sentences in a CLI:
> >
> > Creates a new consumer.
> >
> > Isn't an actual sentence, so formatting it as such reads awkward.
> The
> > other side of that is that forcing full sentences to fulfill this
> > formatting desire will end up with a really verbose CLI --help,
> which is
> > also cumbersome. That's what the man page is for.
> 
> +1
> 
> Just trying to align more with current RHEL cli tools (i.e. yum
> --help)
> 
> -Todd 

So perhaps I should clarify. I'm not advocating writing complete
sentences, fragments are fine. But when I'm reading documentation I find
capitalization and periods easier to identify as delimiters than no-caps
and semicolons.

I also don't really like the "everyone else is doing it" argument. If
they had reasons for doing it that way, I'd like to hear those, but I
don't find conformity for conformity's sake compelling. =/

-- 
Jason L Connor
Software Engineer
Systems Management and Cloud Enablement
Red Hat, Inc.
+1.919.890.8331
RHCT #605010081634021
Freenode: linear
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 490 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/pulp-list/attachments/20100927/99d49d6a/attachment.sig>


More information about the Pulp-list mailing list