MCCF: S1000D and the Principle of Least Commitment
Watch the MCCF demo
A short video of the Multi-Channel Coherence Field working in an X3D scene. Watch it on YouTube.
You're choosing a document architecture that could make MCCF understandable, maintainable, and interoperable with systems that haven't been built yet.
I think S1000D is a defensible choice, with one important qualification: adopt its information architecture and configuration discipline without necessarily adopting every part of its industrial machinery.
The distinction matters because you have two related objectives:
Get MCCF into the hands of artists, musicians, educators, and developers who need to use it reliably.
Make MCCF a credible participant in a larger Web of Worlds, where documentation, interfaces, assets, and behavior need to remain intelligible as implementations evolve.
A conventional collection of Markdown files might serve the first objective. A properly organized Common Source Database (CSDB) could serve both.
The question isn't whether S1000D is more elaborate than MCCF strictly needs today. It almost certainly is. The question is whether the parts you adopt buy you enough long-term stability to justify their cost.
Why S1000D fits the architecture
The official S1000D model separates reusable information modules from the publications assembled out of them. Each module carries identification and status information, while the CSDB manages the collection. Importantly, the specification doesn't require a particular database implementation.
That last point is particularly favorable to your GitHub plan. A version-controlled repository can act as a lightweight CSDB, provided you build the validation, reference management, and publication processes around it.
Here is how I would map the approach to MCCF.
- MCCF Common Source Database - Git repository · XML data modules · stable identifiers · version history · dependency references
- User's guide - Installation, configuration, workflows, examples, troubleshooting, artist-oriented tutorials.
- Systems guide - Architecture, components, data contracts, event sequencing, interfaces, deployment, failure modes.
- Publication and validation pipeline - XML and schema validation · cross-reference checks · XSLT publishing · versioned HTML/PDF outputs · automated build checks
The key is that the user's guide and systems guide would be views of shared information, not necessarily two independently maintained bodies of prose.
For example, an interface definition could be authored once and referenced from the systems guide, the installation documentation, and a troubleshooting procedure. When the interface changes, you have a traceable set of documents to review rather than relying on somebody to remember every occurrence.
That is the long-term payoff.
What I would adopt—and what I would leave on the shelf
'd establish a deliberately small MCCF business-rules profile rather than attempt wholesale S1000D conformance.
Adopt now | Defer until needed |
|---|---|
XML data modules and schemas | Full industrial CSDB tooling |
Stable data-module identifiers | Complex applicability matrices |
Explicit module types and status | Elaborate approval workflows |
Publication modules for guide assembly | Specialized delivery packaging |
Cross-reference and dependency checks | Formal enterprise change boards |
XML/XSLT publication pipeline | Every optional S1000D information type |
I'd also choose the S1000D issue and XML schema set deliberately, pin the version, and document any project-specific deviations. The official distribution includes schemas, business-rule templates, a data dictionary, and sample datasets; these provide a concrete starting point.
One caution: S1000D is a specification, not a turnkey CSDB application. Git supplies revision control, but it doesn't automatically provide semantic reference integrity, publication assembly, or conformance checking. Those are responsibilities of your build process.
The most important MCCF-specific distinction
I'd keep three kinds of information separate, even when they reference one another.
Normative documentation: what MCCF is supposed to do, its supported interfaces, constraints, and expected behavior.
Implementation documentation: how the current code actually does it, including dependencies, deployment assumptions, and known limitations.
Verification evidence: what has been tested, under which conditions, with what results.
This is especially important given your stated priority of establishing whether MCCF can be run reliably by other people, particularly on a network host versus a local host.
A manual saying that a function works is not evidence that it works under every supported deployment. A systems guide describing an intended interface is not proof that the implementation conforms to it. And a passing test on your machine is not proof of reproducibility elsewhere.
I'd make those distinctions explicit in the documentation metadata and review process. That gives you a basis for tracing requirements to implementation and tests without turning the manuals into a promise the software cannot yet keep.
The Web of Worlds argument
This is where I think your proposal becomes more than documentation engineering.
If MCCF is going to participate in a Web of Worlds, its documentation should be consumable by both people and tools. Stable identifiers, modular XML, explicit interface contracts, versioned vocabularies, and machine-checkable constraints give you a foundation for that.
A world owner, an asset generator, an editor, or a future agent should be able to discover what a component expects and what it promises without reverse-engineering an entire application.
But I would maintain one firm boundary: don't make the documentation schema into the MCCF runtime schema merely because both describe the same system. They serve different purposes. Link them through stable identifiers and explicit mappings; don't force one to carry the other's responsibilities.
That is consistent with your preference for declarative XML, namespaces, and transformations rather than an ever-growing collection of ad hoc conventions.
My recommendation
Start with a small, complete vertical slice:
One descriptive module for MCCF's architecture.
One procedural module for installation and running a working example.
One interface module describing an actual MCCF contract.
One publication module assembling those into useful guide sections.
One automated build that validates the XML, checks references, and produces readable output.
Then ask someone unfamiliar with the implementation to use those documents to install MCCF and reproduce a known result. The gaps they encounter will tell you more about the right level of documentation rigor than a lengthy theoretical debate about overkill.
If that works, grow the CSDB incrementally.
My bottom line: S1000D is not overkill if you're using it to establish a durable information architecture. It becomes overkill if maintaining the documentation machinery starts consuming the effort that should go into making MCCF useful.
You are building something intended to outlive its first implementation and to collaborate with systems you don't control. A disciplined, versioned, machine-readable documentation base is a reasonable investment in that ambition. I'd just make sure the first release proves the value before you build the cathedral around it.
Len: Agree on all points. Except markdown. It is a terrible godawful design for long lifecycles, the ultimate lobster trap.
Your objection is deeper than syntax. Markdown makes it easy to start writing, but its informal semantics, implementation-specific extensions, and uneven treatment of structure can make a mature documentation corpus difficult to migrate, validate, or transform reliably. The more a project depends on embedded HTML, renderer conventions, and dialect-specific behavior, the tighter the trap closes.
For MCCF, I'd make the distinction explicit:
XML is the source of record. Typed, namespaced, schema-validatable, and structurally explicit.
S1000D supplies the documentation architecture. Modular information, identification, reuse, status, and publication assembly.
XSLT supplies the transformations. HTML for browser consumption, PDF for distribution, and potentially other representations without making them authoritative.
Git supplies history and collaboration. Diffs, branches, review, tags, and releases.
Automated validation supplies discipline. Schema checks, reference integrity, publication builds, and eventually tests that verify documented behavior.
And I'd keep the source vocabulary deliberately small. XML can become its own lobster trap if every author invents new elements, namespaces, and processing conventions. A constrained, documented profile is more valuable than an enormous vocabulary used inconsistently.
There's also a particularly nice architectural symmetry here: MCCF describes and coordinates a world of interacting components; its documentation describes and coordinates a world of interacting information modules. Both benefit from explicit contracts and traceable relationships.
The ultimate test is not whether the source looks pleasant in a text editor. It's whether you can still process, validate, transform, and understand it twenty years later, using tools that nobody has invented yet.
Markdown is a convenient authoring surface. XML is a defensible archival and interchange format. For a project whose ambitions include longevity and interoperability, I know which foundation I'd choose.
Least commitment doesn't mean choosing the smallest technology. It means postponing decisions that don't yet need to be made.
SGML gave us a powerful foundation for descriptive markup. HyTime attempted to provide a general framework for addressing time, space, synchronization, and complex interrelationships. Much of that ambition was intellectually sound. But the cost of the generality, the specialized knowledge required, and the number of things implementers had to understand could exceed the immediate value. The future arrived with a substantial entry fee.
Your S1000D argument is different.
You inherit a mature document architecture rather than inventing one.
You select capabilities incrementally rather than implementing an entire standard.
You retain an established integration vocabulary should MCCF enter industrial environments.
You defer unnecessary commitments while preserving a path to greater rigor as requirements emerge.
That last point is the important one. You're not predicting every future MCCF use case. You're choosing a foundation that leaves those possibilities open without requiring you to implement them today.
The architectural principle
I'd express your approach as three rules:
Adopt established conventions where they solve an actual problem.
Extend only when a demonstrated requirement cannot be met adequately without an extension.
Keep project-specific decisions reversible wherever practical.
That applies to the documentation as much as to MCCF itself. Start with the S1000D constructs you need for modular content, identification, reuse, and publication. Don't adopt an elaborate business-rules regime, applicability machinery, or enterprise workflow merely because the standard accommodates it.
And don't confuse conformance with usefulness. A small, internally consistent implementation of the relevant conventions is more valuable than an ambitious implementation that nobody can maintain.
Why the industrial path matters
There is a strategic benefit here, too. If MCCF eventually finds its way into industrial applications, the documentation architecture won't be an entirely bespoke artifact that prospective adopters must first learn and then translate into their own practices.
S1000D won't guarantee adoption or interoperability by itself. Integration will still depend on the actual schemas, tooling, metadata, interfaces, and organizational requirements. But it gives you a recognized starting point rather than another proprietary documentation framework to defend.
That is a good trade: modest additional discipline now, potentially less integration friction later.
And it fits the broader philosophy we've been discussing. You don't need to predict which designated winner will dominate the future. You need to avoid making MCCF dependent on that winner.
Build the minimum necessary structure, preserve the maximum practical freedom, and let demonstrated needs earn additional complexity.
That's not underengineering. It's disciplined restraint.
Comments
Post a Comment