Open Stack

On Sat, May 30, 2015 at 2:39 PM, APlimpton <aplimpton at gmail.com> wrote:

>
> Looks like HAProxy and other pieces that are sold separately or
> trademarked should follow their own standard for capitalization (per IBM
> style guide again).
>
>
I was going to note the same about HAProxy -- it's a proper name with
associated capitalization rules. Same as your other examples, Meg.


> Thanks for the support, Meg :) Funny enough I thought this was going to be
> more of a case where most everyone had shifted to using the initial
> uppercase and the Conventions page just hadn't been updated to reflect it.
> Sorry to be putting a ripple in the pond.
>
>
Not at all, and please don't take any of this as a personal affront or
anything. I'm glad you're looking around and questioning. We love yours and
Meg's fresh eyes!


> Given that it goes against general usage and most style guides, it would
> beneficial to know why the proper noun is being lowercased. I get the need
> to avoid making Everything Look Important, and wholeheartedly agree, but
> this is specifically for one small set of names. OpenStack gets two
> capitalizations, the projects functional names and all the releases have a
> initial one. We clearly didn't disapprove of them in general, so why here?
>

It's tangled up in the lack of clarity around trademark use for a couple of
years. Now that there's more rigor around the use of the OpenStack
trademark, how about you take a look at why you think project names should
be capitalized and post here.
http://www.openstack.org/brand/openstack-trademark-policy/
and
http://www.openstack.org/brand/

When I read through those, I still come up with the conventions we have in
place. Here are my reasons pro lowercase:

- The team/project names like nova, swift, etc. names are never going to be
trademarked so no extra import should be imparted by using the
capitalize-for-proper-name convention.
- We don't pursue legal reasoning in trademarking the name, but do try to
find a unique name that's unused in the software industry. It's not a
proper name.
- We have gotten cease and desist for the use of quantum for example, and
by lowercasing we may be less likely to be in violation of some corner/edge
legal name case.
- The file name such as nova.conf actually has to be lowercase in
Linux-based operating systems.
- The nova-<name> service or daemon names also have to be lowercase in
Linux-based operating systems.
- The nova, swift Command Line Interface (CLI) tools also have to be run in
lowercase  in Linux-based operating systems.
- The lower case always as a rule rather than exception helps simplify
editing and guidance.


> Side note: Since we have a rule for sentence capitalization for headings,
> would it be okay for me to add that to the Conventions page? I don't see
> any mention of it.
>


It's here:
https://wiki.openstack.org/wiki/Documentation/Markup_conventions#Headings
and here:
https://wiki.openstack.org/wiki/Documentation/Conventions/DocBook#Headings

Thanks,
Anne


