SpecAgile - Ascii1000D

Premise

The S1000D specification combines three separate specifications:

Business Architecture Specification includes elements like DMC components (MODELIC, SDC, MICC, SNS, etc), Applicability, CIRs and other constructs supporting defense and aerospace technical data.
Semantic Specification relates elements to semantic elements, like //step as procedural element, //challrsp as challenge / response element.
Markup Specification the actual XSD that defines the XML markup.

Full S1000D systems have combined costs ranging from $12k per user per year to $50k per user per year, not counting migration and maintenance costs. Smaller organizations are unable to support these costs while remaining competitive.

However the Business Architecture is often the singular critical aspect for supporting aerospace and defense projects. That architecture can be established in other markup formats and processes.

Ascii1000D uses the S1000D business architecture as applied in the Asciidoc LML (lightweight markup language), with additional Semantic Specification requirements supported via the use of Asciidoc Roles. Using the Docs-As-Code paradigm, Ascii1000D builds on long-established process that already exists for the management of software code.

Using the Docs-As-Code approach provides a CCMS framework with standard technology on established tooling, rather than bespoke CCMS (component content management system), bespoke editor, and likely a separate bespoke build engine for PDFs and IETMs.

Markup Comparison

The below chart compares equivalent structures from many different Component Content Systems. Note that some structures, like the S1000D CIR reference, is not possible to summarize in the space of the table cell.

Ascii1000D uses the absolute least possible amount of markup by avoiding admixture of document and product semantics, letting the S1000D architecture do its job in terms of addressability, referencing, standardization, and systems engineering.

Why declare incode five different times when you can have it in the filename just once?

Goals

Ascii1000D has a few basic goals

Component Authoring with as Little As Possible
Everything should be able to generate documentation deliverables with as few keystrokes as possible, with as few licenses as possible, as little setup as possible. Our core position is that Technical Publications systems should not be million-dollar integration projects.
Standard Tooling
Pushing S1000D-style deliverables with Ascii1000D will use common developer tooling. If your company has a software group, then these tools will be available: Git-based DVCS (GitLab, GitHub, Bitbucket) as CSDB-equivalent; full-featured text editor (Visual Studio Code, Atom, Sublime, Brackets, Eclipse) as editor; Asciidoctor/Asciidoctor-PDF/DocBook-XSL/CSS for PDF/HTML(IETM L3 Equivalent)/ePub/XML deliverables. No bespoke editors, no bespoke CSDBs, no bespoke publishing systems. Everything is stock - except your content.
S1000D Architecture
Filenames (data module codes), file relationships, data flows, all non-markup related architecture from S1000D is to be used in Ascii1000D. The exception to this is where it violates the above rule: for example, CGM illustrations can’t be implemented on an open architecture, so we adopt SVG instead for all line art.
Business System Agnostic
The system will function regardless of the type or number of different business systems that contain engineering data. It's not tied to a specific PDM/ERP/CAD system.
Engineering Data Sources
The system assumes that engineering data must be integrated using the following formats as interchange: 3MF and/or STEP for design parts data; CSV for engineering parts data, and CSV for Logistics. See Parts Data Information (pCIRs), below.

Ascii1000D

Demonstration of an S1000D publication architecture using the Asciidoc LML (lightweight markup language).

S1000D Architecture, Standard Tooling: Anyone can edit, anyone can render, and everyone can collaborate.
S1000D-style filenaming conventions
CIRs/TIRs (Common Information Repositories) / (Technical Information Repositories) via Include Directive to tagged regions
Conditional Content aka Applicability via Asciidoc Conditional Directives
Content re-use PM (Publication Module) and DMRL (Data Module Requirement List) via Asciidoc Include Directives, and DMRLs for project planning.
Validation requirement is satisfied/exceeded via usage of linters: LanguageTools, Vale, and/or Redpen.cc.
Line art parts identification via SVG+CSS or inclusion of X3D or applicable HTML5 web 3d format.
PDF / HTML IETM L3 Equivalent can be customized with standard tools (JS/CSS, DocBook-XSL, YML)
PDF / HTML IETM L3 Equivalent deliverables can be set up as part of an automated build process using Antora, Gradle, DocToolChain, GitLab (on-prem), or with your org's already-established build automation tool.

Example of Ascii1000D, Visual Studio Code and PDF output

"It's possible this product variant may have some deviance from a supportability perspective"

Parts Data Information (pCIRs)

Note the red line in the following parts data diagram: documentation deliverables must often be structured and sometimes drafted before MTA (Maintenance Task Analysis) can be completed.

This is an enduring problem both in "formal" S1000D and in Ascii1000D : the writer must have DMCs before beginning, but the maintenance planning necessary for DMC creation might be missing or incomplete.

When this occurs, the Configuration Management and Systems Engineering teams must be worked with in close cooperation, to ensure that the writer team does not create a forked Systems Engineering architecture. Alternatively, one of the writer team can perform roles with the Systems Engineering group and make double use of their Systems work by creating DMCs early on.

S1000D mandates usage of semantically/taxonomically significant filenames, so this process must be managed very carefully. Modern Version Control Systems do not distinguish between a renamed file and a new file. Renamed files have an entirely new change history from the point of view of the change system.

Gitflow: Collaboration versus Review