[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

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

On Mon, 2010-09-27 at 12:28 -0400, Todd B. Sanders wrote:
>   On 09/27/2010 12:07 PM, Jason Dobies wrote:
> > 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.
RHCT #605010081634021
Freenode: linear

Attachment: signature.asc
Description: This is a digitally signed message part

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]