>
> Thanks,
> Amanda
>
> On Fri, May 29, 2015 at 3:24 PM, Meg McRoberts <dreidellhasa at yahoo.com>
> wrote:
>
>> I'll go along with the wishes of the majority but I do agree with Amanda
>> here, that capitalizing the names of the projects
>> would make both the writing and the reading easier.
>>
>> What about services that are not projects per se, such as HAProxy, MySQL,
>> MongoDB, Pacemaker, Corosync...?  Some of these exist
>> outside the OpenStack world and everyone is used to them being
>> capitalized in a certain way.  But it seems quite awkward
>> to capitalize these when services that are projects are not capitalized.
>>
>> I just went through a piece of doc and changed HAProxy to haproxy.  The
>> title of the section is "HAProxy nodes" so I had to
>> make that "Haproxy nodes" to conform to the standard for capitalization
>> in headers.  I suppose I could rewrite it to be "The haproxy nodes"
>> but I would much prefer to have the keyword begin the header.
>>
>> As I said, I'll go along but Amanda deserves a little support ;-)
>> meg
>>
>>   ------------------------------
>>  *From:* Anne Gentle <annegentle at justwriteclick.com>
>> *To:* APlimpton <aplimpton at gmail.com>
>> *Cc:* "openstack-docs at lists.openstack.org" <
>> openstack-docs at lists.openstack.org>
>> *Sent:* Friday, May 29, 2015 2:56 PM
>> *Subject:* Re: [OpenStack-docs] Style Question for Project Names
>>
>>
>>
>> On Fri, May 29, 2015 at 4:36 PM, APlimpton <aplimpton at gmail.com> wrote:
>>
>> I see several people are fine with how the convention is and would prefer
>> for it to remain as is because they do not see a need for the change.
>>
>> Because I do see a need, the burden is on me to further explain what I’m
>> seeing and why it suggests that using a capital letter with the project
>> names is needed.
>>
>> When I say inconsistencies I mean that a handful of the OpenStack
>> documentation manuals and a few wiki pages use the lowercase. On all other
>> guides, references, manuals, websites, pages, blogs and various other
>> communications the capitalized letter is used by the community (OpenStack
>> and general). This strong majority of people using the capitalized version
>> indicates that there has been a shift in the usage and we should update our
>> convention accordingly.
>>
>> This is supported by the fact that these project names are names/proper
>> nouns and as such should be capitalized. Having the release code names
>> capitalized but not the project code names is inconsistent. If the name is
>> to be a proper noun w/ all lowercase then all sentences that start with the
>> project name will need to be reworded (source: IBM Style Guide used per the
>> Conventions wiki page).
>>
>> An additional benefit to using the initial uppercase with project names
>> is that it helps reduce confusion. Each project uses the project name three
>> distinct ways with the exact same case. The project name, the CLI name and
>> the command that is used. For example: nova, nova, nova. As a component of
>> the project, the CLI name and the command should be lowercase (source: IBM
>> Style Guide). Using a capitalized letter with the project name immediately
>> distinguishes it as being not the project component and helps make sentence
>> creation and updating less convoluted.
>>
>> If this makes sense to most of you and the consensus is reached to change
>> to the initial uppercase I will be happy to find and make those changes. If
>> the consensus is to keep it all lowercase then I’ll go ahead and attempt
>> correction for the majority of docs, which will take a little longer. If
>> keeping all lowercase, it may also be a good idea to remind the other
>> contributors about the conventions page so they will be aware in the
>> future. Either way I am believer in consistency and clarity. :)
>>
>>
>> Agreed. Thanks for bringing the issue forward. Even when writing a blog
>> post for the Rackspace blog two weeks ago, I had two editors tell me to
>> capitalize the project/team name. However they were fine with lowercase
>> once I pointed out our conventions. We have the power to enforce lowercase
>> so why not put your energy towards the lowercase preference that we've had
>> for years?
>>
>> One rule we have for simplicity's sake is to use sentence case for all
>> titles, and the reasoning behind this is that it's fewer rules to explain
>> and enforce (plus there are two competing Title Case styles from certain
>> references). I sense we have the same simplicity goal with "always lower
>> case project names" because once people start uppercasing what they think
>> is Important then Everything Is Important if you Know what I Mean. :)
>>
>> I'd ask you to activate towards lowercase and help enforce that as
>> standard rather than advocating for Upper Case All the Time.
>>
>> Really though, I said I'd get out of the way on this one. Hope my
>> reasoning makes sense.
>> Anne
>>
>>
>>
>> Thanks,
>> Amanda
>>
>> On Fri, May 29, 2015 at 1:37 PM, Shilla Saebi <shilla.saebi at gmail.com>
>> wrote:
>>
>> +1
>>
>> Sent from my iPhone
>>
>> > On May 29, 2015, at 4:22 PM, Christian Berendt <christian at berendt.io>
>> wrote:
>> >
>> >> On 05/29/2015 09:40 PM, Andreas Jaeger wrote:
>> >> We're following the current convention for some time already and I see
>> >> no reason to change, let's keep the current convention. If there're
>> >> problems, let's fix them...
>> >
>> > +1
>> >
>> > --
>> > Christian Berendt
>> > Cloud Computing Solution Architect
>> > Mail: berendt at b1-systems.de
>> >
>> > B1 Systems GmbH
>> > Osterfeldstraße 7 / 85088 Vohburg / http://www.b1-systems.de
>> > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537
>> >
>> > _______________________________________________
>> > OpenStack-docs mailing list
>> > OpenStack-docs at lists.openstack.org
>> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>
>> _______________________________________________
>> OpenStack-docs mailing list
>> OpenStack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>
>>
>>
>> _______________________________________________
>> OpenStack-docs mailing list
>> OpenStack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>
>>
>>
>>
>> --
>> Anne Gentle
>> annegentle at justwriteclick.com
>>
>> _______________________________________________
>> OpenStack-docs mailing list
>> OpenStack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>
>>
>>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150530/6aec417e/attachment-0001.html>