Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
46 commits
Select commit Hold shift + click to select a range
3d66ecc
spelling: a
jsoref May 21, 2026
c123390
spelling: absolute
jsoref May 21, 2026
081c1e3
spelling: and link
jsoref May 21, 2026
b445cd5
spelling: and
jsoref May 21, 2026
1b209cb
spelling: attribute
jsoref May 21, 2026
367eb41
spelling: based
jsoref May 21, 2026
4040611
spelling: bug fixing
jsoref May 21, 2026
1f94056
spelling: cleverly
jsoref May 21, 2026
f6e11e5
spelling: conditional
jsoref May 21, 2026
92c30e4
spelling: configured
jsoref May 21, 2026
3185482
spelling: demonstration
jsoref May 21, 2026
a1659be
spelling: depends
jsoref May 21, 2026
6fff52f
spelling: docopslab
jsoref May 21, 2026
24e571c
spelling: documentation
jsoref May 21, 2026
571e08e
spelling: element(s)
jsoref May 21, 2026
92f9f72
spelling: elimination
jsoref May 21, 2026
395df41
spelling: example
jsoref May 21, 2026
bcc9044
spelling: except
jsoref May 21, 2026
3fd6362
spelling: fall back
jsoref May 21, 2026
8e7f594
spelling: for
jsoref May 21, 2026
6bbd975
spelling: githubusercontent
jsoref May 21, 2026
3566d7b
spelling: high
jsoref May 21, 2026
d00fa9d
spelling: javascript
jsoref May 21, 2026
6c1c3da
spelling: jira
jsoref May 21, 2026
4d0e442
spelling: knowledge base
jsoref May 21, 2026
4b2c359
spelling: libraries
jsoref May 21, 2026
04cbcc8
spelling: macos
jsoref May 21, 2026
375489d
spelling: manipulation
jsoref May 21, 2026
8ac4090
spelling: matching
jsoref May 21, 2026
203d992
spelling: neighboring
jsoref May 21, 2026
6ac379f
spelling: number
jsoref May 21, 2026
433d1bb
spelling: open graph
jsoref May 21, 2026
2402412
spelling: precede
jsoref May 21, 2026
0993fc6
spelling: programmers
jsoref May 21, 2026
d456e5c
spelling: prompt
jsoref May 21, 2026
866ce0b
spelling: representative
jsoref May 21, 2026
6f33a04
spelling: secondary
jsoref May 21, 2026
b450c87
spelling: section
jsoref May 21, 2026
f38bbc5
spelling: straightforward
jsoref May 21, 2026
5ee2ded
spelling: subdivided
jsoref May 21, 2026
cc21e12
spelling: supplementary
jsoref May 21, 2026
3bbbefe
spelling: the
jsoref May 21, 2026
4d8228c
spelling: to
jsoref May 21, 2026
f3fef78
spelling: when
jsoref May 21, 2026
41e7c0c
spelling: which
jsoref May 21, 2026
ef850c4
spelling: workflows
jsoref May 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Rakefile
Original file line number Diff line number Diff line change
Expand Up @@ -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...'

Expand Down
4 changes: 2 additions & 2 deletions _blog/code-to-docs-pipelines.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ And I added a `project_end_date` for good measure -- you can probably already im
Suddenly, we're either asking the developers to maintain the user-facing documentation _inside their source code_, or we need to find some way to complement the source code with those enhanced docs.

[NOTE]
None of this is to mention that even when product attribute descriptions are staightforward, they often need to be proofread and edited by a professional, who is probably not a developer working in the product codebase.
None of this is to mention that even when product attribute descriptions are straightforward, they often need to be proofread and edited by a professional, who is probably not a developer working in the product codebase.

Doing all of this much better than so-far discussed is quite possible, but I needed to get to this point so anyone reading along can appreciate the problem.
I often hear developers shrug off the idea that this is "`even a thing`".
Expand Down Expand Up @@ -238,7 +238,7 @@ In the following sections, I will detail and show examples of the latter three a
[[overlay-method]]
=== The Overlay Method

Once there is a fixed data structure in place that is being used to generate output for reference codes, that system can be "`overlayed`" with suppliementary or overriding data.
Once there is a fixed data structure in place that is being used to generate output for reference codes, that system can be "`overlayed`" with supplementary or overriding data.

