Merge pull request #45 from buildkite/revise-writing-style-and-contri…

…buting-guides-and-readme

Revise contributing and style guides, and README

CONTRIBUTING.md

@@ -11,32 +11,34 @@ Please also note the following style guides, which are relevant to adding conten
 
 The Buildkite docs is a custom-built website. This section gives some guidance on working with the setup.
 
+As a public contributor to the Buildkite Docs, you should work with a fork of [this upstream repository](https://github.com/buildkite/docs) in your own GitHub account, and then create pull requests to this upstream.
+
 ### Add a new docs page and nav entry
 
 To add a new documentation (docs) page and a nav entry for it:
 
 1. Create the file as a new Markdown file (with the extension `.md`) within the appropriate `pages` directory. Ensure the file name is written in all lowercase letters, and separate words using underscores. (These underscores will be automatically converted to hyphens when the Buildkite Docs site is rebuilt.)
 
-1. Add a corresponding entry to this new page in the [`data/nav.yml`](./data/nav.yml) file, which adds a new entry for this page in the page navigation sidebar (nav) of the [Buildkite Docs site](https://buildkite.com/docs). Note the existing page entries in `nav.yml` and use them as a guide to determine the location and hence, placement of the entry to your new Markdown file (in the nav and `nav.yml`). The following elements require considering for a new entry in `nav.yml`:
+1. Add a corresponding entry to this new page in the [`./data/nav.yml`](./data/nav.yml) file, which adds a new entry for this page in the page navigation sidebar (nav) of the [Buildkite Docs site](https://buildkite.com/docs). Note the existing page entries in `nav.yml` and use them as a guide to determine the location and hence, placement of the entry to your new Markdown file (in the nav and `nav.yml`). The following elements require considering for a new entry in `nav.yml`:
 
-| Key           | Description | Data type |
-| ------------- | ----------- | --------- |
-| `name`        | Nav entry name (see note below). | String, required |
-| `path`        | Enter a relative URL path for internal pages. You can also prepend with `https` for external pages, or `mailto:` for email links, although this practice should be avoided or minimized. If the `path` is empty or omitted, then this will be rendered as a toggle that opens a new section of pages. | String, optional |
-| `icon`        | Prepend with an icon. | String, optional |
-| `theme`       | WIP: doesn't work yet. Apply a theme. You can use `green` or `purple`. | String, optional |
-| `children`    | Child nav entry items. | Array of objects, optional |
-| `pill`        | Append a pill. Currently you can use `beta`, `coming-soon`, `deprecated` or `new` | String, optional |
-| `new_window`  | Make this link open up a new window, although this practice should be avoided or minimized. | Bool, optional |
-| `type` | Special nav link types. With `dropdown` the children nav items will be rendered as hover dropdown menus on laptop/desktop screen devices. `link` is a shortcut link that takes the user from one section to another (for example, you may link to SSO under the Integrations section from Pipeline's sidebar). It also renders an 'external link' icon as an affordance. Lastly, `divider` makes a divider line in the nav to help with visual delineation. | String, `dropdown|link|divider`, optional |
+    | Key           | Description | Data type |
+    | ------------- | ----------- | --------- |
+    | `name`        | Nav entry name (see note below). | String, required |
+    | `path`        | Enter a relative URL path for internal pages. You can also prepend with `https` for external pages, or `mailto:` for email links, although this practice should be avoided or minimized. If the `path` is empty or omitted, then this will be rendered as a toggle that opens a new section of pages. | String, optional |
+    | `icon`        | Prepend with an icon. | String, optional |
+    | `theme`       | WIP: doesn't work yet. Apply a theme. You can use `green` or `purple`. | String, optional |
+    | `children`    | Child nav entry items. | Array of objects, optional |
+    | `pill`        | Append a pill. Currently you can use `beta`, `coming-soon`, `deprecated` or `new` | String, optional |
+    | `new_window`  | Make this link open up a new window, although this practice should be avoided or minimized. | Bool, optional |
+    | `type` | Special nav link types. With `dropdown` the children nav items will be rendered as hover dropdown menus on laptop/desktop screen devices. `link` is a shortcut link that takes the user from one section to another (for example, you may link to SSO under the Integrations section from Pipeline's sidebar). It also renders an 'external link' icon as an affordance. Lastly, `divider` makes a divider line in the nav to help with visual delineation. | String, `dropdown|link|divider`, optional |
 
 > [!NOTE]
 > Whenever you save changes to the `nav.yml` file, you'll need to stop and restart your local development environment in order to see these changes reflected in the nav.
-> 
+>
 > The Buildkite Docs web site is kept running with Ruby, which interprets underscores in filenames as hyphens. Therefore, if a page is called `octopussy_cat.md`, then for its entry in the `nav.yml` file, you need to reference its `path` key value as `octopussy-cat`.
-> 
+>
 > If you're creating a new section for the nav, then as described for the `path` key above, add the `name` key for this entry, omit its `path` key, and add a `children` key to create this new section. Then, nest/indent all new page entries within this section entry.
-> 
+>
 > Since a new section entry in the nav is purely a toggle that cannot hold page content itself, then to introduce a page for this new section, create a top-level "Overview" page for this section instead.
 
 ### Linting
@@ -64,9 +66,9 @@ The rules enabled for this Markdown linting are defined in the [`.markdownlint.y
 
 The Buildkite Docs build pipeline uses [Vale](https://vale.sh/) to check for spelling errors, and builds will fail if a spelling error is encountered.
 
-If you need to add an exception to this (for example, you are referencing a new technology or tool that isn't in Vale's vocabulary), add this term verbatim to the [`/vale/styles/vocab.txt`](./vale/styles/vocab.txt) file, ensuring that the term is added in the correct alphabetical order within the file. Case is important but should be ignored with regard to alphabetical ordering within the file. This makes it easier to identify if an exception has already been added.
+If you need to add an exception to this (for example, you are referencing a new technology or tool that isn't in Vale's vocabulary), add this term verbatim to the [`./vale/styles/vocab.txt`](./vale/styles/vocab.txt) file, ensuring that the term is added in the correct alphabetical order within the file. Case is important but should be ignored with regard to alphabetical ordering within the file. This makes it easier to identify if an exception has already been added.
 
-If you encounter a spelling error within a heading, add this entry into the [`/vale/styles/Buildkite/h1-h6_sentence_case.yml`](./vale/styles/Buildkite/h1-h6_sentence_case.yml) file.
+If you encounter a spelling error within a heading, add this entry into the [`./vale/styles/Buildkite/h1-h6_sentence_case.yml`](./vale/styles/Buildkite/h1-h6_sentence_case.yml) file.
 
 #### Escape vale linting
 
@@ -114,13 +116,14 @@ To save yourself a few unnecessary rounds of edits in the future, remember that
 
 #### Beta flags
 
-To mark a content page in the site as being in beta, add its relative path _after_ `docs` to the `app/models/beta_pages.rb` file.
+To mark a content page in the site as being in beta, add its relative path _after_ `docs` to the [`./app/models/beta_pages.rb`](./app/models/beta_pages.rb) file.
 
 For example:
 ```
 [
-  'test-analytics',
-  'test-analytics/integrations'
+  'pipelines/some-new-beta-feature',
+  'test-analytics/some-new-beta-feature',
+  'packages/some-new-beta-feature'
 ]
 ```
 
@@ -130,7 +133,7 @@ Adding the class `has-pill-beta` to any element will append the beta pill. This
 
 #### Table of contents
 
-Table of contents are automatically generated based on `##`-level headings.
+An in-page table of contents (with the **On this page** title) is automatically generated based on `##`-level headings.
 
 You can omit a table of contents by adding some additional metadata to a Markdown template using the following YAML front matter:
 
@@ -243,10 +246,10 @@ This information was aggregated by going over the existing screenshots in the do
 > Before you proceed, make sure that both the width and the height of the image are an even number of pixels!
 
 Steps for adding add an image to a documentation page:
-1. Name the image file (lowercase, separate words using hyphens; add a number to the filename, for example, 'installation-1' if you are adding several images to the same page)
-2. Put the file into the corresponding `images` folder (a folder with the same name as the page you are adding this image to; create such folder if it doesn't exist yet)
-3. Compose relevant alt text for the image file using sentence case
-4. Add your image file to the documentation page using the following code example `<%= image "your-image.png", width: 1110, height: 1110, alt: "Screenshot of Important Feature" %>`.
+1. Name the image file (lowercase, separate words using hyphens; add a number to the filename, for example, 'installation-1' if you are adding several images to the same page).
+1. Save the file into its corresponding `images` folder (that is, a sub-folder within `images` whose path and name respectively matches that of the Markdown page's path within `pages` and the name this image file is referenced by on this page). Create this sub-folder hierarchy if it doesn't yet exist within `images`.
+1. Compose relevant alt text for the image file using sentence case.
+1. Add your image file to the documentation page using the following code example `<%= image "your-image.png", width: 1110, height: 1110, alt: "Screenshot of Important Feature" %>`.
 For large images/screenshots taken on a retina screen, use `<%= image "your-image.png", width: 1110/2, height: 1110/2, alt: "Screenshot of Important Feature" %>`.
 
 ## Talking about YAML

README.md

@@ -26,7 +26,7 @@ On some platforms (for example, Linux-based ones), you may need to prefix `docke
 
 #### Get the Buildkite Docs source
 
-Clone the Buildkite Docs source locally. To do so, run these commands:
+As a public contributor to the Buildkite Docs, clone its source repository locally. To do so, run these commands:
 
 ```bash
 git clone [email protected]:buildkite/docs.git

styleguides/writing-style.md

@@ -47,6 +47,10 @@ How many people are being referred to in each of these sentences?
 
 Therefore, use serial commas to distinguish individual items in a list from those which are not.
 
+### Plain English
+
+Aim to adopt and implement [_plain English language_](https://clickhelp.com/clickhelp-technical-writing-blog/basics-of-plain-language-in-technical-documentation/) in your writing. Avoid complex jargon that readers find off-putting and distracting, and instead, use more conventional terms that most readers will understand upon reading your writing for the first time. This doesn't mean you cannot use technical terms—just as long as they are terms that most of your target audience will understand.
+
 ### Active/passive voice
 
 Whenever possible, use active voice, which is generally clearer and simpler.
@@ -145,6 +149,10 @@ This list summarizes word usage (or words and punctuation to avoid) in line with
 
 ### Specific word/term usage
 
+#### Use "and" and not "&"
+
+Avoid using ampersands ("&") for the word "and". Doing so sets a poor stylistic precedent. In the Buildkite Docs, "and" is spelled verbatim as "and", and inconsistencies in the way "and" is referred to in the docs impairs its overall readability.
+
 #### And/or
 
 Avoid this construct as it can be confusing to the reader. Often, "and" implies "or", and therefore you don't need to write both words as "and/or". For example, "You can view and edit your pipeline steps" also implies "or" for the "and".