Move docs/services-firewalls.md into docs/user-guide/ and make small

wording changes to api.md

Author: David Oppenheimer

docs/api.md

@@ -44,9 +44,9 @@ What constitutes a compatible change and how to change the API are detailed by t
 
 ## API versioning
 
-Fine-grain resource evolution alone makes it difficult to eliminate fields or restructure resource representations. Therefore, Kubernetes supports multiple API versions, each at a different API path prefix, such as `/api/v1beta3`. These are simply different interfaces to read and/or modify the same underlying resources. In general, all API resources are accessible via all API versions, though there may be some cases in the future where that is not true. 
+To make it easier to eliminate fields or restructure resource representations, Kubernetes supports multiple API versions, each at a different API path prefix, such as `/api/v1beta3`. These are simply different interfaces to read and/or modify the same underlying resources. In general, all API resources are accessible via all API versions, though there may be some cases in the future where that is not true. 
 
-Distinct API versions present more clear, consistent views of system resources and behavior than intermingled, independently evolved resources. They also provide a more straightforward mechanism for controlling access to end-of-lifed and/or experimental APIs.
+We chose to version at the API level rather than at the resource or field level to ensure that the API presents a clear, consistent view of system resources and behavior, and to enable controlling access to end-of-lifed and/or experimental APIs.
 
 The [API and release versioning proposal](design/versioning.md) describes the current thinking on the API version evolution process.
 

docs/user-guide/quick-start.md

@@ -72,7 +72,7 @@ $ kubectl get svc my-nginx -o json | grep \"ip\"
                    "ip": "130.111.122.213"
 ```
 
-In order to access your nginx landing page, you also have to make sure that traffic from external IPs is allowed. Do this by opening a [firewall to allow traffic on port 80](../../docs/services-firewalls.md).
+In order to access your nginx landing page, you also have to make sure that traffic from external IPs is allowed. Do this by opening a [firewall to allow traffic on port 80](services-firewalls.md).
 
 ## Killing the application
 

docs/services-firewalls.md docs/user-guide/services-firewalls.md

@@ -71,5 +71,5 @@ Coming soon.
 
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
-[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/services-firewalls.md?pixel)]()
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/services-firewalls.md?pixel)]()
 <!-- END MUNGE: GENERATED_ANALYTICS -->

pkg/kubectl/cmd/create.go

@@ -127,7 +127,7 @@ func printObjectSpecificMessage(obj runtime.Object, out io.Writer) {
 cluster.  If you want to expose this service to the external internet, you may
 need to set up firewall rules for the service port(s) (%s) to serve traffic.
 
-See http://releases.k8s.io/HEAD/docs/services-firewalls.md for more details.
+See http://releases.k8s.io/HEAD/docs/user-guide/services-firewalls.md for more details.
 `,
 				makePortsString(obj.Spec.Ports, true))
 			out.Write([]byte(msg))