Merge pull request #97 from alphagov/firebreak

Update information architecture
alphagov · Oct 16, 2019 · a7b2a65 · a7b2a65
2 parents f24aea2 + b5debca
commit a7b2a65
Show file tree

Hide file tree

Showing 42 changed files with 512 additions and 382 deletions.
diff --git a/config/tech-docs.yml b/config/tech-docs.yml
@@ -16,7 +16,7 @@ header_links:
 # Table of contents depth – how many levels to include in the table of contents.
 # If your ToC is too long, reduce this number and we'll only show higher-level
 # headings.
-max_toc_heading_level: 2
+max_toc_heading_level: 1
 
 # Tracking ID from Google Analytics (e.g. UA-XXXX-Y)
 ga_tracking_id: UA-86101042-3

diff --git a/source/add_an_openapi_specification.html.md.erb b/source/add_an_openapi_specification.html.md.erb
diff --git a/...tionality/add_an_openapi_specification.md → ...n_openapi_specification/index.html.md.erb b/...tionality/add_an_openapi_specification.md → ...n_openapi_specification/index.html.md.erb
@@ -1,6 +1,15 @@
+---
+title: "Add an OpenAPI specification"
+weight: 33
+last_reviewed_on: 2019-10-03
+review_in: 1 day
+---
+
 # Add an OpenAPI specification to your documentation
 
