On Thu, Jun 25, 2015 at 10:13 AM, Andreas Jaeger <a...@suse.com> wrote:
> 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 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. >> > > 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. - Higher-value contributions happen with information architecture, tested docs, and accuracy/speed in reviews and corrections. > > 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. >> > > 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". > > Current list of services in projects.yaml: > service: Compute > service: Object Storage > should be storage > service: Image service > service: Identity > service: Dashboard > service: Networking > service: Block Storage > should be storage > service: Telemetry > service: Orchestration > service: Database service > service: Bare metal service > service: Common libraries > service: Deployment > service: Message service > service: Data processing service > service: Key management service > service: DNS service > service: Containers service > service: Shared file systems > service: Application catalog > service: command line client > service: Governance service > service: Benchmark service > service: Workflow service > service: Key-Value Store as a Service > Key-value storage > service: Puppet modules for the OpenStack components > service: Chef cookbooks for the OpenStack components > service: Search service > service: Ansible Playbooks and Roles for the deployment of OpenStack > > > 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? > 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