[source,yaml]
----
Expand Down
4 changes: 2 additions & 2 deletions _blog/tech-blogging-in-asciidoc.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ It embeds the content of another file -- in whole _or in part_ -- into a parent

Such includes are also used throughout the link:{page-github-url}?plain=1[source for this post].

Nearly every example of block content in this post is transcluded from an adjacent file called `_asciidoc-snippets.adoc`, which is subvidivded using AsciiDoc include tags, demarcated like so:
Nearly every example of block content in this post is transcluded from an adjacent file called `_asciidoc-snippets.adoc`, which is subdivided using AsciiDoc include tags, demarcated like so:

:tagged_content: Everything between tagged lines is included in the "calling" document.

Expand Down Expand Up @@ -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
========
Expand Down
2 changes: 1 addition & 1 deletion _blog/true-single-sourcing.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
16 changes: 8 additions & 8 deletions _data/docops-lab-projects.yml
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ projects:
Deep-dive courses and other resources for learning general docs-as-code methods.
Initially focused on using AYL DocStack tools and strategies to tackle complex documentation tasks and projects.
Includes nascent AsciiDoc EDU platform/framework code.
line: Learn to author and manage documents the way progrmamers do.
line: Learn to author and manage documents the way programmers do.
star: true
page: true
card: readme
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -649,7 +649,7 @@ projects:
type: utility
desc: |
A development utility that centralizes authoring of common configs, styles/rules, and documentation for sharing across all DocOps Lab project repos.
Provides a numer of Rake tasks for maintaining consistency of distributed libraries and assets used in _development_ of DocOps Lab tools but not necessary for _using_ said tools.
Provides a number of Rake tasks for maintaining consistency of distributed libraries and assets used in _development_ of DocOps Lab tools but not necessary for _using_ said tools.
line: Aka `labdev`, a tool for distributing common libraries and assets across DocOps Lab project repos
vrsn: 0.1.0
tags: [development,environment]
Expand Down Expand Up @@ -758,7 +758,7 @@ projects:
- inline-term
- inline-file
- trademarker
# AsciiDoc block semantics/manipulaton
# AsciiDoc block semantics/manipulation
- admonition-ext
- sidebar-ext
- code-truncate
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -1250,7 +1250,7 @@ $meta:
# only repo visibility. If omitted, assume false (repo is private or doesn't exist yet).
# 15. Projects MAY have a href property, which is a URL to the project's website
# or documentation site. External URLs only (not GitHub repos).
# 16. Projects MAY have a text property, which which is to override the property's
# 16. Projects MAY have a text property, which is to override the property's
# actual name in displays on the website.
# 17. Projects MAY have a look, which is a short description of the project's appearance,
# when relevant, such as a theme or design style.
Expand Down
6 changes: 3 additions & 3 deletions _data/jekyll-asciidoc-ui-config-def.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -728,7 +728,7 @@ properties:
desc: |
A map of keys (prompt indicators) and strings (prompt strings) to use for different prompts.
docs: |
Add key-value pairs to the `alt_strings` object to enable non-default prompt strings associated with an extra role (`.priompt-<key>`, where `<key>` is the key of the prompt string to use).
Add key-value pairs to the `alt_strings` object to enable non-default prompt strings associated with an extra role (`.prompt-<key>`, where `<key>` is the key of the prompt string to use).

For example, to use a different prompt string for a block with the role `.prompt-root`, add something like following to the `alt_strings` object:

Expand Down Expand Up @@ -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 |
Expand Down
4 changes: 2 additions & 2 deletions _data/tech-docs-serials.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion _docs/agent/missions/_common.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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[]

Expand Down
2 changes: 1 addition & 1 deletion _docs/agent/roles/_upgrades.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
Expand Down
2 changes: 1 addition & 1 deletion _docs/agent/roles/planner-architect.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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)
* Ruby, Bash, JavaScript, SQL, REST (High-level modeling and outlining)
4 changes: 2 additions & 2 deletions _docs/agent/topics/devops-ci-cd.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@ 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.