-This tool can extract endpoint information from an [Open API v3 specification](https://swagger.io/docs/specification/about/) in a YAML file.
+OpenAPI is an API description format for RESTful APIs. The GDS Open Standards board [recommends that government organisations use OpenAPI version 3 to describe RESTful APIs](https://www.gov.uk/government/publications/recommended-open-standards-for-government/describing-restful-apis-with-openapi-3).
+
+The template can extract endpoint information from an [Open API v3 specification](https://swagger.io/docs/specification/about/) in a YAML file.
 
 ## Amend the tech-docs.yml file
 
@@ -16,7 +25,7 @@ This can be a relative path to a file in your tech docs repo folder, for example
 api_path: ./source/pets.yaml
 ```
 
-This can also be a URL to a file hosted elsewhere, for example: 
+This can also be a URL to a file hosted elsewhere, for example:
 
 ```
 api_path: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml

diff --git a/source/configuration-options.html.md.erb → ...d_project/configuration/index.html.md.erb b/source/configuration-options.html.md.erb → ...d_project/configuration/index.html.md.erb
@@ -1,5 +1,8 @@
 ---
 title: "Configuration options"
+weight: 35
+last_reviewed_on: 2019-10-03
+review_in: 1 day
 ---
 
 # Configuration options

diff --git a/source/content_example/content.md → ...e/amend_project/content/index.html.md.erb b/source/content_example/content.md → ...e/amend_project/content/index.html.md.erb
@@ -1,4 +1,11 @@
-# Content examples
+---
+title: "Change your content"
+weight: 31
+last_reviewed_on: 2019-10-03
+review_in: 1 day
+---
+
+# Change your content
 
 This page provides examples of different content types.
 
@@ -42,7 +49,7 @@ This page provides examples of different content types.
       - nested bullet 1
       - nested bullet 2
       - nested bullet 3
-```      
+```
 
 ## Tables
 
@@ -87,7 +94,7 @@ You should create tables using HTML when there are specific formatting requireme
 The following code is an example of a 2 column 2 row table with no text wrapping.
 
 ```bash
-<div style = "overflow-x:auto;"> 
+<div style = "overflow-x:auto;">
 <table style="width:100%">
 <tr>
 <th nowrap>Header 1</th>
@@ -122,3 +129,15 @@ You can write the link in HTML with a `target="blank"` element to make the link
 ## Images
 
 `!``[]``(LOCATION_OF_IMAGE)`
+
+## Insert a warning
+
+Use the warning text component when you need to warn users about something important, such as legal consequences of an action, or lack of action, that they might take.
+
+This warning text format is consistent with the [GOV.UK Design System warning text](https://design-system.service.gov.uk/components/warning-text/).
+
+Insert the following Ruby code into your content file:
+
+```ruby
+<%= warning_text('INSERT WARNING TEXT HERE') %>
+```
diff --git a/source/amend_project/index.html.md.erb b/source/amend_project/index.html.md.erb
@@ -0,0 +1,14 @@
+---
+title: "Change your documentation project"
+weight: 30
+last_reviewed_on: 2019-10-03
+review_in: 1 day
+---
+
+# Change your documentation project
+
+You can change your documentation project by:
+
+- changing the content
+- updating your documentation to use the latest version of the template
+- adding an OpenAPI3 specification
diff --git a/source/middleman.html.md.erb → ...amend_project/middleman/index.html.md.erb b/source/middleman.html.md.erb → ...amend_project/middleman/index.html.md.erb
@@ -1,6 +1,8 @@
 ---
 title: "Middleman options"
-weight: 87
+weight: 34
+last_reviewed_on: 2019-10-03
+review_in: 1 day
 ---
 
 # Middleman options

diff --git a/source/functionality/update_gem.md → ...mend_project/update_gem/index.html.md.erb b/source/functionality/update_gem.md → ...mend_project/update_gem/index.html.md.erb
@@ -1,4 +1,11 @@
-# Update docs to use latest tech-docs-gem
+---
+title: "Update your gem"
+weight: 32
+last_reviewed_on: 2019-10-03
+review_in: 1 day
+---
+
+# Update your documentation to use the latest version of the template
 
 ## Clone the remote documentation repo
 

diff --git a/source/collapsible_nav.html.md.erb b/source/collapsible_nav.html.md.erb
diff --git a/source/content.html.md.erb b/source/content.html.md.erb
diff --git a/source/create_new_project.html.md.erb b/source/create_new_project.html.md.erb
diff --git a/source/create_project/create_new_project/index.html.md.erb b/source/create_project/create_new_project/index.html.md.erb
@@ -0,0 +1,51 @@
+---
+title: "Create a new documentation project"
+weight: 22
+last_reviewed_on: 2019-10-03
+review_in: 1 day
+---
+
+# Create a new documentation project
+
+1. Open the command line interface.
+
+1. Navigate to your documents folder.
+
+1. Run the following in the command line:
+
+    ```
+    middleman init PROJECT_NAME -T alphagov/tech-docs-template
+    ```
+    where `PROJECT_NAME` is the name of your project.
+
+1. Answer the installation questions.
+
+1. Project creation is complete when you see `Bundle complete!`.
+
+## Configure your new documentation project
+
+### Enable collapsible navigation
+
+Add the following code to your project's `tech-docs.yml` file if necessary:
+
+```
+# Enable collapsible navigation in the sidebar
+collapsible_nav: true
+```
+
+### Enable search
+
+The search function is especially useful for multipage documentation.
+
+Add the following code to your project’s `tech-docs.yml` file if necessary:
+
+```
+# Enable search
+enable_search: true
+```
+
+## View your new documentation project
+
+Navigate to the created documentation repo folder.
+
+The folder will have multiple pre-populated files. You will only need to amend the `/source` folder and the `config/tech-docs.yml` file.
diff --git a/source/create_project/index.html.md.erb b/source/create_project/index.html.md.erb
@@ -0,0 +1,10 @@
+---
+title: "Create a documentation project"
+weight: 20
+last_reviewed_on: 2019-10-03
+review_in: 1 day
+---
+
+# Create a documentation project
+
+You can create a single page or multipage documentation project.
diff --git a/source/architecture/multipage.md → ...reate_project/multipage/index.html.md.erb b/source/architecture/multipage.md → ...reate_project/multipage/index.html.md.erb
@@ -1,4 +1,11 @@
-# Build a multipage site
+---
+title: "Build a multipage site"
+weight: 24
+last_reviewed_on: 2019-10-03
+review_in: 1 day
+---
+
+# Build a multipage documentation site
 
 You can create a technical documentation site that splits its content across multiple pages.
 
@@ -12,7 +19,7 @@ You can split the content into multiple individual pages. An example is the [GOV
 
 ### Amend the tech-docs.yml file
 
-Add this to your project’s `tech-docs.yml` file, or set it to true if it is already there:
+Add the following code to your project’s `tech-docs.yml` file if necessary:
 
 ```
 # Enable multipage navigation in the sidebar
@@ -45,7 +52,7 @@ Additionally, the tech doc repo must have at least one `.html.md.erb` file in th
 
 The .html.md.erb files must not have the same name as the folders that the .html.md.erb files use partials refer to.
 
-For example, you cannot have a support.html.md.erb file that contains the partial `<%= partial 'support/contact_us' %>`.
+For example, you cannot have a support.html.md.erb file that contains the partial `PARTIAL`.
 
 ### Amend the multiple .html.md.erb files
 
@@ -72,16 +79,18 @@ For example, you cannot have a support.html.md.erb file that contains the partia
 
     For example, a single `.html.md.erb` file becomes multiple `.html.md.erb` files:
 
+    ```
     <div style="height:1px;font-size:1px;">&nbsp;</div>
 
     |Single page|Multipage|
     |:---|:---|
-    |---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/index' %>|---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/index' %>|
-    ||---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/index' %>|
-    ||---<br>weight: 20<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/start' %>|
-    ||---<br>weight: 30<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/users' %>|
+    |---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br>PARTIAL|---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br>PARTIAL|
+    ||---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br>PARTIAL|
+    ||---<br>weight: 20<br>title: "Product Technical Documentation"<br>---<br><br>PARTIAL|
+    ||---<br>weight: 30<br>title: "Product Technical Documentation"<br>---<br><br>PARTIAL|
 
     <div style="height:1px;font-size:1px;">&nbsp;</div>
+    ```
 
 ### Add H1 heading if required
 
@@ -98,7 +107,7 @@ You can split the content into multiple individual pages, and can have pages "ne
 
 ### Amend the tech-docs.yml file
 
-Add this to your project’s `tech-docs.yml` file, or set it to true if it is already there:
+Add the following to your project’s `tech-docs.yml` file if necessary:
 
 ```
 # Enable multipage navigation in the sidebar
@@ -131,7 +140,7 @@ Additionally, the tech doc repo must have at least one `.html.md.erb` file in th
 
 ### Amend the multiple .html.md.erb files
 
-1. Add a weight argument and value to the title of each .html.md.erb file. This builds the structure of the multipage documentation.
+1. Add a weight argument and value to the title of each .html.md.erb file to build the structure of the multipage documentation.
 
     For example:
 
@@ -158,10 +167,10 @@ Additionally, the tech doc repo must have at least one `.html.md.erb` file in th
 
     |Single page|Multipage|
     |:---|:---|
-    |---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/index' %>|---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/index' %>|
-    ||---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/index' %>|
-    ||---<br>weight: 20<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/start' %>|
-    ||---<br>weight: 30<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/users' %>|
+    |---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br>PARTIAL|---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br>PARTIAL|
+    ||---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br>PARTIAL|
+    ||---<br>weight: 20<br>title: "Product Technical Documentation"<br>---<br><br>PARTIAL|
+    ||---<br>weight: 30<br>title: "Product Technical Documentation"<br>---<br><br>PARTIAL|
 
     <div style="height:1px;font-size:1px;">&nbsp;</div>
 
@@ -175,9 +184,9 @@ If there is an H1 heading in both, you will see two H1s when the documentation s
 
 Refer to the GOV.UK PaaS technical documentation repo [nested content folder](https://github.com/alphagov/paas-tech-docs/tree/master/source/deploying_services) as an example.
 
-1. Create a folder within the __source__ folder. This is where the `.html.md.erb` files for your nested content must live.
+1. Create a folder within the __source__ folder. This folder is where the `.html.md.erb` files for your nested content must live.
 
-1. Create an `index.html.md.erb` file within the nested content folder. This will be the "wrapper" for the nested content. It can refer to another content file through partials or have the content in itself.
+1. Create an `index.html.md.erb` file within the nested content folder. This file will be the "wrapper" for the nested content. The wrapper can refer to another content file through partials or have the content in itself.
 
     Note that each `.html.md.erb` must have a weight value that preserves the overall hierarchy both within the nested content and compared to the other non-nested content.
 

diff --git a/source/getting_started/install_macs.md → ...ate_project/setup_local/index.html.md.erb b/source/getting_started/install_macs.md → ...ate_project/setup_local/index.html.md.erb
@@ -1,42 +1,43 @@
-# Prerequisites for Macs
+---
+title: "Set up your local machine"
+weight: 21
+last_reviewed_on: 2019-10-03
+review_in: 1 day
+---
 
-You must have the following set up on your mac laptop:
+# Set up your local machine
 
-- administrator rights on your laptop
+The following instructions assume that you have a mac laptop.
+
+You must set up the following on your local machine:
+
+- administrator rights
 - [Xcode](https://developer.apple.com/xcode/) command line interface tools
 - [Ruby](https://www.ruby-lang.org/en/)
 - [Middleman](https://middlemanapp.com/) static site generator
 
 ## Administrator rights on your laptop
 
-Raise a ticket on the [GDS Web Help Desk](https://gdshelpdesk.digital.cabinet-office.gov.uk/helpdesk/WebObjects/Helpdesk.woa) to request administrator rights on your laptop.
+If you are a Government Digital Service (GDS) employee, raise a ticket on the [GDS Web Help Desk](https://gdshelpdesk.digital.cabinet-office.gov.uk/helpdesk/WebObjects/Helpdesk.woa) to request administrator rights on your laptop.
 
-You must be a Government Digital Service employee to do this.
+If you are not a GDS employee, follow your internal IT processes.
 
 ## Install Xcode command line interface tools
 
-These instructions assume that you are the Managed Software Centre on your Mac.
-
-1. Go to the Managed Software Centre on your Mac.
-1. Select Updates.
-1. Install all required updates.
-1. Search for xcode in the search field in Updates.
-1. Install Xcode x.x.x or update if necessary.
-
-OR
-
 1. Go to [Apple Developer Downloads](https://developer.apple.com/download/more).
 1. Search for "xcode".
 1. Select the appropriate __Command Line Tools (macOS x.x) for Xcode x.x__ and download the file.
 1. Install the file.
 
+If you have a software centre for your department, you should be able to install the Xcode command line tools through this.
+
 ## Install Ruby
 
 [Ruby](https://www.ruby-lang.org/en/) is installed globally. This means that you can run the install command from any location on your local machine rather than from within a specific folder.
 
 You can install Ruby in multiple ways, for example using [Ruby Version Manager](https://rvm.io/) (RVM) or [rbenv](https://github.com/rbenv/rbenv). These instructions assume you are using RVM.
 
-1. Run the following in the command line interface to install the ruby version manager:
+1. Run the following in the command line to install the ruby version manager:
 
     ```
     `\curl -sSL https://get.rvm.io | bash -s stable --ruby`
@@ -48,7 +49,7 @@ You can install Ruby in multiple ways, for example using [Ruby Version Manager](
 
 [Middleman](https://middlemanapp.com/) is installed globally. This means that you can run the install command from any location on your local machine rather than from within a specific folder.
 
-Run the following in the command line interface to install Middleman:
+Run the following in the command line to install Middleman:
 
 ```
 gem install middleman