openstack-doc-core team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

On Thu, Jun 25, 2015 at 6:50 PM, Lana Brindley <openstack@xxxxxxxxxxxxxxxx>
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
> 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@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack-doc-core
> More help   : https://help.launchpad.net/ListHelp
>