Merge pull request #73 from kobiton/patch-contributing

Quick content fixes for CONTRIBUTING and README

CONTRIBUTE.adoc → CONTRIBUTING.adoc

@@ -2,21 +2,21 @@
 
 Thanks for contributing to Kobiton Docs! This guide covers how content for link:https://docs.kobiton.com/[docs.kobiton.com] is created, organized, and published. Everyone here is expected to adhere to the xref:CODE_OF_CONDUCT.adoc[Code of Conduct], so be sure to review before continuing.
 
-If you're new to docs-as-code, see _first_time_contributors, otherwise choose a topic from the xref:_table_of_contents[table of contents].
+If you're new to docs-as-code, see xref:_first_time_contributors[], otherwise choose a topic below:
 
 [#_table_of_contents]
 == Table of contents
 
 * xref:_first_time_contributors[]
-* xref:_build_the_docs[]
+* xref:_build_the_docs_locally[]
 * xref:_file_nameing[]
 * xref:_directory_structure[]
 * xref:_antora_playbooks[]
 * xref:_navigation_bar[]
 * xref:_partials[]
 * xref:_page_types_and_templates[]
 * xref:_style_and_voice[]
-* xref:_publishing[]
+* xref:_docker_commands[]
 
 [#_first_time_contributors]
 == First time contributors
@@ -25,15 +25,15 @@ Our docs are managed as docs-as-code, meaning each document is a plain text file
 
 === Version control
 
-Version control allows our team to work on documents simultaneously without accidently overwriting each others work.
+Version control allows our team to work on documents simultaneously without accidentally overwriting each other's work.
 
 * link:https://docs.github.com/en/get-started/using-git/about-git[Learn about Git and GitHub]
 * link:https://docs.github.com/get-started/quickstart/hello-world[Get started with GitHub]
 * link:https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request[Your first pull request]
 
 === Files
 
-Plain text files only contain content--not design elements--allowing our team to seperate content-related tasks from design-related tasks.
+Plain text files only contain content--not design elements--allowing our team to separate content-related tasks from design-related tasks.
 
 * link:https://docs.asciidoctor.org/asciidoc/latest/[Learn about the AsciiDoc markup language]
 * link:https://asciidoctor.org/docs/asciidoc-writers-guide/[Get started with the AsciiDoc markup language]
@@ -42,7 +42,7 @@ Plain text files only contain content--not design elements--allowing our team to
 
 === Static site generator
 
-The static site generator converts all plain text files to HTML and bundles them with our CSS when you xref:_build_the_docs[build the docs].
+The static site generator converts all plain text files to HTML and bundles them with our CSS when you xref:_build_the_docs_locally[build the docs].
 
 * link:https://docs.antora.org/antora/latest/how-antora-works/[Learn about Antora]
 * link:https://docs.antora.org/antora/latest/install-and-run-quickstart/[Get started with Antora]
@@ -54,22 +54,22 @@ When a commit is merged to our `main` branch in GitHub, the site is automaticall
 
 * link:https://docs.docker.com/get-started/overview/[Learn about Docker]
 * link:https://docs.docker.com/get-started/[Get started with Docker]
-* xref:_publishing[How to use Docker with Kobiton Docs]
+* xref:_docker_commands[How to use Docker with Kobiton Docs]
 * link:https://www.jenkins.io/[Learn about Jenkins]
 * link:https://www.jenkins.io/doc/pipeline/tour/getting-started/[Get started with Jenkins]
 
-[#_build_the_docs]
-== Build the docs
+[#_build_the_docs_locally]
+== Build the docs locally
 
-To build the docs locally, you'll need link:https://nodejs.org/[Node.js] and link:https://yarnpkg.com/[Yarn]. Run the following commands to check if they're installed:
+We use link:https://docs.antora.org/antora/latest/how-antora-works/[Antora] as our static site generator. Before you can use Antora to build the docs locally, you'll need link:https://nodejs.org/[Node.js] and link:https://yarnpkg.com/[Yarn]. Run the following commands to see if they're installed:
 
 [source,shell]
 ----
 node --version
 yarn --version
 ----
 
-If Node.js and Yarn are installed, you can install our project dependencies and build the docs locally by running the following commands:
+If Node.js and Yarn are installed, install our project dependencies and build the docs locally by running:
 
 [source,shell]
 ----
@@ -80,7 +80,7 @@ yarn build
 [#_directory_structure]
 == Directory structure
 
-The Kobiton Docs repository uses one `modules` directory containing an `antora.yml` file, a `ROOT` directory, and directories for each Kobiton feature. Each directory within `modules` contains its own `images`, `pages`, and `partials` directories, along with a `nav.adoc` file.
+Kobiton Docs uses one `modules` directory containing an `antora.yml` file, a `ROOT` directory, and a directory for each Kobiton feature. Each directory in `modules` contains an `images`, `pages`, and `partials` directories, along with a `nav.adoc` file.
 
 For example:
 
@@ -119,12 +119,12 @@ Typically, Antora configurations use one `antora-playbook.yml` file, however in
 * `antora-playbook-docs.yml`
 * `antora-playbook-widget.yml`
 
-The first playbook is used to configure link:https://docs.kobiton.com/[docs.kobiton.com], while the second is used to configure the help widget on link:https://portal.kobiton.com/[portal.kobiton.com]. Additionally, each playbook uses their own UI bundle:
+The first playbook is used to configure link:https://docs.kobiton.com/[docs.kobiton.com], while the second is used to configure the help widget on link:https://portal.kobiton.com/[portal.kobiton.com]. Additionally, each playbook uses their own UI bundle for CSS styling:
 
 * `ui-bundle-docs`
 * `ui-bundle-widget`
 
-In general, both playbooks should match each other, while each UI bundle should be unique.
+In most cases, the playbooks should match and UI bundles should be unique.
 
 [#_navigation_bar]
 == Navigation bar
@@ -366,24 +366,23 @@ Content.
 
 One day we'll create our own, but for now we follow the link:https://learn.microsoft.com/en-us/style-guide/brand-voice-above-all-simple-human[Microsoft Style Guide] for style and voice.
 
-[#_publishing]
-== Publishing
+[#_docker_commands]
+== Docker commands
 
-We use link:https://www.docker.com/[Docker] to publish content to link:https://docs.kobiton.com/[docs.kobiton.com] and the help widget on link:https://portal.kobiton.com/[portal.kobiton.com]. Run the following commands to check if its installed:
+We use link:https://www.docker.com/[Docker] and link:https://www.jenkins.io/[Jenkins] to publish content to link:https://docs.kobiton.com/[docs.kobiton.com] and the help widget on link:https://portal.kobiton.com/[portal.kobiton.com].
 
-[source,shell]
-----
-docker --version
-----
+=== `docs`
 
-To build an image for link:https://docs.kobiton.com/[docs.kobiton.com], run:
+Images for link:https://docs.kobiton.com/[docs.kobiton.com] are built using the following Docker command:
 
 [source,shell]
 ----
 docker build -t kobiton/docs:1.0 -f docker/docs/Dockerfile .
 ----
 
-To build a docker image for the help widget on link:https://portal.kobiton.com/[portal.kobiton.com], run:
+=== `widget`
+
+Images for the help widget on link:https://portal.kobiton.com/[portal.kobiton.com] are built using the following Docker command:
 
 [source,shell]
 ----

README.adoc

@@ -4,7 +4,7 @@ This repository contains the source files for link:https://docs.kobiton.com/[doc
 
 - link:https://github.com/kobiton/documentation/issues/new?assignees=&labels=&template=report-an-issue.md&title=[Report an issue]
 - link:https://github.com/kobiton/documentation/issues/new?assignees=&labels=&template=request-a-feature.md&title=[Request a feature]
-- xref:CONTRIBUTE.adoc[Contribute]
+- xref:CONTRIBUTING.adoc[Contribute]
 
 == Quick start