Open Stack

Does anyone else want to add a yea or nay about capitalizing project names
before we put this topic to bed?

Thanks :)
Amanda

On Mon, Jun 1, 2015 at 10:37 AM, Cannon, Chris <ccannon at hp.com> wrote:

>  I support the move to capitalize. (in case you’re keeping track)
>
>
>
> *From:* APlimpton [mailto:aplimpton at gmail.com]
> *Sent:* Monday, June 01, 2015 12:25 AM
> *To:* Anne Gentle
> *Cc:* openstack-docs at lists.openstack.org
>
> *Subject:* Re: [OpenStack-docs] Style Question for Project Names
>
>
>
> 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/20150618/46694377/attachment-0001.html>