Re: [Openstack-doc-core] Ironic docs Service name standards
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 10/07/15 11:34, Anne Gentle wrote: On Jul 9, 2015, at 8:25 PM, Lana Brindley openst...@lanabrindley.com wrote: On 08/07/15 22:41, Anne Gentle wrote: On Wed, Jul 8, 2015 at 1:16 AM, Andreas Jaeger a...@suse.com wrote: On 06/25/2015 04:10 PM, Anne Gentle wrote: 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. Anne, I saw your comment on: https://review.openstack.org/194230 So, changing to Block storage, Object storage, Bare metal looks strange to me. But I'm neither a native speaker nor an editor. Heh, my thinking is anything will look strange to us after editing Block Storage for years. I really don't want to get into the explanations for Key-Value vs. Key-value so I prefer the initial cap everywhere for simplicity. I'm of course open to discussion. If this list really can't imagine these guidelines working I can revisit. Looking forward to the patch - and perhaps a short list as overview to review. Btw. did you see the thread [openstack-dev] Should project name be uppercase or lowercase? I think I replied on the review then on the thread, do you see it now? Anne, I see that patch (https://review.openstack.org/#/c/194230) is now more or less stalled. Where are we at now? I need to do a new patch with the guidelines. OK, cool. Let me know if you need anything from me :) L - -- Lana Brindley Technical Writer Rackspace Cloud Builders Australia http://lanabrindley.com -BEGIN PGP SIGNATURE- Version: GnuPG v1 iQEcBAEBAgAGBQJVnyGfAAoJELppzVb4+KUyQFQH/0byWq7ThwyH6CR4+LFcUwOk YnXosQzq7MTIlTcrpUJEPsCqu7Sh2oazstSF6916sB6dcPjBxMGxzJlaOxmF96M5 y65INrGK8nLfk70n2pVo2I60ysg5XEQvubO/7zYXZPx57ud6qld55fZsUsXneP1V afS2EGmyFNfUA/2D7LxS6S/acvd2HMpdM4hyhIB2sl9zOTqtCQBFP7p4pUeFJ8MB BwAQW22WBCf2jf5RRLNR5fScOwoSaqCj6jS0a3QrpAF0xR2bfY4Kk/uNCipSXwSy e1XQfU5StKNxdN33gyUILHGew0P76roL51qPdeujXxRPPujmOokB2Xy74Sz6rWs= =kRoQ -END PGP SIGNATURE- -- Mailing list: https://launchpad.net/~openstack-doc-core Post to : openstack-doc-core@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack-doc-core More help : https://help.launchpad.net/ListHelp
Re: [Openstack-doc-core] Ironic docs Service name standards
On Wed, Jul 8, 2015 at 1:16 AM, Andreas Jaeger a...@suse.com wrote:
On 06/25/2015 04:10 PM, Anne Gentle wrote:
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.
Anne, I saw your comment on:
https://review.openstack.org/194230
So, changing to Block storage, Object storage, Bare metal looks
strange to me. But I'm neither a native speaker nor an editor.
Heh, my thinking is anything will look strange to us after editing Block
Storage for years.
I really don't want to get into the explanations for Key-Value vs.
Key-value so I prefer the initial cap everywhere for simplicity. I'm of
course open to discussion. If this list really can't imagine these
guidelines working I can revisit.
Looking forward to the patch - and perhaps a short list as overview to
review.
Btw. did you see the thread [openstack-dev] Should project name be
uppercase or lowercase?
I think I replied on the review then on the thread, do you see it now?
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@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack-doc-core
More help : https://help.launchpad.net/ListHelp
Re: [Openstack-doc-core] Ironic docs Service name standards
On 06/25/2015 04:10 PM, Anne Gentle wrote: On Thu, Jun 25, 2015 at 5:17 AM, Andreas Jaeger a...@suse.com mailto:a...@suse.com wrote: On 06/25/2015 12:04 PM, Steve Gordon wrote: - Original Message - From: Andreas Jaeger a...@suse.com mailto:a...@suse.com To: Lana Brindley openst...@lanabrindley.com mailto:openst...@lanabrindley.com, openstack-doc-core@lists.launchpad.net mailto:openstack-doc-core@lists.launchpad.net 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
Re: [Openstack-doc-core] Ironic docs Service name standards
On Thu, Jun 25, 2015 at 6:50 PM, Lana Brindley openst...@lanabrindley.com wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Comments inline, with extensive snipping ... On 26/06/15 01:39, Anne Gentle wrote: snip 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, I would really like to find out how the TC feel about this one. 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. +1 The way I see this is that the Ironic team asked for 'copy editing and information architecture assistance'. The first thing to when providing that assistance is to pick the low-hanging fruit: typos, grammar, and (yes) conventions. Of course, we wouldn't be doing any of that if they hadn't specifically asked for it. So, your advise for projects like Ironic would be not to send a number of patches that change all conventions and don't do anything else? Yes. Because: - Their contributors should follow OpenStack conventions if they want to be published to docs.openstack.org. - We want docs to be self-service, as in, we give you conventions, you follow them and review to those conventions. If you disagree with them you politely bring it up on the -docs mailing list but still agree to follow conventions. This works in situations where they're maintaining their own docs in their own repos. When they've specifically come and asked us for assistance, though, it's a different story. - Higher-value contributions happen with information architecture, tested docs, and accuracy/speed in reviews and corrections. I do agree with this point. I guess the way I see it is you have to start with the small stuff. You have to get your house cleaned up before you can rearrange the furniture. And newly written docs that mix with existing ones? Which conventions should those use? 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. I look forward to seeing this. One example: Object Storage. And we should probably merge our wiki page with the text below or make it clearer why we use OpenStack Compute but Orchestration module for OpenStack. Agreed. I think there's no small amount of confusion over why it is the way it is. Revising service guidance: Use service when the provided capability is a noun (Image, Database) and do not add service when the capability is a capacity (Compute, Bare metal). Would that work? 'Bare metal' is a noun. I'm not sure this makes sense. Yep, good point. I'm working with our editor on better guidelines and I'll post soon. I've been continuing to reply on the review itself if anyone wants to follow along. I'm particularly concerned about what happens when we have two projects in the tent, both doing say a monitoring solution for OpenStack. We seem to already have multiple application workflow and catalog projects. We need to get these guidelines right and tackle the naming now. Thanks, Anne L - -- Lana Brindley Technical Writer Rackspace Cloud Builders Australia http://lanabrindley.com -BEGIN PGP SIGNATURE- Version: GnuPG v1 iQEcBAEBAgAGBQJVjJOoAAoJELppzVb4+KUyWmUIALfv1i0GvjE8Zv0KvlAGrwmH 0lxD7zXd7iRhCdm/E39pzPdqRHKTTAwCauqBHVkYedrQazRv4rJUjlNeEms4Wnwu
Re: [Openstack-doc-core] Ironic docs Service name standards
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Comments inline, with extensive snipping ... On 26/06/15 01:39, Anne Gentle wrote: snip 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, I would really like to find out how the TC feel about this one. 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. +1 The way I see this is that the Ironic team asked for 'copy editing and information architecture assistance'. The first thing to when providing that assistance is to pick the low-hanging fruit: typos, grammar, and (yes) conventions. Of course, we wouldn't be doing any of that if they hadn't specifically asked for it. So, your advise for projects like Ironic would be not to send a number of patches that change all conventions and don't do anything else? Yes. Because: - Their contributors should follow OpenStack conventions if they want to be published to docs.openstack.org. - We want docs to be self-service, as in, we give you conventions, you follow them and review to those conventions. If you disagree with them you politely bring it up on the -docs mailing list but still agree to follow conventions. This works in situations where they're maintaining their own docs in their own repos. When they've specifically come and asked us for assistance, though, it's a different story. - Higher-value contributions happen with information architecture, tested docs, and accuracy/speed in reviews and corrections. I do agree with this point. I guess the way I see it is you have to start with the small stuff. You have to get your house cleaned up before you can rearrange the furniture. And newly written docs that mix with existing ones? Which conventions should those use? 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. I look forward to seeing this. One example: Object Storage. And we should probably merge our wiki page with the text below or make it clearer why we use OpenStack Compute but Orchestration module for OpenStack. Agreed. I think there's no small amount of confusion over why it is the way it is. Revising service guidance: Use service when the provided capability is a noun (Image, Database) and do not add service when the capability is a capacity (Compute, Bare metal). Would that work? 'Bare metal' is a noun. I'm not sure this makes sense. L - -- Lana Brindley Technical Writer Rackspace Cloud Builders Australia http://lanabrindley.com -BEGIN PGP SIGNATURE- Version: GnuPG v1 iQEcBAEBAgAGBQJVjJOoAAoJELppzVb4+KUyWmUIALfv1i0GvjE8Zv0KvlAGrwmH 0lxD7zXd7iRhCdm/E39pzPdqRHKTTAwCauqBHVkYedrQazRv4rJUjlNeEms4Wnwu RyTwyR3RLokcBr/S8WY6hlXIue8DgA/OAFWqxCfJA/apWBgZD840jrdkTKc4D9Jn cmIIbo4vpzJyakhfCMjQH5vTFZE01n3TAZ4QDzVlK9N1lRZby78FzGZYmHofYUdB T9HNDJ3Ea8Fk/5gq56O5LV98MAo3BMTHo3l6AbCV3BpzDYL9MjnJ1PNy+8ml8TYn t8RiHLvddtTDv39u0N5AUcOtSngAaa5dlOU19QRlbxW1xhyp8oPuGrkiQfVZt7g= =xpQQ -END PGP SIGNATURE- -- Mailing list: https://launchpad.net/~openstack-doc-core Post to : openstack-doc-core@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack-doc-core More help : https://help.launchpad.net/ListHelp
