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
signature.asc
Description: This is a digitally signed message part
_______________________________________________ Pulp-list mailing list [email protected] https://www.redhat.com/mailman/listinfo/pulp-list
