[OpenStack-docs] Style Question for Project Names

APlimpton aplimpton at gmail.com
Mon Jun 1 07:24:40 UTC 2015


After reviewing the guidelines
http://www.openstack.org/brand/openstack-trademark-policy/
and http://www.openstack.org/brand/, I see that there is rigor protecting
and using for the OpenStack mark ("OpenStack") and logos. Interestingly
there is a non-working link in the second paragraph of the Trademark Policy
page that was supposed to go to the marks themselves. Without that link
working it's hard to say if the individual projects were listed there. This
is also of note because the only time I saw mention of the projects, they
were capitalized:

http://www.openstack.org/brand/openstack-trademark-policy/
The "Powered by OpenStack™" Logo, shown immediately below, may be used by
individuals, organizations, and companies that use formally released
OpenStack Compute (Nova) code in their application or product.

The “Storage Powered by OpenStack™” Logo, shown immediately below, may be
used by individuals, organizations, and companies that use formally
released OpenStack Object Storage (Swift) code in their application or
product.
------

Having the legal policies and the majority of people using the initial
uppercase strengthens the argument for updating the capitalization
conventions in favor of it.

Certainly the project code names are not the legal names and won't be
trademarked but they are proper names and proper nouns.  Since the
formal/legal names for the projects are capitalized doing the same for the
code names doesn't place any importance, it just provides consistency. A
friend can be named Michael but go by Mike. He wouldn't go by mike.

Having all mention of the project code name as lowercase does add
simplicity but at the cost of accuracy and clarity. Simplicity can also be
found with the proper noun is capitalized rule. It essentially boils down
to "only the CLI is lowercase" and has the added benefit of already being
used commonly and provides clarity to writing.
Examples:
The Nova team has...
for the OpenStack Compute (code name Nova) project. Nova is the...
To use the nova CLI...
In the terminal type: nova --help

All that said, I certainly agree that the legal/form name should be used
when possible. Indeed the Documentation team has been doing so for years so
there would be fairly little updating needed for many of those guides for a
switch to an initial capitalization.



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
>

Aha, I was thinking of it as a general convention, not tool specific.
Thanks for the links!


Looks like consensus is currently:
Keep all lowercase - 3
Use initial uppercase - 3


Thanks,
Amanda


On Sat, May 30, 2015 at 1:21 PM, Anne Gentle <annegentle at justwriteclick.com>
wrote:

>
>
> 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/20150601/f3e6f592/attachment-0001.html>


More information about the OpenStack-docs mailing list