settingsLogin | Registersettings

[OpenStack-docs] Style Question for Project Names

0 votes

Hi All,

I am hoping this isn't secretly a hot button issue -- in our Conventions
page
(
https://wiki.openstack.org/wiki/Documentation/Conventions#OpenStack.2C_not_Openstack_or_openstack)
it says that the capitalization of the project team names (like swift,
nova, heat) are lowercase. It lists the official capitalization as
lowercase and further spells out that "When used as a command-line-client
name, lowercase is best. When used for the team or project name, typically
it's not necessary to capitalize."

I think that we should revise this convention so that team and project
names typically start with a capitalized letter. For example Cinder,
Neutron, Glance.
Reasons:
* The community seems to have embraced this style choice.
* This is a logical choice as it is a proper noun.
* It minimizes confusion if a reference is for project name or
command-line interface name.

How does the "change a convention" process work?

Thanks,
Amanda


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
asked May 29, 2015 in openstack-docs by APlimpton (1,000 points)   1

16 Responses

0 votes

On Fri, May 29, 2015 at 9:07 AM, APlimpton aplimpton@gmail.com wrote:

Hi All,

I am hoping this isn't secretly a hot button issue -- in our Conventions
page
(
https://wiki.openstack.org/wiki/Documentation/Conventions#OpenStack.2C_not_Openstack_or_openstack)
it says that the capitalization of the project team names (like swift,
nova, heat) are lowercase. It lists the official capitalization as
lowercase and further spells out that "When used as a command-line-client
name, lowercase is best. When used for the team or project name, typically
it's not necessary to capitalize."

I think that we should revise this convention so that team and project
names typically start with a capitalized letter. For example Cinder,
Neutron, Glance.
Reasons:
* The community seems to have embraced this style choice.
* This is a logical choice as it is a proper noun.
* It minimizes confusion if a reference is for project name or
command-line interface name.

How does the "change a convention" process work?

Well, you started in the right place by bringing it to the mailing list.

I think that you'll have to gather consensus here, then also be willing to
change it everywhere. That's a lot of change in openstack-manuals and other
official documents. In the developer docs I'm sure they use the team names
in ways we wouldn't approve.

I personally strongly argue to eliminate team names to avoid confusion. Try
hard not to ever ever use them in documentation. It's awful to have to look
up a list of names and map to what the service actually is or does. The
names are meaningless, chosen by random lookkups, and get changed due to
trademarking issues, such as quantum/neutron, marconi/zaqar so far.

I dislike deep diving on convention arguments so I'll stop here, but just
wanted to let you know the process and my "feels" on this particular issue.
:)
Thanks,
Anne

Thanks,
Amanda


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

--
Anne Gentle
annegentle@justwriteclick.com


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 29, 2015 by annegentle_at_justwr (9,780 points)   2 5 6
0 votes

Hi Anne,

Thanks for confirming I am on the right track. I am quite willing to hunt
down and replace across the docs. Right now it is inconsistent (sometimes
on the same page) but seems to be skewing towards the capitalized version.

I can see why you are staunchly for project name removal and I have noticed
how the main website only references the functional names.

Hopefully consensus can be reached soon. :)

Thanks,

On Fri, May 29, 2015 at 7:39 AM, Anne Gentle annegentle@justwriteclick.com
wrote:

On Fri, May 29, 2015 at 9:07 AM, APlimpton aplimpton@gmail.com wrote:

Hi All,

I am hoping this isn't secretly a hot button issue -- in our Conventions
page
(
https://wiki.openstack.org/wiki/Documentation/Conventions#OpenStack.2C_not_Openstack_or_openstack)
it says that the capitalization of the project team names (like swift,
nova, heat) are lowercase. It lists the official capitalization as
lowercase and further spells out that "When used as a command-line-client
name, lowercase is best. When used for the team or project name, typically
it's not necessary to capitalize."

I think that we should revise this convention so that team and project
names typically start with a capitalized letter. For example Cinder,
Neutron, Glance.
Reasons:
* The community seems to have embraced this style choice.
* This is a logical choice as it is a proper noun.
* It minimizes confusion if a reference is for project name or
command-line interface name.

How does the "change a convention" process work?

Well, you started in the right place by bringing it to the mailing list.

I think that you'll have to gather consensus here, then also be willing to
change it everywhere. That's a lot of change in openstack-manuals and other
official documents. In the developer docs I'm sure they use the team names
in ways we wouldn't approve.

I personally strongly argue to eliminate team names to avoid confusion.
Try hard not to ever ever use them in documentation. It's awful to have to
look up a list of names and map to what the service actually is or does.
The names are meaningless, chosen by random lookkups, and get changed due
to trademarking issues, such as quantum/neutron, marconi/zaqar so far.

I dislike deep diving on convention arguments so I'll stop here, but just
wanted to let you know the process and my "feels" on this particular issue.
:)
Thanks,
Anne

