From 3d66eccd1d4e7b3c2c541edb404a4ee68f61e00b Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Thu, 21 May 2026 13:58:52 -0400 Subject: [PATCH 01/46] spelling: a Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com> --- gems/docopslab-dev/README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gems/docopslab-dev/README.adoc b/gems/docopslab-dev/README.adoc index 13c6e634..79e4d34b 100644 --- a/gems/docopslab-dev/README.adoc +++ b/gems/docopslab-dev/README.adoc @@ -101,7 +101,7 @@ If this is _your first time using_ `docopslab-dev` on a given workstation, you w If you have the prerequisites and are just getting started with _a given DocOps Lab project_, you should be ready after <>. -If you are initializing `docopslab-dev` in an new project, you will also need to initialize the environment. +If you are initializing `docopslab-dev` in a new project, you will also need to initialize the environment. [[prerequisites]] === Prerequisites From c123390d0553317cee42e376336e5e9da6ce4310 Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Thu, 21 May 2026 14:08:00 -0400 Subject: [PATCH 02/46] spelling: absolute Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com> --- gems/docopslab-dev/specs/data/manifest-schema.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gems/docopslab-dev/specs/data/manifest-schema.yaml b/gems/docopslab-dev/specs/data/manifest-schema.yaml index 263f366b..0b362daa 100644 --- a/gems/docopslab-dev/specs/data/manifest-schema.yaml +++ b/gems/docopslab-dev/specs/data/manifest-schema.yaml @@ -144,7 +144,7 @@ $schema: repo: type: String desc: | - Git repository to fetch library from, either on Git (`owner/name`) or a local path on host (value starting: `~` for relative to home, `.` for relevant to present directory, or `/` for asbolute paths). + Git repository to fetch library from, either on Git (`owner/name`) or a local path on host (value starting: `~` for relative to home, `.` for relevant to present directory, or `/` for absolute paths). default: DocOps/lab ref: type: String From 081c1e307d91866630b308424c6262e2b2584ae8 Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Thu, 21 May 2026 14:55:26 -0400 Subject: [PATCH 03/46] spelling: and link Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com> --- _docs/reference/asciidoc-styles.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/reference/asciidoc-styles.adoc b/_docs/reference/asciidoc-styles.adoc index 5438b744..1dc08bf0 100644 --- a/_docs/reference/asciidoc-styles.adoc +++ b/_docs/reference/asciidoc-styles.adoc @@ -47,7 +47,7 @@ That guide is reproduced here. [[general-asciidoc-syntax-guidelines]] == General AsciiDoc Syntax Guidelines -DocOps Lab documentation largely follows the conventions outlined in the link:https://asciidoctor.org/docs/asciidoc-recommended-practices/[Recommended Practices] andlink:https://asciidoctor.org/docs/asciidoc-writers-guide/[Writer's Guide] documents maintained by the Asciidoctor project. +DocOps Lab documentation largely follows the conventions outlined in the link:https://asciidoctor.org/docs/asciidoc-recommended-practices/[Recommended Practices] and link:https://asciidoctor.org/docs/asciidoc-writers-guide/[Writer's Guide] documents maintained by the Asciidoctor project. Reinforcements and exceptions: From b445cd5698eb6cdcef3db027ba0c303b6fdd4b03 Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Thu, 21 May 2026 13:58:26 -0400 Subject: [PATCH 04/46] spelling: and Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com> --- _blog/tech-blogging-in-asciidoc.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_blog/tech-blogging-in-asciidoc.adoc b/_blog/tech-blogging-in-asciidoc.adoc index 8269e3ac..3a23de04 100644 --- a/_blog/tech-blogging-in-asciidoc.adoc +++ b/_blog/tech-blogging-in-asciidoc.adoc @@ -271,7 +271,7 @@ AsciiDoc also supports ordered lists (numbered), unordered lists (bulleted), and [[ordered-lists]] ==== Ordered Lists -Ordered lists can be pretty powerful, in that you can start an re-start them at any number. +Ordered lists can be pretty powerful, in that you can start and re-start them at any number. .Ordered list example ======== From 1b209cbe18275927d4531ba4927f3d09f193e075 Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Thu, 21 May 2026 14:08:38 -0400 Subject: [PATCH 05/46] spelling: attribute Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com> --- _docs/agent/missions/_common.adoc | 2 +- slides/internal/index.html | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_docs/agent/missions/_common.adoc b/_docs/agent/missions/_common.adoc index 0853c9f0..539b73d8 100644 --- a/_docs/agent/missions/_common.adoc +++ b/_docs/agent/missions/_common.adoc @@ -30,7 +30,7 @@ Switch lenses deliberately; shared base knowledge (README, goals, conventions) s * Always ask the Operator when you don't know exactly how DocOps Lab prefers a step be carried out. * Always follow the mission procedure as closely as possible, adapting only when necessary due to project-specific constraints. * Always document any deviations from the standard procedure and the reasons for them in the Mission Report. -* Always look for a DRY way to define product metadata/attrbutes in README.adoc and YAML files (`specs/data/*-def.yml`). +* Always look for a DRY way to define product metadata/attributes in README.adoc and YAML files (`specs/data/*-def.yml`). * Always pause for Operator approval before ANY publishing or deployment action, including pushing/posting to GitHub. // end::always[] diff --git a/slides/internal/index.html b/slides/internal/index.html index 7fafe4a8..95887b4b 100644 --- a/slides/internal/index.html +++ b/slides/internal/index.html @@ -873,7 +873,7 @@ block.innerHTML = betterTrim( block ); } - // Escape HTML tags unless the "data-noescape" attrbute is present + // Escape HTML tags unless the "data-noescape" attribute is present if( config.escapeHTML && !block.hasAttribute( 'data-noescape' )) { block.innerHTML = block.innerHTML.replace( //g, '>' ); } From 367eb41f86565a139b4ce9396b0652457f322727 Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Thu, 21 May 2026 15:31:19 -0400 Subject: [PATCH 06/46] spelling: based Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com> --- _data/tech-docs-serials.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_data/tech-docs-serials.yml b/_data/tech-docs-serials.yml index 184f96aa..ed2fe517 100644 --- a/_data/tech-docs-serials.yml +++ b/_data/tech-docs-serials.yml @@ -387,7 +387,7 @@ services: site: https://www.dufcrule.com/posts/ tags: [technical-writing, ai] desc: | - Occasional posts by a Spain-baed tech writer named Ian. + Occasional posts by a Spain-based tech writer named Ian. - name: technicalwriting.dev site: https://technicalwriting.dev From 404061128c23fad5782dcdc1fb747d1db252f2b1 Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Thu, 21 May 2026 14:55:57 -0400 Subject: [PATCH 07/46] spelling: bug fixing Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com> --- _docs/agent/roles/_upgrades.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/agent/roles/_upgrades.adoc b/_docs/agent/roles/_upgrades.adoc index 883e86ee..06f7443f 100644 --- a/_docs/agent/roles/_upgrades.adoc +++ b/_docs/agent/roles/_upgrades.adoc @@ -15,7 +15,7 @@ Technical Writer:: Add documentation authoring and quality control capabilities // end::tech-writer[] // tag::product-engineer[] -Product Engineer:: Add code implementation and bugfixing capabilities (`.agent/docs/roles/product-engineer.md`) +Product Engineer:: Add code implementation and bug fixing capabilities (`.agent/docs/roles/product-engineer.md`) // end::product-engineer[] // tag::devops-release-engineer[] From 1f940563c579c30bf8fb4fe086522b7025e45e44 Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Thu, 21 May 2026 14:56:52 -0400 Subject: [PATCH 08/46] spelling: cleverly Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com> --- _data/docops-lab-projects.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_data/docops-lab-projects.yml b/_data/docops-lab-projects.yml index a610bd59..55cfced2 100644 --- a/_data/docops-lab-projects.yml +++ b/_data/docops-lab-projects.yml @@ -1227,7 +1227,7 @@ $meta: # there is crossover, tags may include OTHER types. # 8. Each project should have a tech array, which is an array of technologies # used in the project, such as programming languages, frameworks, or libraries. -# 9. Each project should have an icon, which is a clevrely representative Lucide +# 9. Each project should have an icon, which is a cleverly representative Lucide # icon name from: https://lucide.dev/icons # 10. Each project should have a line, which is a short, one-line description of # the project, suitable for use in a list or summary. From f6e11e5a460bbfd65543334dee3b58bc1ddfe838 Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Thu, 21 May 2026 14:09:20 -0400 Subject: [PATCH 09/46] spelling: conditional Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com> --- slides/internal/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/slides/internal/index.html b/slides/internal/index.html index 95887b4b..1d463fdb 100644 --- a/slides/internal/index.html +++ b/slides/internal/index.html @@ -423,7 +423,7 @@

