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...' diff --git a/_blog/code-to-docs-pipelines.adoc b/_blog/code-to-docs-pipelines.adoc index 91c2f4e7..e75af321 100644 --- a/_blog/code-to-docs-pipelines.adoc +++ b/_blog/code-to-docs-pipelines.adoc @@ -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`". @@ -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] ---- diff --git a/_blog/tech-blogging-in-asciidoc.adoc b/_blog/tech-blogging-in-asciidoc.adoc index 8269e3ac..4fb84667 100644 --- a/_blog/tech-blogging-in-asciidoc.adoc +++ b/_blog/tech-blogging-in-asciidoc.adoc @@ -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. @@ -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 ======== 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. diff --git a/_data/docops-lab-projects.yml b/_data/docops-lab-projects.yml index a610bd59..082aa967 100644 --- a/_data/docops-lab-projects.yml +++ b/_data/docops-lab-projects.yml @@ -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 @@ -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] @@ -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] @@ -758,7 +758,7 @@ projects: - inline-term - inline-file - trademarker - # AsciiDoc block semantics/manipulaton + # AsciiDoc block semantics/manipulation - admonition-ext - sidebar-ext - code-truncate @@ -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 @@ -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 @@ -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. @@ -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. diff --git a/_data/jekyll-asciidoc-ui-config-def.yml b/_data/jekyll-asciidoc-ui-config-def.yml index 1715608e..3b77c0a3 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 @@ -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-`, where `` 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-`, where `` 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: @@ -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 | diff --git a/_data/tech-docs-serials.yml b/_data/tech-docs-serials.yml index 184f96aa..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] @@ -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 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/_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[] 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 diff --git a/_docs/agent/topics/devops-ci-cd.adoc b/_docs/agent/topics/devops-ci-cd.adoc index 36e1c675..829873e7 100644 --- a/_docs/agent/topics/devops-ci-cd.adoc +++ b/_docs/agent/topics/devops-ci-cd.adoc @@ -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. 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/_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] diff --git a/_docs/reference/asciidoc-attributes.adoc b/_docs/reference/asciidoc-attributes.adoc index 20630838..850a8ba4 100644 --- a/_docs/reference/asciidoc-attributes.adoc +++ b/_docs/reference/asciidoc-attributes.adoc @@ -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 diff --git a/_docs/reference/asciidoc-styles.adoc b/_docs/reference/asciidoc-styles.adoc index 5438b744..9801f602 100644 --- a/_docs/reference/asciidoc-styles.adoc +++ b/_docs/reference/asciidoc-styles.adoc @@ -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. 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: diff --git a/_docs/task/fix-broken-links.adoc b/_docs/task/fix-broken-links.adoc index 50920275..1f074c31 100644 --- a/_docs/task/fix-broken-links.adoc +++ b/_docs/task/fix-broken-links.adoc @@ -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 ---- diff --git a/_docs/task/fix-spelling-issues.adoc b/_docs/task/fix-spelling-issues.adoc index 97ec410c..5bbde28a 100644 --- a/_docs/task/fix-spelling-issues.adoc +++ b/_docs/task/fix-spelling-issues.adoc @@ -72,5 +72,5 @@ spellcheck: output_file: spelling-report.yml # defaults to spellcheck-.yml prompt: | # Your custom prompt here - # Preceed each line with a hash (#) + # Precede each line with a hash (#) ---- \ No newline at end of file diff --git a/_docs/templates/AGENTS.markdown b/_docs/templates/AGENTS.markdown index 05fb9165..581313a8 100644 --- a/_docs/templates/AGENTS.markdown +++ b/_docs/templates/AGENTS.markdown @@ -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. 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 %}
diff --git a/_plugins/jekyll_asciidoc_ext.rb b/_plugins/jekyll_asciidoc_ext.rb index af48b3df..2f8605fe 100644 --- a/_plugins/jekyll_asciidoc_ext.rb +++ b/_plugins/jekyll_asciidoc_ext.rb @@ -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` # 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: "," %} - +