Thanks,
Amanda


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

--
Anne Gentle
annegentle@justwriteclick.com


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 29, 2015 by APlimpton (1,000 points)   1
0 votes

On 05/29/2015 08:08 PM, APlimpton wrote:
Hi Anne,

Thanks for confirming I am on the right track. I am quite willing to
hunt down and replace across the docs. Right now it is inconsistent
(sometimes on the same page) but seems to be skewing towards the
capitalized version.

There shouldn't be many inconsistencies, if you find some, please tell
us or fix them (no need for a bug).

I can see why you are staunchly for project name removal and I have
noticed how the main website only references the functional names.

Hopefully consensus can be reached soon. :)

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...

Andreas
--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,
HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 29, 2015 by Andreas_Jaeger (17,140 points)   2 3 4
0 votes

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@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@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 29, 2015 by christian_at_berendt (3,780 points)   3 8
0 votes

+1

Sent from my iPhone

On May 29, 2015, at 4:22 PM, Christian Berendt christian@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@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@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 29, 2015 by Shilla_Saebi (1,020 points)   1
0 votes

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. :)

Thanks,
Amanda

On Fri, May 29, 2015 at 1:37 PM, Shilla Saebi shilla.saebi@gmail.com
wrote:

+1

Sent from my iPhone

On May 29, 2015, at 4:22 PM, Christian Berendt christian@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@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@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 29, 2015 by APlimpton (1,000 points)   1
0 votes

On Fri, May 29, 2015 at 4:36 PM, APlimpton aplimpton@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@gmail.com
wrote:

+1

Sent from my iPhone

On May 29, 2015, at 4:22 PM, Christian Berendt christian@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@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@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

--
Anne Gentle
annegentle@justwriteclick.com


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 29, 2015 by annegentle_at_justwr (9,780 points)   2 5 6
0 votes

Looks like HAProxy and other pieces that are sold separately or trademarked
should follow their own standard for capitalization (per IBM style guide
again).

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.

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?

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.

Thanks,
Amanda

On Fri, May 29, 2015 at 3:24 PM, Meg McRoberts dreidellhasa@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@justwriteclick.com
To: APlimpton aplimpton@gmail.com
Cc: "openstack-docs@lists.openstack.org" <
openstack-docs@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@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@gmail.com
wrote:

+1

Sent from my iPhone

On May 29, 2015, at 4:22 PM, Christian Berendt christian@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@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@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

--
Anne Gentle
annegentle@justwriteclick.com


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 30, 2015 by APlimpton (1,000 points)   1
0 votes

On Sat, May 30, 2015 at 2:39 PM, APlimpton aplimpton@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- 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@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@justwriteclick.com
To: APlimpton aplimpton@gmail.com
Cc: "openstack-docs@lists.openstack.org" <
openstack-docs@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@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@gmail.com
wrote:

+1

Sent from my iPhone

On May 29, 2015, at 4:22 PM, Christian Berendt christian@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@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@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

--
Anne Gentle
annegentle@justwriteclick.com


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

--
Anne Gentle
annegentle@justwriteclick.com


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 30, 2015 by annegentle_at_justwr (9,780 points)   2 5 6
0 votes

Also while we're at it can we decide if it should be "an SQL" or "a SQL" and doc that in the conventions page? That way there is consistency across the board.

Sent from my iPhone

On May 30, 2015, at 4:21 PM, Anne Gentle annegentle@justwriteclick.com wrote:

On Sat, May 30, 2015 at 2:39 PM, APlimpton aplimpton@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- 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@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@justwriteclick.com
To: APlimpton aplimpton@gmail.com
Cc: "openstack-docs@lists.openstack.org" openstack-docs@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@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@gmail.com wrote:
+1

Sent from my iPhone

On May 29, 2015, at 4:22 PM, Christian Berendt christian@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@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@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

--
Anne Gentle
annegentle@justwriteclick.com


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

--
Anne Gentle
annegentle@justwriteclick.com


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 30, 2015 by Shilla_Saebi (1,020 points)   1
...