openstack-doc-core team mailing list archive

[Lana Brindley <openstack@xxxxxxxxxxxxxxxx>]

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