For now you can get a good idea for getting started with automation by checking the standard paths in the current project (`Dockerfile`, `docker-compose.yml`, `.github/workflos/`, `Rakefile`, `scripts/`) as well as looking at similar DocOps Lab projects that have more established CI/CD workflows.
For now you can get a good idea for getting started with automation by checking the standard paths in the current project (`Dockerfile`, `docker-compose.yml`, `.github/workflows/`, `Rakefile`, `scripts/`) as well as looking at similar DocOps Lab projects that have more established CI/CD workflows.

The rest of this document is snippets from various relevant internal documentation.

Expand Down
2 changes: 1 addition & 1 deletion _docs/policy/mission.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
====
Expand Down
2 changes: 1 addition & 1 deletion _docs/reference/_asciidoc-syntax.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
2 changes: 1 addition & 1 deletion _docs/reference/asciidoc-attributes.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Do not use hyphens (`-`) in attribute names except:

. Suffixes carry meaning:

* `_vrsn` for to reference a product version (`this_prod_vrsn`)
* `_vrsn` to reference a product version (`this_prod_vrsn`)
* `_version` for third-party versions (`this_prod_ruby_version`)
* `_majmin` for major.minor version pair
* `_url` for HTTPS addresses
Expand Down
4 changes: 2 additions & 2 deletions _docs/reference/asciidoc-styles.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -47,12 +47,12 @@ 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:

* 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.
Expand Down
2 changes: 1 addition & 1 deletion _docs/reference/bash-styles.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
4 changes: 2 additions & 2 deletions _docs/task/fix-broken-links.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -178,13 +178,13 @@ Use this solution only when the link source is wrong or the target anchor ID is
.Misspelled link source
[source,asciidoc]
----
See xref:sectione-one[Section One] for details.
See xref:section-one[Section One] for details.
----

.Misspelled anchor ID
[source,asciidoc]
----
[[secton-one]]
[[section-one]]
=== Section One
----

Expand Down
2 changes: 1 addition & 1 deletion _docs/task/fix-spelling-issues.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -72,5 +72,5 @@ spellcheck:
output_file: spelling-report.yml # defaults to spellcheck-<datetime>.yml
prompt: |
# Your custom prompt here
# Preceed each line with a hash (#)
# Precede each line with a hash (#)
----
2 changes: 1 addition & 1 deletion _docs/templates/AGENTS.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ This template is published as a rendered document at https://docopslab.org/docs/

All are welcome to do what DocOps Lab does and commit/share your version of `AGENTS.md`, which is inspired by https://agents.md as a standard for AI agent prompting.

**NOTE:** The version of this document you are reading is a _seconrary template_ meant to be copied and customized for each project it is used on.
**NOTE:** The version of this document you are reading is a _secondary template_ meant to be copied and customized for each project it is used on.
Once initially saved to a new repo, search for characters like `<%` and change those placeholders to suit the specific project.

**NOTE:** Use the [raw version](https://github.com/DocOps/lab/blob/main/_docs/templates/AGENTS.markdown?plain=1) of this file instead of the rendered version.
Expand Down
2 changes: 1 addition & 1 deletion _includes/project-details.html
Original file line number Diff line number Diff line change
Expand Up @@ -184,7 +184,7 @@ <h3>Package Collections</h3>
<h4>{{ pack[0] }}</h4>
<p>{{ pack[1].desc }}</p>
{% if pack[1].deps %}
<p><strong>Dependends on:</strong> {{ pack[1].deps | join: ', ' }}</p>
<p><strong>Depends on:</strong> {{ pack[1].deps | join: ', ' }}</p>
{% endif %}
{% if pack[1].libs %}
<div class="pack-libraries">
Expand Down
2 changes: 1 addition & 1 deletion _plugins/jekyll_asciidoc_ext.rb
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
# Build site-wide xref_* attributes from collections and inject them
# into every AsciiDoc page right before Asciidoctor runs.
# Page front matter set as AsciiDoc `page-` attributes are not available
# at the point this hook runs, so conventional frontmatter (--- fenced)
# when this hook runs, so conventional frontmatter (--- fenced)
# is recommended for overriding relevant values such as:
# `xref_id`, `title`, `slug`, `xref_exclude`
#
Expand Down
Loading