Key Differences

External/User Docs are:

  • easy for users to discover and access

  • expected to be more polished and accurate

Risks of bad or missing docs

AudiencePotential Cost

customer

revenue loss

prospect

deal loss

coworker

frustration, cycles

open-source dev

code contributions

Solutions

Internal Documentation Principles

  1. All docs are first-class docs.

  2. Meet developers where they’re at (authoring and discovery).

  3. Minimize the number of technologies.

  4. Don’t repeat yourself (DRY).

All Docs are First Class

  • edited and architected by content professionals

  • delivered conveniently

  • accurate

  • polished

Meet Devs in Dev World

  • Use existing dev platforms

    • JIRA/GitHub Issues

    • Confluence/Wiki

    • Docs-as-code via Git

    • Commandline tools

Meet Devs in Dev World (Cont’d)

  • Deliver to accessible platform

    • Could be Confluence

    • Could be static site on company VPN

    • Could be GitHub wiki or Notion

Keep the Toolchain Short

  • SSG or Wiki/CMS?

  • collaboration platform

  • runtime environments / Docker

  • linters

  • deployment platform

Keep the Language Stack Shorter

  • Content markup (Markdown, AsciiDoc*, rST)

  • Data markup (YAML*, JSON, CSV)

  • Template markup (Liquid*, Jinja2, Handlebars)

  • Scripting (Bash*, Python, Rust, Golang)

