openstack-doc-core team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

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

> On 06/25/2015 04:10 PM, Anne Gentle wrote:
>
>>
>>
>> On Thu, Jun 25, 2015 at 5:17 AM, Andreas Jaeger <aj@xxxxxxxx
>> <mailto:aj@xxxxxxxx>> wrote:
>>
>>     On 06/25/2015 12:04 PM, Steve Gordon wrote:
>>
>>         ----- Original Message -----
>>
>>             From: "Andreas Jaeger" <aj@xxxxxxxx <mailto:aj@xxxxxxxx>>
>>             To: "Lana Brindley" <openstack@xxxxxxxxxxxxxxxx
>>             <mailto:openstack@xxxxxxxxxxxxxxxx>>,
>>             openstack-doc-core@xxxxxxxxxxxxxxxxxxx
>>             <mailto: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.
>>
>
> 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
>
>