[OpenStack-docs] Style Question for Project Names
Lana Brindley
openstack at lanabrindley.com
Sun May 31 23:12:39 UTC 2015
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Here are my current thoughts on initcaps for project names:
Personally, I would probably prefer upper case for the project name.
*However*:
* As Anne said, we really shouldn't be using the project names at all,
('Image service' instead of 'Glance', etc) so writing them out is often
a better option than arguing about capitalisation.
* It's much simpler to always lowercase, rather than have to remember,
explain, and understand a series of exceptions.
* Lowercase has been in force for some time now, and changing it will be
a massive amount of work. I'd rather we spend that time on something
useful, like the RST conversion, or improving the doc.
(Incidentally, I don't personally like the sentence-case headings,
either, but have rolled with it for more or less the same reasons).
L
On 31/05/15 12:17, Anne Gentle | Just Write Click wrote:
> On Sat, May 30, 2015 at 5:07 PM, Meg McRoberts <dreidellhasa at yahoo.com>
> wrote:
>
>> Thanks for the okay to use HAProxy -- it really was ugly without the
>> capitalization.
>>
>> Anne, not to put too fine a point on it, but commands, files, etc in Linux
>> do not have to be lowercase, although they often are.
>> I think the statement should be something like "Command, file, and
>> daemon/service names are case sensitive on Linux and,
>> in most cases, are lowercase."
>>
>
> Yep, fair point.
>
>
>>
>> I guess my mind is frozen in other conventions, but I like the distinction
>> between services and commands -- for example, "the glance
>> command implements the Glance service" -- which is probably not likely to
>> ever be written exactly like that but... And I'm not so sure
>> that the lack of capitalization is going to deter trademark hawks.
>>
>>
> Implements the Image service.
>
>
>> So this convention applies only to the services listed in
>> https://wiki.openstack.org/wiki/Documentation/Conventions#Service_and_project_names
>> ?
>> So Ceph and MongoDB are acceptable?
>>
>
> Ceph (http://ceph.com/legal-page/trademark-use-policy/) and MongoDB (
> http://www.mongodb.org/about/licensing/#mongodb-trademark-guidelines) are
> both trademarks.
>
> The OpenStack Foundation doesn't plan to trademark project names to my
> knowledge. So again, I think it's important not to uppercase them.
>
>
>>
>> Tangential point: sahara should have a mention of "savannah" with
>> commentary similar to that for neutron/quantum, and it really should mention
>> Hadoop, shouldn't it?
>>
>
> Yep, sounds right. And not to be too repetitive, but Hadoop is a registered
> trademark, https://hadoop.apache.org/.
>
>
>>
>> Sorry, everyone's a critic... I'll shut up now ;-)
>>
>
> Heh, no no it's fine! Words matter for many reasons and I want us all to be
> aware of legal names.
>
> Anne
>
>
>> meg
>>
>> ------------------------------
>> *From:* Anne Gentle <annegentle at justwriteclick.com>
>> *To:* APlimpton <aplimpton at gmail.com>
>> *Cc:* Meg McRoberts <dreidellhasa at yahoo.com>; "
>> openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org>
>> *Sent:* Saturday, May 30, 2015 1:21 PM
>>
>> *Subject:* Re: [OpenStack-docs] Style Question for Project Names
>>
>>
>>
>> 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
>>
>>
>>
>
>
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
- --
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQEcBAEBAgAGBQJVa5VnAAoJELppzVb4+KUyp/8H/RFOhEunu5XKp1Zy9UpPrsOt
CgUVD7ZzMG+rbVii0/jPwMXxpTx6FlbGFsVwW7WqjEAVvD7MEwv8EI7mg4RwbqtL
SxhJjg1GzQVCm7G99scGhkmUZBKAQuYA+eVM+04r4TG8kqS1LtpVuubRgxfYwz2r
mTAiqU3UlINSPNt9EdMNNbCQwBt+NEOScl4Lj4UY5JkuDX7bpMPltdtr0cH9W/Lz
lR/owZ7CtI5bzcxq3temxmIqKkAxftZBkG0mU5hL+G3SV76LyuMgie0ciZ0GRKCZ
PG8T5MaT2At7wNnGuuv6PBzhzHSgDouxSa95XiITWQY7LcEC7Mu+odqSThCnf2Y=
=+5wY
-----END PGP SIGNATURE-----
More information about the OpenStack-docs
mailing list