Write Once, Deliver Everywhere

  • DRY / Single Source of Truth (SSoT)

  • True single sourcing defines product and docs

  • Minimize "hand-offs" between SMEs & documentarians

Conditionalize Source

  • Generate multiple versions of the same document

    • differ by audience role

    • differ by delivery method

  • Use modular content

    • if/else conditions

    • transclusion of reusable content

-

Examples

Example: AsciiDoc Conditonal & Transclusion

asciidoc conditional includes
+

Examples

Example: AsciiDoc Conditional & Transclusion

asciidoc conditional includes
command
asciidoctor -a env-internal --out-file=docs.html docs.adoc

Example: YAML Truth Sourcing

properties:
   base_url:
     summary: The base path to the resource.

From 92c30e40c1c9c33bf7901d4bec6ab89c1eafc5ae Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:09:25 -0400
Subject: [PATCH 10/46] spelling: configured

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 gems/docopslab-dev/specs/data/manifest-schema.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gems/docopslab-dev/specs/data/manifest-schema.yaml b/gems/docopslab-dev/specs/data/manifest-schema.yaml
index 0b362daa..70849192 100644
--- a/gems/docopslab-dev/specs/data/manifest-schema.yaml
+++ b/gems/docopslab-dev/specs/data/manifest-schema.yaml
@@ -112,7 +112,7 @@ $schema:
           type: Boolean
           desc: |
             Whether to auto-sync this file from upstream.
-            If properly conigured, local modifications outside canonical blocks.
+            If properly configured, local modifications outside canonical blocks.
           default: true
         data:
           type: Map

From 318548202a36a93ba34574691081ff127fdb96f2 Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:09:44 -0400
Subject: [PATCH 11/46] spelling: demonstration

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _data/docops-lab-projects.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_data/docops-lab-projects.yml b/_data/docops-lab-projects.yml
index 55cfced2..f734c996 100644
--- a/_data/docops-lab-projects.yml
+++ b/_data/docops-lab-projects.yml
@@ -1085,7 +1085,7 @@ projects:
   - name: Kitchen Sink REST API Demo
     slug: kitchen-sink-rest
     type: demo
-    line: A complex but small REST API for testing and demonstraton of OpenAPI docs generation
+    line: A complex but small REST API for testing and demonstration of OpenAPI docs generation
     desc: |
       A sample REST API with OpenAPI 3.0 spec, Postman collection, and example client code in Ruby, Python, and JavaScript.
     vrsn: V1

From a1659be5e64903b9adadd7d8e27e9dd3c463c64b Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:09:56 -0400
Subject: [PATCH 12/46] spelling: depends

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _includes/project-details.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_includes/project-details.html b/_includes/project-details.html
index 36ca7dd3..a42a3231 100644
--- a/_includes/project-details.html
+++ b/_includes/project-details.html
@@ -184,7 +184,7 @@ 
Package Collections

     
{{ pack[0] }}

     
{{ pack[1].desc }}

     {% if pack[1].deps %}
-    
Dependends on: {{ pack[1].deps | join: ', ' }}

+    
Depends on: {{ pack[1].deps | join: ', ' }}

     {% endif %}
     {% if pack[1].libs %}
     


From 6fff52f7f07742f07e7fa82d1c5edd091cc74ba1 Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:12:19 -0400
Subject: [PATCH 13/46] spelling: docopslab

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 Rakefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Rakefile b/Rakefile
index 5406b2db..aef95a05 100644
--- a/Rakefile
+++ b/Rakefile
@@ -231,7 +231,7 @@ task :write_rubocop_styles do
 end
 
 desc 'Render an AsciiDoc file of universal attributes'
-# use _data/docops-lab-projects.yml data and the Liquid template at _includes/docpslab-universal-attributes.asciidoc to produce a file at _docs/partials/built/_docopslab-universal-attributes.adoc
+# use _data/docops-lab-projects.yml data and the Liquid template at _includes/docopslab-universal-attributes.asciidoc to produce a file at _docs/partials/built/_docopslab-universal-attributes.adoc
 task :generate_universal_attributes do
   puts '📄 Generating universal attributes AsciiDoc file...'
 

From 24e571cc917bfd7a9a71f598643d80264efc3a68 Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:12:07 -0400
Subject: [PATCH 14/46] spelling: documentation

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _data/docops-lab-projects.yml | 2 +-
 _sass/_document.scss          | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/_data/docops-lab-projects.yml b/_data/docops-lab-projects.yml
