fix some cross refs and formatting

Author: rosieyohannan

README-server-docs.md

@@ -63,4 +63,4 @@ In order to make tables display correctly in the web version of Server docs, ass
 ### Inter-document cross refs
 Cross references should be made in the form: `<<overview#services-machine,Services Machine>>` where `overview` is the name of the file the destination is in, `services-machine` is the anchor heading, and `Services Machine` is what to display in the prose.
 
-This is a little trickier when cross referencing between the install and ops guides as the xref needs to work for the PDF, where they are two separate docs as well as the Jekyll site where you will be dealing with two regular pages as with any xref. So in this instance reference the URL of the Jekyll version, so instead of using the `<<>>` described above, use a normal link URL[text to display].
+This is a little trickier when cross referencing between the install and ops guides as the xref needs to work for the PDF, across two separate docs, as well as the Jekyll site where you will be dealing with two regular pages as with any xref. In this instance, reference the URL of the Jekyll version, so instead of using the `<<>>` described above, use a normal link `URL[text to display]`.

README.md

@@ -8,6 +8,8 @@ For larger edits or new articles, you'll want to set up a local environment for
 
 If you have a question or need help debugging, please head to [CircleCI Discuss](https://discuss.circleci.com/) where our support team will help you out.
 
+Docs for CircleCI Server Administration are built in a slightly different way so there is a [separate README](README-server-docs.md) for this section.
+
 ## License Information
 Documentation (guides, references, and associated images) is licensed as Creative Commons Attribution-NonCommercial-ShareAlike CC BY-NC-SA. The full license can be found [here](http://creativecommons.org/licenses/by-nc-sa/4.0/legalcode), and the human-readable summary [here](http://creativecommons.org/licenses/by-nc-sa/4.0/).
 

release/tmp/CircleCI-Server-AWS-Installation-Guide.pdf renamed to jekyll/_cci2/CircleCI-Server-AWS-Installation-Guide.pdf

@@ -43,7 +43,7 @@ Have available the following information and policies before starting the instal
 * AWS instances must have outbound access to pull Docker containers and to verify your license. If you don't want to give open outbound access, see our https://help.replicated.com/community/t/customer-firewalls/55[list of ports] that will need access.
 * In order to provision required AWS entities with Terraform you will require an IAM User with the following permissions (See the https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html[AWS guidance] on creating IAM users):
 +
-[source,json,linenums]
+[source,json]
 ----
 {
     "Version": "2012-10-17",

release/tmp/CircleCI-Server-Operations-Guide.pdf renamed to jekyll/_cci2/CircleCI-Server-Operations-Guide.pdf

@@ -185,26 +185,22 @@ image::privacy.png[]
 .Storage Options
 image::storage.png[]
 
-. Enhanced AWS Integration TBD
+. Complete enhanced AWS Integration options.
 // explain enhanced AWS integration 1.0 or just say ignore
 
 . Complete the Email section if you wish to configure your own email server for sending build update emails. Leave this section is you wish to use our default email server.
 +
 NOTE: Due to an issue with our third party tooling, Replicated, the Test SMTP Authentication button is not currently working
 
-// explain email server options, test button doesnt work etc
-
 . Configure VM service if you plan to use https://circleci.com/docs/2.0/building-docker-images/[Remote Docker] or `machine` executor features. We recommend using an IAM instance profile for authentication, as described in the <<aws-prereq#planning,planning>> section of this document. With this section completed, instances will automatically be provisioned to execute jobs in Remote Docker or use the `machine` executor.
 +
 .Configure VM Service
 image::vmprovider.png[]
-
++
 You can preallocate instances to always be up and running, reducing the time taken for Remote Docker and `machine` executor jobs to start. If preallocation is set, a cron job will cycle through your preallocated instances once per day to prevent them getting into a bad/dead state.
-
++
 CAUTION: If Docker Layer Caching (DLC) is to be used VM preallocation must be set to `0` – on-demand – for both Remote Docker and `machine` executor.
 
-//<!--Advanced settings to cover here too - make a section in ops guide for this and list of OK instance types for VM provider-->
-
 . If you wish to use AWS Cloudwatch or Datadog for collating metrics for your installation, set this up here. For more infomration see our https://circleci.com/docs/2.0/monitoring/[Monitoring guidance]:
 +
 .Metrics

jekyll/_cci2/aws-prereq.adoc

@@ -59,7 +59,7 @@ While filesystem-level data integrity issues are rare and preventable, there wil
 If you want to clean up any abnormal build records in your database after a recovery, you can delete them by running the following commands on the Services machine replacing the example build URL with an actual URL from your CircleCI application:
 
 ```shell
-$ circleci dev-console
+circleci dev-console
 # Wait for console to load
 user=> (admin/delete-build "https://my-circleci-hostname.com/gh/my-org/my-project/1234")
 ```

jekyll/_cci2/aws.adoc

@@ -5,9 +5,13 @@
 :toc: macro
 :toc-title:
 
-NOTE: CircleCI Server v2.17 uses the CircleCI 2.0 architecture.
+NOTE: CircleCI Server v2.17.x uses the CircleCI 2.0 architecture.
 
-The following sections provide step-by-step instructions for installing CircleCI Server v2.17 on Amazon Web Services (AWS) with Terraform. Refer to the https://circleci.com/server/changelog[changelog] for what's new and fixed in this release.
+The following sections provide planning information, system requirements and step-by-step instructions for installing CircleCI Server on Amazon Web Services (AWS) with Terraform.
+
+Refer to the https://circleci.com/server/changelog[changelog] for what's new and fixed in this release.
+
+If you are looking to update an existing installation, see our guide to <<updating-server#updating-a-server-installation,Updating a Server Installation>>.
 
 toc::[]
 

jekyll/_cci2/backup.adoc

@@ -17,7 +17,7 @@ image::arch_server.png[Services Architecture]
 <<<
 == Build Environments
 
-CircleCI 2.0 uses Nomad as the primary job scheduler. Refer to our <<nomad#basic-terminology-and-architecture,Nomad Introduction>> to learn more about the job scheduler and how to perform basic client and cluster operations.
+CircleCI 2.0 uses Nomad as the primary job scheduler. Refer to our <<nomad#introduction-to-nomad-cluster-operation,Introduction to Nomad Cluster Operation>> to learn more about the job scheduler and how to perform basic client and cluster operations.
 
 By default, CircleCI 2.0 Nomad clients automatically provision containers according to the image configured for each job in your `.circleci/config.yml` file.
 
@@ -42,7 +42,7 @@ image::arch_components.png[CircleCI Core Components]
 
 === Services Machine
 
-The Services machine must must not be restarted and may be backed up using VM snapshotting. If you must restart the Services machine, do so only as a last resort, because a restart will result in downtime. Refer to the <<backup#disaster-recovery,Disaster Recovery>> chapter for instructions.
+The Services machine must must not be restarted and may be backed up using VM snapshotting. If you must restart the Services machine, do so only as a last resort, because a restart will result in downtime. Refer to the <<backup#backup-and-recovery,Backup and Recovery>> chapter for instructions.
 //I feel like this is going in to telling you stuff you shouldn't do too quickly - feels negative
 
 DNS resolution may point to the IP address of the Services machine. It is also possible to point to a load balancer, for example an ELB in AWS. The following table describes the ports used for traffic on the Service machine:

jekyll/_cci2/install-overview.adoc

@@ -27,16 +27,16 @@ To take a snapshot of your installation:
 NOTE: It is also possible to automate this process with the AWS API. Subsequent AMIs/snapshots are only as large as the difference (changed blocks) since the last snapshot, such that storage costs are not necessarily larger for more frequent snapshots, see Amazon's EBS snapshot billing document for details.
 Once you have the snapshot you are free to make changes on the Services machine.
 
-If you do need to rollback at any point, see our <<backup#restoring-from-backup,Restore from Backup>> guide.
+If you do need to rollback at any point, see our https://circleci.com/docs/2.0/backup/#restoring-from-backup[guide to restoring from a backup].
 
 == Updating Replicated
 
-=== Perquisites
+=== Prerequisites
 
 * Your installation is Ubuntu 14.04 or 16.04 based.
 * You are running replicated version 2.10.3<= on your services machine. Check by running the following:
 +
-```
+```shell
 replicated --version
 ```
 * Your installation is **not** airgapped and you can access the internet from it
@@ -48,19 +48,19 @@ CAUTION: Remember to take a snapshot (described above) before starting the Repli
 
 . Stop the CircleCI application:
 +
-```
-    replicatedctl app stop
+```shell
+replicatedctl app stop
 ```
 +
 Application shutdown takes a few minutes. Please check the administration dashboard and wait for the status to become “Stopped” before continuing. You can also run the following command to view the app status:
 +
-```
-    replicatedctl app status inspect
+```shell
+replicatedctl app status inspect
 ```
 +
 Example Output:
 +
-```
+```shell
 [
     {
         "AppID": "edd9471be0bc4ea04dfca94718ddf621",
@@ -77,46 +77,46 @@ Example Output:
 
 . For the replicated update to succeed, it is necessary to update docker to the recommended version, 17.12.1:
 +
-```
-    sudo apt-get install docker-ce=17.12.1~ce-0~ubuntu
+```shell
+sudo apt-get install docker-ce=17.12.1~ce-0~ubuntu
 ```
 
 . Pin the Docker version using the following command:
 +
-```
-    sudo apt-mark hold docker-ce
+```shell
+sudo apt-mark hold docker-ce
 ```
 
 === Perform Update
 
 . Perform the Replicated update by executing the update script as follows:
 +
-```
-    curl -sSL "https://get.replicated.com/docker?replicated_tag=2.34.1" | sudo bash
+```shell
+curl -sSL "https://get.replicated.com/docker?replicated_tag=2.34.1" | sudo bash
 ```
 +
 Double-check your replicated and docker versions:
 +
-```
-    replicatedctl version    # 2.34.1
-    docker -v                # 17.12.1
+```shell
+replicatedctl version    # 2.34.1
+docker -v                # 17.12.1
 ```
 
 . Restart the app with
 +
-```
-    replicatedctl app start
+```shell
+replicatedctl app start
 ```
 +
 The application will take a few minutes to spin up. You can check the progress in the administration dashboard or by executing;
 +
-```
-    replicatedctl app status inspect
+```shell
+replicatedctl app status inspect
 ```
 +
 Example output:
 +
-```
+```shell
 [
     {
         "AppID": "edd9471be0bc4ea04dfca94718ddf621",

jekyll/_cci2/overview.adoc

@@ -7,7 +7,7 @@ categories: [getting-started]
 order: 1
 ---
 
-This document provides a summary of features and product notes for the release of CircleCI Server v2.17.
+This document provides a summary of features and product notes for the release of CircleCI Server v2.17. For a full list of changes, including patch releases, refer to the [changelog](https://circleci.com/server/changelog).
 
 ## What's New in Release 2.17
 
@@ -18,11 +18,6 @@ This document provides a summary of features and product notes for the release o
 * Improved the cache in front of GraphQL API resulting in overall improved performance.
 * Added backpressure to avoid overwhelming nomad with requests, this will result in increased performance from existing nomad clusters.
 
-
-- PDF installation and operations documentation:
-   - [*CircleCI v2.17 Installation Guide*](https://circleci.com/docs/2.0/circleci-install-doc-v2-17.pdf)
-   - [*CircleCI v2.17 Operations Guide*](https://circleci.com/docs/2.0/circleci-ops-guide-v2-17.pdf)
-
 ## Fixed in Release 2.17
 
 * Fixed some bugs related to GitHub API response handling and webhook handling.

jekyll/_cci2/updating-server.adoc

@@ -268,11 +268,9 @@ en:
 - name: Server Administration
   icon: docs/admin.svg
   children:
-    - name: Server v2.17.3 Install and Upgrade
+    - name: Server v2.17.x Install
       link: 2.0/install-overview/
       children:
-        - name: Trial Single-box Install
-          link: 2.0/single-box/
         - name: Overview
           link: 2.0/install-overview/
         - name: System Requirements
@@ -287,7 +285,9 @@ en:
           link: 2.0/updating-server/
         - name: Upgrades from 1.0 to 2.0
           link: 2.0/upgrading/
-    - name: Server v2.17.3 Operations
+        - name: Trial Single-box Install
+          link: 2.0/single-box/
+    - name: Server v2.17.x Operations
       link: 2.0/overview/
       children:
         - name: Overview
@@ -332,15 +332,15 @@ en:
           link: 2.0/architecture/
         - name: Acknowledgments
           link: 2.0/open-source/
-    - name: CircleCI Server v2.17 PDFs
+    - name: CircleCI Server v2.17.3 PDFs
       link: 2.0/v.2.17-overview/
       children:
         - name: What's New in v2.17
           link: 2.0/v.2.17-overview/
-        - name: v2.17 Installation Guide
-          link: 2.0/circleci-install-doc-v2-17.pdf
-        - name: v2.17 Operations Guide
-          link: 2.0/circleci-ops-guide-v2-17.pdf
+        - name: v2.17.3 Installation Guide
+          link: 2.0/CircleCI-Server-Installation-Guide.pdf
+        - name: v2.17.3 Operations Guide
+          link: 2.0/CircleCI-Server-Operations-Guide.pdf
     - name: CircleCI Server v2.16 PDFs
       link: 2.0/v.2.16-overview/
       children: