Improves release notes for readability

Improves 1.1.1 release notes.
* Fixes docker#1565
* Fixes docker#1636

release_notes.md

@@ -12,68 +12,77 @@ weight=110
 
 # UCP Release Notes
 
-**Upgrading**
+Here you can learn about new features, bug fixes, breaking changes and
+known issues for each UCP version.
 
-[Learn how to upgrade to the latest version](installation/upgrade.md)
+You can then use [the upgrade instructions](installation/upgrade.md), to
+upgrade your installation to the latest release.
 
 ## Version 1.1.1
 
 **Features**
 
 * Core
-  * Upgraded Swarm to 1.2.2
-  * added `passwd` command to docker/ucp-auth image which allows admins to 
-  reset their passwords. Note for security purposes it is NOT recommended to 
-  give users access to host machines running UCP controllers.
+  * Upgraded Docker Swarm to version 1.2.2.
+  * An administrator can now reset their password. Use the `docker/ucp-auth passwd`
+  command for this.
 
 * docker/ucp image
-  * Added `--kv-timeout` flag to `install` command which configures election 
-  timeout latency of UCP key-value store (e.g. for cross-availability zones or 
-  data centers). More info: https://coreos.com/etcd/docs/latest/tuning.html
-  * Added `--insecure-fingerprint` flag to `join` command which bypasses TLS
-  verification when adding new nodes. Note for security purposes this is NOT 
-  recommended for normal UCP deployments.
+  * It's now possible to configure the heartbeat interval and election timeout
+  of the UCP key-value store with the `docker/ucp install --kv-timeout` option.
+  This is useful when running UCP across multiple data centers.
+  [Learn more](https://coreos.com/etcd/docs/latest/tuning.html)
+  * It's now possible skip TLS verification when joining new nodes to the
+  cluster, using the `docker/ucp join --insecure-fingerprint` option. To ensure
+  your cluster is secure, don't use this option for normal UCP deployments.
 
 * UI
-  * Can now enter private registry credentials when using "Pull image" in UI.
-  * Added disable account checkbox in "Edit User" screen to facilitate easier 
-  switching from managed auth to LDAP auth and vice-versa.
-  * Added checkbox for de-anonymizing usage reports.
-  * Now displays an error when "Pull image" in UI fails.
-  * New UI options to show/hide columns and filter system/stopped containers.
+  * When pulling images on the UCP UI, you can now provide the credentials for
+  a private registry.
+  * It's now possible to disable a user account, to make it easier to switch
+  from managed authentication to LDAP and vice-versa.
+  * Added a setting to submit usage reports without anonymizing data.
+  * When failing to pull an image on the UCP UI, a feedback message is
+  displayed.
+  * The Containers page now allows to show and hide columns.
+  * The Containers page now allows filtering running, stopped, and system
+  containers.
 
 **Bug Fixes**
 
-* Fixes a known issue from UCP 1.1.0 where the cluster fails to join additional 
-nodes after upgrading from an older version of UCP.
-* Upgrading from UCP 1.0.x now correctly preserves users/teams/orgs.
-* Upgrading from UCP 1.0.x now puts correct version labels on containers
-* Errors reported by UCP k-v store are now more informative.
-* Restore command now ensures backup is uncorrupted, UCP cluster is healthy and 
-is running the same or later UCP version in order to proceed successfully.
+* Fixed an issue that prevented new nodes to be joined to a cluster, after
+upgrading UCP from an older version to 1.1.0.
+* When upgrading, configurations for user, teams, and organizations are now
+preserved.
+* When upgrading, version labels are correctly added to the containers.
+* Improved error logs generated by the UP key-value store.
+* The restore command now ensures the backup is not corrupt, that the UCP
+cluster is healthy and is running the same or later version of UCP before
+restoring.
 * LDAP domain names are now case-insensitive for easier syncing.
-* Fixes error by which user could get unintended "access denied" message 
-when deploying a container in UI due to cached permission labels
+* Fixed an issue that caused LDAP syncs to run every minute, after upgrading
+UCP from an older version to 1.1.0.
+* Fixed error by which user could get an "access denied" message when deploying
+a container from the UI due to cached permission labels.
 
 **Misc**
 
-* It is no longer necessary to add `--swarm-experimental` flag at installation
-in order to enable container rescheduling as this Swarm feature is now GA.
-* UCP now recommends a minimum of 2 GB of RAM per host (up from 1.5 GB).
-* During installation, UCP now warns you to only restart the Docker Engine 
-after joining all controller nodes to the cluster (known issue in v1.1.0)
+* Since container rescheduling has reached GA on Docker Swarm, you can use it
+without having to install UCP with the `--swarm-experimental-flag`.
+* UCP now requires a minimum of 2 GB of RAM per node, instead of 1.5 GB.
+* During installation, UCP now warns you to only restart the Docker Engine
+after joining all controller nodes to the cluster.
 
 **Known Issues**
 
-* When running on Docker Engines prior to 1.11.1-cs2, containers with 
-`restart=always` on overlay networks may not resume properly when the daemon
-is restarted on a UCP controller node. It is highly recommended to upgrade your
-Engines, particularly when using overlay networks or running UCP and DTR in HA 
-configuration on the same nodes.
-* When attempting to restore a v1.1.0 backup on a new cluster installed with 
-the `fresh-install` flag, the restore operation process may fail due to 
-engine-discovery configuration issues. It is recommended to take a new set of 
-backups after upgrading to v1.1.1.
+* When using UCP with a Docker Engine prior to 1.11.1-cs2, containers with a
+restart policy set to `restart=always` and using an overlay network, may not
+resume properly when the Docker daemon is restarted. Upgrade the Docker Engine
+on your nodes to version 1.11.1-cs2 to fix this. This is specially important
+when running UCP and DTR on the same nodes, and with high-availability.
+* When attempting to restore a v1.1.0 backup on a new cluster installed with
+the `fresh-install` flag, the restore operation may fail due to engine-discovery
+configuration issues. You should create new backups after upgrading to v1.1.1.
 
 ## Version 1.1.0
 
@@ -129,8 +138,9 @@ upstream version or UCP version
 variables passed to the command are displayed
 * Renamed 'external-ucp-ca' flag to 'external-server-cert' for clarity.
 The former name is deprecated but still available
-* Since UCP now makes use of overlay networking, make sure ports 4789 and 7946
-are open when deploying your cluster.
+* UCP is automatically configured to use overlay networking. Make sure ports
+4789 and 7946 are open for this to work
+* The new authentication service requires ports 12383-12386 to be open
 
 **Known Issues**