openstack-doc-core team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

On Thu, Jun 25, 2015 at 5:17 AM, Andreas Jaeger <aj@xxxxxxxx> wrote:

> On 06/25/2015 12:04 PM, Steve Gordon wrote:
>
>> ----- Original Message -----
>>
>>> From: "Andreas Jaeger" <aj@xxxxxxxx>
>>> To: "Lana Brindley" <openstack@xxxxxxxxxxxxxxxx>,
>>> openstack-doc-core@xxxxxxxxxxxxxxxxxxx
>>>
>>> On 06/25/2015 02:16 AM, Lana Brindley wrote:
>>>
>>>> -----BEGIN PGP SIGNED MESSAGE-----
>>>> Hash: SHA1
>>>>
>>>> Hi everyone,
>>>>
>>>> First of all, I'm sorry that the Ironic docs thing has turned into a bit
>>>> of a disaster. I had no idea that we were going to end up in a standards
>>>> argument over this, but I'm still hopeful that we can see a path through
>>>> this.
>>>>
>>>> The problem: A number of patches (mostly created by Shilla, if I'm not
>>>> mistaken) are now being blocked in the Ironic repo by an Ironic core who
>>>> doesn't agree with our standards. While they're certainly entitled to
>>>> question our standards, blocking the patches means that other good work
>>>> is not getting merged.
>>>>
>>>> The solution: I'm not certain. Right now, what I want to do is send
>>>> email to Devananda (the Ironic PTL) with a list of the patches being
>>>> blocked, so we can determine if there's a way we can appease the Ironic
>>>> core team's concerns over standards. Shilla (and others who have a patch
>>>> out on this), can you please send me a list of the patches currently
>>>> being blocked?
>>>>
>>>> The fallout: We're already arguing about the standard in question on our
>>>> own list, and the community seems deeply divided. I personally don't
>>>> care about the capitalisation of service names, and am happy to enforce
>>>> whatever the community decides. That said, I feel as though the
>>>> community is unlikely to come to a solid conclusion on this. Do cores
>>>> have an opinion? If there is a strong tendency amongst this group,
>>>> perhaps it's easier to just go with that and adjust accordingly. Please
>>>> feel free to debate this topic on this thread.
>>>>
>>>
>>> So, this is "Ironic" vs "ironic"?
>>>
>>> I think what needs to be worked out with a project is that our
>>> conventions are enforced if we work together. Like there are hacking
>>> rules for code which a core team reviews, there are documentation rules
>>> that are under the Documentation team (btw. going to a reviewed style
>>> guide would help with the story;)!
>>>
>>> On the Ironic vs ironic: While I prefer the lower-case, I see upper-case
>>> everywhere.
>>>
>>> It's the number one change that I request during reviews.
>>>
>>> If we want to enforce our documentation style everywhere, it might be
>>> better to not enforce the capitalization or change the rule.
>>>
>>>
>>> So, I'm willing to change my vote if that is needed to adopt the Doc
>>> style everywhere ;)
>>>
>>> Anne, is the Doc style adoption a TC discussion?
>>>
>>> What do we need to make our style guide better consumable by other
>>> projects?
>>>
>>> Andreas
>>>
>>
>> This is the patch in question:
>>
>>      https://review.openstack.org/#/c/194230/1/reference/projects.yaml
>>
>> It's about Bare metal service versus Bare Metal service.
>>
>
> Thanks!
>
> Ah, that one ;(
>
> So, it's "Bare metal service" vs "Bare Metal service" vs "Bare Metal
> Service".
>
> We did a couple of consistency changes there and might need to go - as
> mentioned in the review - over the complete list to have consistency. And
> that discussion we need to have and I think Docs should have final say on
> it - but up for the TC,
>
>
Yes, it is up to the TC but they certainly want docs team input. I've put
my input on the patch itself:

---

For context: we are in this situation because of legal names, where some of
the original governance allowed projects to use "OpenStack" in the docs as
part of their name very early on. So, sometimes the phrasing needed
"service" to help with readability. Also, legally we were required to use
module due to branding with the OpenStack name.

So, the convention is:

   - Uppercase first letter of first word only.
   - Do not use OpenStack in the name of the service.
   - Use module if it is consuming other services (such as heat).
   - Use service in general as that is mostly what is being added as
   projects.

Now that we have the interop and brand guidelines, the use of OpenStack in
a name in the docs is not needed, but we still need to be very careful and
considerate in naming consistently.

Bare metal fits our first naming rule.

Changing these back and forth is not helpful. I will better document the
naming conventions in the governance repo to avoid this in the future.

---

But here's what I really want to say. To be high-value contributors to all
the projects we must avoid the reputation of being nit pickers.

Please review my rules above and see how they work for you in the docs,
especially for the newest projects that came in the last two weeks. I will
write a patch that describes the guidance for the governance repo based on
input here.

Thanks,
Anne


> 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
>
>
> --
> Mailing list: https://launchpad.net/~openstack-doc-core
> Post to     : openstack-doc-core@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack-doc-core
> More help   : https://help.launchpad.net/ListHelp
>