Bug 1306520 Document persistent volume storage labeling

[tnguyen-rh]

This is for BZ 1306520.

@ahardin-rh @adellape @bfallonf @tpoitras @jsafrane
PTAL.

[ahardin-rh]

"Term for Key/Value Pairs" and "Storage Type" are not showing up as bold headers here, though the "Project Name/PVC Name" headers in the table below are behaving properly.

[ahardin-rh]

@tnguyen-rh , just one comment. Other than that, LGTM! 🎆

[tnguyen-rh]

@ahardin-rh Thanks. I've removed the (dubious) options="headers" part and moved things around. The table header line is now bold, as expected.

[tpoitras]

I'm not sure that these commas are necessary.

[tnguyen-rh]

@tpoitras
Yeah, i think the sentence works w/o those commas, as well.

[tpoitras]

@tnguyen-rh made some suggestions 👍

[bfallonf]

"The term storage-provisioner label is what this documentation uses." Probably don't need to mention this here and above. Maybe get rid of it above, and keep it here, as we're about to talk about the table?

"This document uses the term storage-provisioner label in place of the three key/value pairs."

Also, is "understand" the right word? Maybe something like "use"?

[tnguyen-rh]

@bfallonf
Right, "understand" is not the best choice.

Hmm, getting rid of storage-provisioner label entirely is a good idea.

[bfallonf]

A few nits as well!

[jsafrane]

"associated with OpenShift" - I would use "dynamically created by OpenShift" to emphasize that we touch only volumes created by dynamic provisioning.

[jsafrane]

One minor nit, otherwise the documentation looks fine from technical point of view. I leave the style and exact wording for others to review.

[tnguyen-rh]

@jsafrane
Thanks for the review.

One last technical wrinkle: I invented the generic term storage-provisioner labels but am not completely happy w/ it, and would really prefer to use a term that OpenShift developers use or will use. I remember from our meeting that there is no such term at present. So the following questions are mostly a thought-experiment:

• Do you think storage-provisioner labels has a chance of being accepted (and used) by the OS devs?
• If yes, could you please start to use it in the code (e.g., in comments)?
• If maybe, what would be the objections?
• If no, what do you think will be the "winning" term, eventually?

[jsafrane]

In the code, we use term 'cloud tags' and 'Tags to attach to the real volume in the cloud provider - e.g. AWS EBS'. I don't think this should be the same in the documentation.

[tnguyen-rh]

@bfallonf @tpoitras
I've chosen another term, Volume Owner Information, and have reorganized a bit. Better?

[adellape]

s/visibile/visible/

[tnguyen-rh]

Che imabarazzo...

@adellape Thanks.

[bfallonf]

@tnguyen-rh LGTM 👍

[tnguyen-rh]

[rev_history]
|link:../install_config/persistent_storage/dynamically_provisioning_pvs.html[Configuring Persistent Storage -> Dynamic Provisioning]
|Documented link:../install_config/persistent_storage/dynamically_provisioning_pvs.html#volume-owner-info[Volume Owner Information].
%
|link:../install_config/persistent_storage/dynamically_provisioning_aws.html[Configuring Persistent Storage -> Persistent Storage Using AWS Elastic Block Store]
|Linked to link:../install_config/persistent_storage/dynamically_provisioning_pvs.html#volume-owner-info[Volume Owner Information].
%
|link:../install_config/persistent_storage/dynamically_provisioning_cinder.html[Configuring Persistent Storage -> Persistent Storage Using OpenStack Cinder]
|Linked to link:../install_config/persistent_storage/dynamically_provisioning_pvs.html#volume-owner-info[Volume Owner Information].
%
|link:../install_config/persistent_storage/dynamically_provisioning_gce.html[Configuring Persistent Storage -> Persistent Storage Using GCE Persistent Disk]
|Linked to link:../install_config/persistent_storage/dynamically_provisioning_pvs.html#volume-owner-info[Volume Owner Information].
%