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