From 310a908479155a1966baf18a411d8d950009a63b Mon Sep 17 00:00:00 2001 From: Isaiah Robinson <95643215+internetisaiah@users.noreply.github.com> Date: Wed, 14 Jun 2023 09:28:48 -0700 Subject: [PATCH] Quick content fixes for CONTRIBUTING and README --- CONTRIBUTE.adoc => CONTRIBUTING.adoc | 45 ++++++++++++++-------------- README.adoc | 2 +- 2 files changed, 23 insertions(+), 24 deletions(-) rename CONTRIBUTE.adoc => CONTRIBUTING.adoc (80%) diff --git a/CONTRIBUTE.adoc b/CONTRIBUTING.adoc similarity index 80% rename from CONTRIBUTE.adoc rename to CONTRIBUTING.adoc index 3673c5b4..51f9f5e1 100644 --- a/CONTRIBUTE.adoc +++ b/CONTRIBUTING.adoc @@ -2,13 +2,13 @@ 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[] @@ -16,7 +16,7 @@ If you're new to docs-as-code, see _first_time_contributors, otherwise choose a * xref:_partials[] * xref:_page_types_and_templates[] * xref:_style_and_voice[] -* xref:_publishing[] +* xref:_docker_commands[] [#_first_time_contributors] == First time contributors @@ -25,7 +25,7 @@ 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] @@ -33,7 +33,7 @@ Version control allows our team to work on documents simultaneously without acci === 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,14 +54,14 @@ 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] ---- @@ -69,7 +69,7 @@ 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] ---- diff --git a/README.adoc b/README.adoc index 1c1d2964..5b3815e6 100644 --- a/README.adoc +++ b/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