index f734c996..0c4d59cf 100644
--- a/_data/docops-lab-projects.yml
+++ b/_data/docops-lab-projects.yml
@@ -941,7 +941,7 @@ projects:
       Data Schema specifications or requirements docs for specialized SGYML (YAML) data objects, for governing flat-file data sources as code.
       These standards specify how end users can create custom definitional documents out of these syntaxes and process them.
       These natural-language specifications and their SGYML Schema counterparts dictate: how SchemaGraphy validators, parsers, and other supporting utilities should be configured to process SGYML documents in specific syntaxes.
-      This monorepo includes full documentaton of each "`spec`", though contents are mainly sourced in separate repos alongside a flagship API for the given syntax.
+      This monorepo includes full documentation of each "`spec`", though contents are mainly sourced in separate repos alongside a flagship API for the given syntax.
     deps: [schemagraphy]
     subjects:
       - name: OpenHXY
diff --git a/_sass/_document.scss b/_sass/_document.scss
index 01af3b63..b7493ba3 100644
--- a/_sass/_document.scss
+++ b/_sass/_document.scss
@@ -184,7 +184,7 @@
     }
   }
 
-  // DOCMENTATION INDEX PAGE
+  // DOCUMENTATION INDEX PAGE
   .document-container.index {
     .docs-list {
       h4 {

From 571e08e2187238e3128ae96a0ede682cc22d5181 Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 13:59:29 -0400
Subject: [PATCH 15/46] spelling: element(s)

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _data/jekyll-asciidoc-ui-config-def.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_data/jekyll-asciidoc-ui-config-def.yml b/_data/jekyll-asciidoc-ui-config-def.yml
index 1715608e..a848b4e8 100644
--- a/_data/jekyll-asciidoc-ui-config-def.yml
+++ b/_data/jekyll-asciidoc-ui-config-def.yml
@@ -482,7 +482,7 @@ properties:
                     dflt: '.buzz, .key, .buzz dt, .keywords dt'
                     type: Selector
                     docs: |
-                      CSS selector for the element/s the content of which will be used to generate the keywords meta tag.
+                      CSS selector for the element(s) the content of which will be used to generate the keywords meta tag.
                   specifier:
                     dflt: 'kee-'
                     type: Slug

From 92f9f72bbd1ba064aaa1f0aa572e14fcfd9a1deb Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:12:52 -0400
Subject: [PATCH 16/46] spelling: elimination

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 slides/internal/index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/slides/internal/index.html b/slides/internal/index.html
index 1d463fdb..ea2b5824 100644
--- a/slides/internal/index.html
+++ b/slides/internal/index.html
@@ -416,7 +416,7 @@
 
Technical Documentation
Public vs Internal
Opening
Presenter
  • Brian Dominick, DocOps Lab
  • docopslab.org
  • 25 years software development experience
  • 10 years tech-docs specialization
Presenter
  • Tech writer for BigData Engineering startup (2015-2018)
  • DocOps contractor since acquisition (2018-present)
  • Working on DocOps framework, utilities, libraries, and trainings/courses
  • Write the Docs participant since 2017
Audience
  • You are either a product developer or technical writer (or aspiring).
  • You are looking to initiate or improve the handling of internal documentation at some kind of engineering organization (or expect to).
Focus
  • Product is enterprise software
  • Subject-matter experts are developers and product managers
  • Product audience includes downstream developers and end users

 
Definitions
Jargon
Git
Leading (dominant) version-control system for flat-file tracking
API
Application programming interface
SDK
Software development kit
docs-as-code
Documentation authored using the same tools and processes as product code
Internal Roles
documentarian
Someone who contributes substantially to docs
TW
Technical writer
PM
Project or product manager
Support
Customer support technician or represntative
External (User) Roles
end user
Someone who uses the most-abstract interfaces of the product (mobile apps, web forms, even CLIs)
downstream dev
Or “dev user”, someone who uses the product’s APIs, SDKs, etc
External Docs
  • focus on interfaces
  • consumer is customer / client / prospect / user
  • includes downstream “dev docs”: API/SDK/etc
Internal Docs
  • also focus on interfaces
    • including private APIs, etc
  • also cover resources
    • assets, infrastructure, processes, styles
  • consumer is coworker / collaborator / successor / you
  • may be publicly accessible (open source)

 
Problems
Divergence and Convergence
Documentation of overlapping subjects is authored and output in different ways, using different tools.
Content divergence is an inevitable problem that can be solved with innovation.

-
Source duplication is a problem that can only be solved with manual effort (or elimintation).
Divergence Breakdown
contributor roles
developers, TWs, PMs
tech preferences
WYSIWYG, CCMS/XML, lightweight markup, Git, etc
audiences
end users, downstream devs, internal devs, etc
delivery methods
static site, wiki, PDF, etc
The Platform Divide
InternalUser/Dev Docs
Confluence
Markdown & GitHub Pages
Google Docs/Sheets
ReadTheDocs
Notion
OpenAPI/Markdown
SharePoint / Office 365
MadCap Flare / DITA
Duplication of Truth Sources
Source 1
The product source code.
Source 2
The documentation source code.

+
Source duplication is a problem that can only be solved with manual effort (or elimination).
Divergence Breakdown
contributor roles
developers, TWs, PMs
tech preferences
WYSIWYG, CCMS/XML, lightweight markup, Git, etc
audiences
end users, downstream devs, internal devs, etc
delivery methods
static site, wiki, PDF, etc
The Platform Divide
InternalUser/Dev Docs
Confluence
Markdown & GitHub Pages
Google Docs/Sheets
ReadTheDocs
Notion
OpenAPI/Markdown
SharePoint / Office 365
MadCap Flare / DITA
Duplication of Truth Sources
Source 1
The product source code.
Source 2
The documentation source code.

 
It matters not at all what is written in Confluence or Markdown or Flare if the source code does not agree.
(Ideal) Audience Breakdown
Internal DocsPublic Docs
Internal Devs
Public & private APIs, SDKs, policies
N/A
Downstream Devs
N/A
Public APIs, SDKs, etc
End Users
N/A
Public UIs, tutorials, etc
Docs Source Convergence
internal docs venn diagram
Content Complication Examples
private/public APIs
Same API might have 90% overlap, 10% private endpoints.
 Docs sourced in code or aside.
configuration
Config is defined internally, used by downstream devs and end users.
 Docs usually sourced aside.
Typical Implementation
  • 2 API references: public on Mintlify or SwaggerHub, used by both internal and downstream devs, private in Confluence or Notion used by internal devs.
  • 2-4 config guides: public on ReadTheDocs, premium for paid users in the WebUI, private versions of both on GitHub, used by devs and QA testers.
Key Differences
Internal Docs are:


From 395df4194d0f0139be3b846fe894889ead1cc043 Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:13:09 -0400
Subject: [PATCH 17/46] spelling: example

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _docs/reference/_asciidoc-syntax.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_docs/reference/_asciidoc-syntax.adoc b/_docs/reference/_asciidoc-syntax.adoc
index 988d3a9f..9fd20b4d 100644
--- a/_docs/reference/_asciidoc-syntax.adoc
+++ b/_docs/reference/_asciidoc-syntax.adoc
@@ -185,7 +185,7 @@ Instances of the following block types may commonly be instances of examples, an
 * literal blocks (sample prompts, logs, etc)
 * rich-text snippets (rendered results, a user story, etc)
 
-Whenever any such instances _are examples_, prepend and append them with example blocks, and prefer to title them at the exampple-block level rather than the inner-content level.
+Whenever any such instances _are examples_, prepend and append them with example blocks, and prefer to title them at the example-block level rather than the inner-content level.
 
 .Example of a code block treated as an example
 [source,asciidoc]

From bcc90441ae60db4386bcb7064d484b8663aa9da5 Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:13:17 -0400
Subject: [PATCH 18/46] spelling: except

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _docs/reference/asciidoc-styles.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_docs/reference/asciidoc-styles.adoc b/_docs/reference/asciidoc-styles.adoc
index 1dc08bf0..9801f602 100644
--- a/_docs/reference/asciidoc-styles.adoc
+++ b/_docs/reference/asciidoc-styles.adoc
@@ -52,7 +52,7 @@ DocOps Lab documentation largely follows the conventions outlined in the link:ht
 
 Reinforcements and exceptions:
 
-* Use `.adoc` extensions _execpt_ for Liquid templates used to render AsciiDoc files, which use `.asciidoc`.
+* Use `.adoc` extensions _except_ for Liquid templates used to render AsciiDoc files, which use `.asciidoc`.
 * Use one sentence per line formatting.
 ** Let hard-returns signal spaces between sentences.
 ** Also do this for major colon- or semicolon-delimited sentences.

From 3fd6362e1ed1ef76bc5fa1ca05d01616f3b74a95 Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:05:21 -0400
Subject: [PATCH 19/46] spelling: fall back

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 gems/docopslab-dev/README.adoc | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/gems/docopslab-dev/README.adoc b/gems/docopslab-dev/README.adoc
index 79e4d34b..7f23c10c 100644
--- a/gems/docopslab-dev/README.adoc
+++ b/gems/docopslab-dev/README.adoc
@@ -123,7 +123,7 @@ Vale::
 * `brew install vale` (macOS)
 * `apt install vale` (Ubuntu/Debian)  
 * `dnf install vale` (Fedora)
-* If not installed, `vale` operations will fallback to Docker execution
+* If not installed, `vale` operations will fall back to Docker execution
 
 Asciidoctor (to support Vale)::
 * installed globally
@@ -136,13 +136,13 @@ ShellCheck::
 * `brew install shellcheck` (macOS)
 * `apt install shellcheck` (Ubuntu/Debian)  
 * `dnf install shellcheck` (Fedora)
-* If not installed, `shellcheck` operations will fallback to Docker execution
+* If not installed, `shellcheck` operations will fall back to Docker execution
 
 actionlint::
 * `brew install actionlint` (macOS)`
 * `go install github.com/rhysd/actionlint/cmd/actionlint@latest` (Go 1.16 or later)
 * Otherwise see link:https://github.com/rhysd/actionlint/blob/v1.7.7/docs/install.md[install guide].
-* If not installed, `actionlint` operations will fallback to Docker execution
+* If not installed, `actionlint` operations will fall back to Docker execution
 
 gh (preferred) or git::
 * `brew install gh` (macOS)

From 8e7f594f5f8ae183c8d67a1505926df9b919870b Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:07:09 -0400
Subject: [PATCH 20/46] spelling: for

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _docs/agent/topics/devops-ci-cd.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_docs/agent/topics/devops-ci-cd.adoc b/_docs/agent/topics/devops-ci-cd.adoc
index 36e1c675..67a1ff2c 100644
--- a/_docs/agent/topics/devops-ci-cd.adoc
+++ b/_docs/agent/topics/devops-ci-cd.adoc
@@ -5,7 +5,7 @@ indexed: false
 = AI Agent Orientation to DocOps Lab DevOps/CI/CD Practices
 include::../_agent_settings.adoc[]
 
-DocOps Lab is in a very nascent stage of establishing shared (cross-repo) tools, workflows, and protocols to for automating development, integration, build, and deployment processes.
+DocOps Lab is in a very nascent stage of establishing shared (cross-repo) tools, workflows, and protocols for automating development, integration, build, and deployment processes.
 
 DocOps Lab uses GitHub Actions and Docker as primary platforms for integration and deployment automation.
 

From 6bbd9753d583c8fff511f3dbc554882a3405a980 Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:19:00 -0400
Subject: [PATCH 21/46] spelling: githubusercontent

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _data/jekyll-asciidoc-ui-config-def.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_data/jekyll-asciidoc-ui-config-def.yml b/_data/jekyll-asciidoc-ui-config-def.yml
index a848b4e8..afc93ca3 100644
--- a/_data/jekyll-asciidoc-ui-config-def.yml
+++ b/_data/jekyll-asciidoc-ui-config-def.yml
@@ -1024,7 +1024,7 @@ properties:
 # tag::dry-yaml[]
               type_definitions:
                 dflt: &type_definitions_map
-                  $ref: "https://raw.githubcontent.com/DocOps/aylstack/content-types.yml#ditataxis-plus"
+                  $ref: "https://raw.githubusercontent.com/DocOps/aylstack/content-types.yml#ditataxis-plus"
                 desc: &type_description |
                   A collection of "`content types`" supported by your style guidance, in the form of a Map of types and their properties.
                 docs: &type_definitions_docs |

From 3566d7b3d8ed3c1c9693d4e1ea64d00eb0d6ce6a Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:14:00 -0400
Subject: [PATCH 22/46] spelling: high

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _docs/agent/roles/planner-architect.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_docs/agent/roles/planner-architect.adoc b/_docs/agent/roles/planner-architect.adoc
index 717d45e2..6c900b1b 100644
--- a/_docs/agent/roles/planner-architect.adoc
+++ b/_docs/agent/roles/planner-architect.adoc
@@ -78,4 +78,4 @@ A good plan is something a mid-level engineer can execute without re-designing i
 * PlantUML with C4 extensions for architecture diagrams.
 * AsciiDoc for natural language specifications.
 * YAML for schema/definition documents.
-* Ruby, Bash, JavaScript, SQL, REST (Highl-level modeling and outlining)
\ No newline at end of file
+* Ruby, Bash, JavaScript, SQL, REST (High-level modeling and outlining)
\ No newline at end of file

From d00fa9d2b72bae16d4ab6891d5c676c97021e047 Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:05:48 -0400
Subject: [PATCH 23/46] spelling: javascript

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _blog/true-single-sourcing.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_blog/true-single-sourcing.adoc b/_blog/true-single-sourcing.adoc
index ab4f7a10..5128b2c3 100644
--- a/_blog/true-single-sourcing.adoc
+++ b/_blog/true-single-sourcing.adoc
@@ -116,7 +116,7 @@ These can involve data processing and logic, but they are relatively simple and
 Liquid was specifically designed for non-developers, and generative-AI coding tools are adept at writing templates in nearly all popular syntaxes.
 This means those savvy non-programmers can help author data files _and_ help turn them into good, auto-generated reference documentation.
 
-This non-programmer involvement is but one of the key advantages of stepping away from "`native`" (Python, Java, Rust, Javascript, Ruby, Golang, etc) programming code and into a truly cross-language, human-writeable data format like YAML.
+This non-programmer involvement is but one of the key advantages of stepping away from "`native`" (Python, Java, Rust, JavaScript, Ruby, Golang, etc) programming code and into a truly cross-language, human-writeable data format like YAML.
 
 [NOTE]
 While YAML is second only to JSON and XML in terms of current popularity, it is wildly more user- and Git-friendly than the leading formats.

From 6c1c3da8e036a26ad847c0d7f092bf72c6daa163 Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:05:59 -0400
Subject: [PATCH 24/46] spelling: jira

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 slides/internal/index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/slides/internal/index.html b/slides/internal/index.html
index ea2b5824..b937b723 100644
--- a/slides/internal/index.html
+++ b/slides/internal/index.html
@@ -422,7 +422,7 @@
 Docs usually sourced aside.

Typical Implementation

  • 2 API references: public on Mintlify or SwaggerHub, used by both internal and downstream devs, private in Confluence or Notion used by internal devs.

  • 2-4 config guides: public on ReadTheDocs, premium for paid users in the WebUI, private versions of both on GitHub, used by devs and QA testers.

Key Differences

Internal Docs are:

  • more directly maintained by SMEs

  • fewer constraints on delivery methods/formats

  • not expected to be as “polished”

  • backed up by code (real source of truth)

Key Differences

External/User Docs are:

  • easy for users to discover and access

  • expected to be more polished and accurate

Risks of bad or missing docs

AudiencePotential Cost

customer

revenue loss

prospect

deal loss

coworker

frustration, cycles

open-source dev

code contributions

-

Solutions

Internal Documentation Principles

  1. All docs are first-class docs.

  2. Meet developers where they’re at (authoring and discovery).

  3. Minimize the number of technologies.

  4. Don’t repeat yourself (DRY).

All Docs are First Class

  • edited and architected by content professionals

  • delivered conveniently

  • accurate

  • polished

Meet Devs in Dev World

  • Use existing dev platforms

    • JIRA/GitHub Issues

    • Confluence/Wiki

    • Docs-as-code via Git

    • Commandline tools

Meet Devs in Dev World (Cont’d)

  • Deliver to accessible platform

    • Could be Confluence

    • Could be static site on company VPN

    • Could be GitHub wiki or Notion

Keep the Toolchain Short

  • SSG or Wiki/CMS?

  • collaboration platform

  • runtime environments / Docker

  • linters

  • deployment platform

Keep the Language Stack Shorter

  • Content markup (Markdown, AsciiDoc*, rST)

  • Data markup (YAML*, JSON, CSV)

  • Template markup (Liquid*, Jinja2, Handlebars)

  • Scripting (Bash*, Python, Rust, Golang)

Write Once, Deliver Everywhere

  • DRY / Single Source of Truth (SSoT)

  • True single sourcing defines product and docs

  • Minimize "hand-offs" between SMEs & documentarians

Conditionalize Source

  • Generate multiple versions of the same document

    • differ by audience role

    • differ by delivery method

  • Use modular content

    • if/else conditions

    • transclusion of reusable content

+

Solutions

Internal Documentation Principles

  1. All docs are first-class docs.

  2. Meet developers where they’re at (authoring and discovery).

  3. Minimize the number of technologies.

  4. Don’t repeat yourself (DRY).

All Docs are First Class

  • edited and architected by content professionals

  • delivered conveniently

  • accurate

  • polished

Meet Devs in Dev World

  • Use existing dev platforms

    • Jira/GitHub Issues

    • Confluence/Wiki

    • Docs-as-code via Git

    • Commandline tools

Meet Devs in Dev World (Cont’d)

  • Deliver to accessible platform

    • Could be Confluence

    • Could be static site on company VPN

    • Could be GitHub wiki or Notion

Keep the Toolchain Short

  • SSG or Wiki/CMS?

  • collaboration platform

  • runtime environments / Docker

  • linters

  • deployment platform

Keep the Language Stack Shorter

  • Content markup (Markdown, AsciiDoc*, rST)

  • Data markup (YAML*, JSON, CSV)

  • Template markup (Liquid*, Jinja2, Handlebars)

  • Scripting (Bash*, Python, Rust, Golang)

Write Once, Deliver Everywhere

  • DRY / Single Source of Truth (SSoT)

  • True single sourcing defines product and docs

  • Minimize "hand-offs" between SMEs & documentarians

Conditionalize Source

  • Generate multiple versions of the same document

    • differ by audience role

    • differ by delivery method

  • Use modular content

    • if/else conditions

    • transclusion of reusable content

Examples

Example: AsciiDoc Conditional & Transclusion

asciidoc conditional includes
command
asciidoctor -a env-internal --out-file=docs.html docs.adoc

Example: YAML Truth Sourcing

properties:
   base_url:

From 4d0e4426f32a0a0f12a5533e7cc0be76618e2733 Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:58:07 -0400
Subject: [PATCH 25/46] spelling: knowledge base

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _data/tech-docs-serials.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_data/tech-docs-serials.yml b/_data/tech-docs-serials.yml
index ed2fe517..40f964f2 100644
--- a/_data/tech-docs-serials.yml
+++ b/_data/tech-docs-serials.yml
@@ -278,7 +278,7 @@ services:
     Filled with commentary on other writings, this traditional blog is a welcome blast from the past style.
     Kevin looks at all kinds of technology, old and new, from the perspective of a professional tech writer.
 
-- name: Knowledgebase Ninjas Podcast
+- name: Knowledge base Ninjas Podcast
   kind: podcast
   site: https://document360.com/podcast/
   tags: [tech-comm, kb, ai, saas, best-practices]

From 4b2c359b662c50fda85d84def2ceea5fdcad348e Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:14:45 -0400
Subject: [PATCH 26/46] spelling: libraries

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _data/docops-lab-projects.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_data/docops-lab-projects.yml b/_data/docops-lab-projects.yml
index 0c4d59cf..d5aed5f7 100644
--- a/_data/docops-lab-projects.yml
+++ b/_data/docops-lab-projects.yml
@@ -437,7 +437,7 @@ projects:
     slug: schemagraphy-rest
     type: rest-api
     desc: |
-      A RESTful API service for processing schema/data and schema/text combinations without installing SchemaGraphy libaries locally.
+      A RESTful API service for processing schema/data and schema/text combinations without installing SchemaGraphy libraries locally.
     line: REST API for testing and processing SchemaGraphy schemas.
     vrsn: 0.1.0
     tags: [sandbox,schemas,web service,validation,Dockerized]

From 04cbcc8ab0781149927c09b4a349af12c391b53b Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:06:10 -0400
Subject: [PATCH 27/46] spelling: macos

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _docs/policy/mission.adoc        | 2 +-
 _docs/reference/bash-styles.adoc | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/_docs/policy/mission.adoc b/_docs/policy/mission.adoc
index ea2fd240..edb5116a 100644
--- a/_docs/policy/mission.adoc
+++ b/_docs/policy/mission.adoc
@@ -157,7 +157,7 @@ Our commitment to containerization (with Docker, etc) is a key part of this prin
 Similar to some of the sub-principles of reusability, interoperability means technology and techniques that fit and work together in a cohesive manner.
 
 DocOPs favors tool integration and data exchange mechanisms that enable seamless workflows across different systems.
-This also means _effective_ compatibility across operating systems (Windows, MacOS, and Linux).
+This also means _effective_ compatibility across operating systems (Windows, macOS, and Linux).
 
 .Examples of DocOps interoperability
 ====
diff --git a/_docs/reference/bash-styles.adoc b/_docs/reference/bash-styles.adoc
index f5243698..f9d4eca9 100644
--- a/_docs/reference/bash-styles.adoc
+++ b/_docs/reference/bash-styles.adoc
@@ -28,7 +28,7 @@ Scripts that require maximum portability and compatibility should use the POSIX-
 
 These scripts must begin with the shebang `#!/bin/sh` and should be tested in a POSIX-compliant environment to ensure they do not rely on Bash extensions.
 
-This standard is mainly to cover MacOS systems, which do not support Bash 4 out of the box.
+This standard is mainly to cover macOS systems, which do not support Bash 4 out of the box.
 Therefore, bootstrap/installer scripts will need to be executable in a Bash 3 environment, where they can prompt for Bash 4 installation if it is not detected and if it is needed by a follow-on script.
 
 Such files should begin with:

From 375489df20bc1a9c239416e10c5c3deb4a677c99 Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:15:08 -0400
Subject: [PATCH 28/46] spelling: manipulation

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _data/docops-lab-projects.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_data/docops-lab-projects.yml b/_data/docops-lab-projects.yml
index d5aed5f7..20df830a 100644
--- a/_data/docops-lab-projects.yml
+++ b/_data/docops-lab-projects.yml
@@ -758,7 +758,7 @@ projects:
       - inline-term
       - inline-file
       - trademarker
-      # AsciiDoc block semantics/manipulaton
+      # AsciiDoc block semantics/manipulation
       - admonition-ext
       - sidebar-ext
       - code-truncate

From 8ac4090a474a7d98736262fb0e7472007bc38e7c Mon Sep 17 00:00:00 2001
From: Josh Soref <2119212+jsoref@users.noreply.github.com>
Date: Thu, 21 May 2026 14:15:26 -0400
Subject: [PATCH 29/46] spelling: matching

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>
---
 _reports/projects-by-tag.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/_reports/projects-by-tag.html b/_reports/projects-by-tag.html
index e8991636..32381e01 100644
--- a/_reports/projects-by-tag.html
+++ b/_reports/projects-by-tag.html
@@ -35,7 +35,7 @@ 
{{ tag }}
{% assign popular_projects = popular | split: "," %} - +