Update Service Catalog docs to meet style guidelines #7341

chenopis · 2018-02-09T22:47:01Z

This change is

k8sio-netlify-preview-bot · 2018-02-09T22:50:04Z

Deploy preview for kubernetes-io-master-staging ready!

Built with commit 74056d4

https://deploy-preview-7341--kubernetes-io-master-staging.netlify.com

steveperry-53 · 2018-02-09T23:19:01Z

docs/concepts/service-catalog/index.md

@@ -7,10 +7,10 @@ approvers:
 {% capture overview %}
 {% glossary_definition term_id="service-catalog" length="all" prepend="Service Catalog is" %}  

-A *Service Broker*, as defined by the [Open Service Broker API spec](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md), is an endpoint for a set of Managed Services offered and maintained by a third-party, which could be a cloud provider such as AWS, GCP, or Azure.
-Some examples of *Managed Services* are Microsoft Azure Cloud Queue, Amazon Simple Queue Service, and Google Cloud Pub/Sub, but they can be any software offering that can be used by an application.
+A Service Broker, as defined by the [Open Service Broker API spec](https://github.com/openservicebrokerapi/servicebroker/blob/v2.13/spec.md), is an endpoint for a set of Managed Services offered and maintained by a third-party, which could be a cloud provider such as AWS, GCP, or Azure.


This is a global comment. Here's just one example:

"It provides a way to list, provision, and bind with external managed services from service brokers."

No caps for "managed services". No caps for "service brokers". Unless those things are proper names, but I don't think they are.

acknowledged

steveperry-53 · 2018-02-09T23:23:37Z

docs/concepts/service-catalog/index.md


-Using Service Catalog, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can browse the list of {% glossary_tooltip text="Managed Services" term_id="managed-service" %} offered by a {% glossary_tooltip text="Service Brokers" term_id="service-broker" %}, provision an instance of a Managed Service, and bind with it to make it available to an application within the Kubernetes cluster.
+Using Service Catalog, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can browse the list of Managed Services offered by a Service Broker, provision an instance of a Managed Service, and bind with it to make it available to an application within the Kubernetes cluster.


It looks like it would be easy enough to use lower case for tool tips.
text="cluster operator"

Ok, I'll lowercase the tooltips.

steveperry-53 · 2018-02-09T23:25:33Z

docs/concepts/service-catalog/index.md

@@ -20,10 +20,10 @@ Using Service Catalog, a {% glossary_tooltip text="Cluster Operator" term_id="cl

 An {% glossary_tooltip text="Application Developer" term_id="application-developer" %} wants to use message queuing as part of their application running in a Kubernetes cluster.
 However, they do not want to deal with the overhead of setting such a service up and administering it themselves.
-Fortunately, there is a cloud provider that offers message queuing as a *Managed Service* through their *Service Broker*.
+Fortunately, there is a cloud provider that offers message queuing as a Managed Service through their Service Broker.


through their -> through its

steveperry-53 · 2018-02-09T23:27:38Z

docs/concepts/service-catalog/index.md


-Using Service Catalog, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can browse the list of {% glossary_tooltip text="Managed Services" term_id="managed-service" %} offered by a {% glossary_tooltip text="Service Brokers" term_id="service-broker" %}, provision an instance of a Managed Service, and bind with it to make it available to an application within the Kubernetes cluster.
+Using Service Catalog, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can browse the list of Managed Services offered by a Service Broker, provision an instance of a Managed Service, and bind with it to make it available to an application within the Kubernetes cluster.


We can save this for the style guide discussion. But I think that using "within" instead of "in" goes against our style guideline of using simple and direct language.

Same for "in order to" vs. "to".

steveperry-53 · 2018-02-09T23:29:55Z

docs/concepts/service-catalog/index.md

-A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can setup Service Catalog and use it to communicate with the cloud provider's {% glossary_tooltip text="Service Broker" term_id="service-broker" %} to provision an instance of the message queuing service and make it available to the application within the Kubernetes cluster.
-The {% glossary_tooltip text="Application Developer" term_id="application-developer" %} therefore does not need to concern themselves with the implementation details or management of the message queue.
+A Cluster Operator can setup Service Catalog and use it to communicate with the cloud provider's Service Broker to provision an instance of the message queuing service and make it available to the application within the Kubernetes cluster.
+The Application Developer therefore does not need to concern themselves with the implementation details or management of the message queue.


If we say, "does not need to be concerned with the implementation details", we can avoid the awkward use of "themselves" to refer to a single person.

Same for "Their application". We could just say, "The application".

steveperry-53 · 2018-02-09T23:33:35Z

docs/concepts/service-catalog/index.md

-A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can setup Service Catalog and use it to communicate with the cloud provider's {% glossary_tooltip text="Service Broker" term_id="service-broker" %} to provision an instance of the message queuing service and make it available to the application within the Kubernetes cluster.
-The {% glossary_tooltip text="Application Developer" term_id="application-developer" %} therefore does not need to concern themselves with the implementation details or management of the message queue.
+A Cluster Operator can setup Service Catalog and use it to communicate with the cloud provider's Service Broker to provision an instance of the message queuing service and make it available to the application within the Kubernetes cluster.
+The Application Developer therefore does not need to concern themselves with the implementation details or management of the message queue.
 Their application can simply use it as a service.



No cap for etcd.
https://coreos.com/etcd/

steveperry-53 · 2018-02-09T23:41:58Z

docs/concepts/service-catalog/index.md

-A {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can setup Service Catalog and use it to communicate with the cloud provider's {% glossary_tooltip text="Service Broker" term_id="service-broker" %} to provision an instance of the message queuing service and make it available to the application within the Kubernetes cluster.
-The {% glossary_tooltip text="Application Developer" term_id="application-developer" %} therefore does not need to concern themselves with the implementation details or management of the message queue.
+A Cluster Operator can setup Service Catalog and use it to communicate with the cloud provider's Service Broker to provision an instance of the message queuing service and make it available to the application within the Kubernetes cluster.
+The Application Developer therefore does not need to concern themselves with the implementation details or management of the message queue.
 Their application can simply use it as a service.

 ## Architecture


"It is implemented as an extension API server and a controller manager.

I think this should be "controller", not "controller manager".

https://github.com/kubernetes-incubator/service-catalog/blob/master/docs/design.md

steveperry-53 · 2018-02-09T23:48:48Z

docs/concepts/service-catalog/index.md

@@ -62,7 +62,7 @@ Service Catalog supports these methods of authentication:



"Similar to ClusterServiceClass, when a new ClusterServiceBroker is added to the cluster, the Service Catalog creates a new ClusterServicePlan resource corresponding to each Service Plan available for each Managed Service."

If we are using Service Catalog as a proper name (and I think we are), then "the Service Catalog" should be "Service Catalog".

"the Service Catalog controller will connect to the appropriate Service Broker and instruct it to provision the service instance."

will connect -> connects
instruct -> instructs

" who want their applications to make use of a Service ServiceInstance. Upon creation, the Service Catalog controller will create"

Is "Service ServiceInstance" correct? Or should it just be "ServiceInstance"?
will create -> creates

done
yeah, "Service ServiceInstance" was a typo

steveperry-53 · 2018-02-10T01:00:13Z

docs/concepts/service-catalog/index.md

@@ -95,7 +95,7 @@ The following is a sequence diagram illustrating the steps involved in listing M

 1. Once the `ClusterServiceBroker` resource is added to Service Catalog, it triggers a *List Services* call to the external Service Broker.


No italics for List Services. Maybe no caps. Not sure what List Services is. Is it a method name: ListServices? If so, then use backticks.

Same for the Provision Instance and Bind Instance calls that come later.

I was trying to avoid the name of the actual API call in the Open Service Broker API by using their terminology. I have rewritten the three to avoid this awkwardness.

steveperry-53 · 2018-02-10T01:02:41Z

docs/concepts/service-catalog/index.md

@@ -95,7 +95,7 @@ The following is a sequence diagram illustrating the steps involved in listing M

 1. Once the `ClusterServiceBroker` resource is added to Service Catalog, it triggers a *List Services* call to the external Service Broker.
 1. The Service Broker returns a list of available Managed Services and Service Plans, which are cached locally in `ClusterServiceClass` and `ClusterServicePlan` resources.


It's the list that is cached, correct? It's not the Services and ServicePlans that are cached.

So I think this should be "which is cached locally".

Yes, the lists are cached in the local ClusterServiceClass and ClusterServicePlan resources. How about "The service broker returns a list of available managed services and a list of Service Plans, which are cached locally as ClusterServiceClass and ClusterServicePlan resources respectively."

steveperry-53 · 2018-02-10T01:11:09Z

docs/concepts/service-catalog/index.md


 ### Binding to a Managed Service

-After a new instance has been provisioned, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} must bind to the Managed Service to get the connection credentials and service account details necessary for the application to use the service. This is done by creating a `ServiceBinding` resource.
+After a new instance has been provisioned, a Cluster Operator must bind to the Managed Service to get the connection credentials and service account details necessary for the application to use the service. This is done by creating a `ServiceBinding` resource.

 The following is an example of a `ServiceBinding` resource:


Use sentence case for headings: Pod configuration file, not Pod Configuration File

steveperry-53 · 2018-02-10T01:16:29Z

docs/concepts/service-catalog/index.md


-Using Service Catalog, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can browse the list of {% glossary_tooltip text="Managed Services" term_id="managed-service" %} offered by a {% glossary_tooltip text="Service Brokers" term_id="service-broker" %}, provision an instance of a Managed Service, and bind with it to make it available to an application within the Kubernetes cluster.
+Using Service Catalog, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can browse the list of Managed Services offered by a Service Broker, provision an instance of a Managed Service, and bind with it to make it available to an application within the Kubernetes cluster.


The Cluster Operator tool tip and the Application Developer tool tip return 404s.

steveperry-53 · 2018-02-10T01:20:18Z

@chenopis Thanks for getting this going. I've finished my review.

chenopis · 2018-02-12T18:57:23Z

/hold

chenopis · 2018-02-20T23:03:47Z

/unhold

…ossary

chenopis · 2018-02-20T23:08:44Z

@steveperry-53 I addressed all of your comments, PTAL.

steveperry-53 · 2018-02-22T21:45:52Z

/approve

steveperry-53 · 2018-02-22T21:47:01Z

@chenopis Would you like me to give the LGTM as well?

chenopis · 2018-02-22T22:58:03Z

@steveperry-53 Yeah sure, that would be great. Thx!

steveperry-53 · 2018-02-22T23:07:53Z

/lgtm

k8s-ci-robot · 2018-02-22T23:08:04Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: steveperry-53

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [steveperry-53]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

* Update Service Catalog docs to meet style guidelines * Address stevepe's comments * Remove full-links to cluster operator and application developer in glossary

chenopis assigned steveperry-53 Feb 9, 2018

chenopis requested a review from jesscodez February 9, 2018 22:47

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Feb 9, 2018

k8s-ci-robot requested review from tengqm and zhangxiaoyu-zidif February 9, 2018 22:47

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Feb 9, 2018

steveperry-53 reviewed Feb 9, 2018

View reviewed changes

steveperry-53 reviewed Feb 10, 2018

View reviewed changes

k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Feb 12, 2018

chenopis force-pushed the chenopis-sc-patch branch from ad184ff to 4285532 Compare February 20, 2018 22:58

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed approved Indicates a PR has been approved by an approver from all required OWNERS files. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Feb 20, 2018

chenopis added 2 commits February 20, 2018 15:01

Update Service Catalog docs to meet style guidelines

b843325

Address stevepe's comments

b0f513c

chenopis force-pushed the chenopis-sc-patch branch from c09e97e to b0f513c Compare February 20, 2018 23:01

k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Feb 20, 2018

Remove full-links to cluster operator and application developer in gl…

74056d4

…ossary

chenopis removed request for tengqm and zhangxiaoyu-zidif February 20, 2018 23:08

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Feb 22, 2018

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 22, 2018

k8s-ci-robot merged commit 0f178d4 into master Feb 22, 2018

chenopis deleted the chenopis-sc-patch branch March 13, 2018 23:37

chenopis added the team/google label Aug 6, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update Service Catalog docs to meet style guidelines #7341

Update Service Catalog docs to meet style guidelines #7341

chenopis commented Feb 9, 2018 •

edited by k8s-reviewable

Loading

k8sio-netlify-preview-bot commented Feb 9, 2018 •

edited

Loading

steveperry-53 Feb 9, 2018 •

edited

Loading

chenopis Feb 20, 2018

steveperry-53 Feb 9, 2018

chenopis Feb 14, 2018

steveperry-53 Feb 9, 2018

chenopis Feb 14, 2018

steveperry-53 Feb 9, 2018 •

edited

Loading

chenopis Feb 14, 2018

steveperry-53 Feb 9, 2018 •

edited

Loading

chenopis Feb 14, 2018

steveperry-53 Feb 9, 2018

chenopis Feb 14, 2018

steveperry-53 Feb 9, 2018

chenopis Feb 14, 2018

steveperry-53 Feb 9, 2018 •

edited

Loading

chenopis Feb 15, 2018

steveperry-53 Feb 10, 2018 •

edited

Loading

chenopis Feb 20, 2018

steveperry-53 Feb 10, 2018

chenopis Feb 20, 2018

steveperry-53 Feb 10, 2018

chenopis Feb 20, 2018

steveperry-53 Feb 10, 2018

steveperry-53 commented Feb 10, 2018

chenopis commented Feb 12, 2018

chenopis commented Feb 20, 2018

chenopis commented Feb 20, 2018

steveperry-53 commented Feb 22, 2018

steveperry-53 commented Feb 22, 2018

chenopis commented Feb 22, 2018

steveperry-53 commented Feb 22, 2018

k8s-ci-robot commented Feb 22, 2018


		Using Service Catalog, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can browse the list of {% glossary_tooltip text="Managed Services" term_id="managed-service" %} offered by a {% glossary_tooltip text="Service Brokers" term_id="service-broker" %}, provision an instance of a Managed Service, and bind with it to make it available to an application within the Kubernetes cluster.
		Using Service Catalog, a {% glossary_tooltip text="Cluster Operator" term_id="cluster-operator" %} can browse the list of Managed Services offered by a Service Broker, provision an instance of a Managed Service, and bind with it to make it available to an application within the Kubernetes cluster.

		@@ -62,7 +62,7 @@ Service Catalog supports these methods of authentication:

		@@ -95,7 +95,7 @@ The following is a sequence diagram illustrating the steps involved in listing M

		1. Once the `ClusterServiceBroker` resource is added to Service Catalog, it triggers a List Services call to the external Service Broker.

		@@ -95,7 +95,7 @@ The following is a sequence diagram illustrating the steps involved in listing M

		1. Once the `ClusterServiceBroker` resource is added to Service Catalog, it triggers a List Services call to the external Service Broker.
		1. The Service Broker returns a list of available Managed Services and Service Plans, which are cached locally in `ClusterServiceClass` and `ClusterServicePlan` resources.

Update Service Catalog docs to meet style guidelines #7341

Update Service Catalog docs to meet style guidelines #7341

Conversation

chenopis commented Feb 9, 2018 • edited by k8s-reviewable Loading

k8sio-netlify-preview-bot commented Feb 9, 2018 • edited Loading

steveperry-53 Feb 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveperry-53 Feb 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveperry-53 Feb 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveperry-53 Feb 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveperry-53 Feb 10, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveperry-53 commented Feb 10, 2018

chenopis commented Feb 12, 2018

chenopis commented Feb 20, 2018

chenopis commented Feb 20, 2018

steveperry-53 commented Feb 22, 2018

steveperry-53 commented Feb 22, 2018

chenopis commented Feb 22, 2018

steveperry-53 commented Feb 22, 2018

k8s-ci-robot commented Feb 22, 2018

chenopis commented Feb 9, 2018 •

edited by k8s-reviewable

Loading

k8sio-netlify-preview-bot commented Feb 9, 2018 •

edited

Loading

steveperry-53 Feb 9, 2018 •

edited

Loading

steveperry-53 Feb 9, 2018 •

edited

Loading

steveperry-53 Feb 9, 2018 •

edited

Loading

steveperry-53 Feb 9, 2018 •

edited

Loading

steveperry-53 Feb 10, 2018 •

edited

Loading