How ceos-org/interoperability-handbook works
What this project is (type + purpose)
This repository is not an application runtime; it’s a documentation product (a handbook) with:
• Source content in Markdown chapters (Introduction.md, Architecture.md, etc.)
• Publishing automation that generates a release PDF (see publishing/generate_pdf.py and .github/workflows/pdf-on-release.yml)
• Quality gates for formatting/spelling/content checks (see .markdownlint.json, .spellcheck.yml, .github/workflows/check-contents.yaml)
How to read the file tree as architecture signals
From the tree:
Content layer (the “product”)
• README.md (entry point + TOC + release link)
• Chapter files: Introduction.md, Framework.md, Vocabulary.md, Architecture.md, Interface.md, Quality.md, Policy.md, Conclusion.md
• images/ (embedded assets like the CEOS logo)
• LICENSE (CC-BY 4.0)
Publishing layer (build system)
• publishing/generate_pdf.py (the build pipeline implementation; likely concatenation, markdown-to-pdf conversion, styling, etc.)
• publishing/readme.md (build instructions/notes for publishing subsystem)
Governance / automation / CI
• .github/workflows/check-contents.yaml (continuous checks: lint/spell/structure)
• .github/workflows/pdf-on-release.yml (release-time workflow: build PDF + attach to GitHub Release)
• .markdownlint.json (markdown style rules)
• .spellcheck.yml + .wordlist.txt (spellchecking config + allowlist)
Distribution (GitHub Releases → PDF download)
This layout mirrors the real lifecycle described in the README (release PDF link) and the presence of CI/CD workflow files.
Concrete components and labels to use (use the actual file names)
• Introduction.md
• Framework.md
• Vocabulary.md
• Architecture.md
• Interface.md
• Quality.md
• Policy.md
• Conclusion.md
• images/
• .github/workflows/check-contents.yaml
• .markdownlint.json
• .spellcheck.yml
• wordlist.txt
• .github/workflows/pdf-on-release.yml
• publishing/generate_pdf.py
• Output: interoperability-handbook.pdf
• GitHub Releases (e.g., v2.0.0)
• Link from README.md to release asset
Clear labels
• Name each workflow by filename and trigger (e.g., “check-contents.yaml (on push/PR)” and “pdf-on-release.yml (on release/tag)”).
• Control/event: “push/PR”, “release/tag”
• Data/artifact: “PDF”, “lint results”, “spellcheck report”
Boundaries
• A big boundary for GitHub (Repo + Actions + Releases)
• Optional boundary for Local dev (contributors editing files before pushing)
Don’t overthink it: “separate into as many components as possible”
For this repository, “more components” mainly means:
• Split content into “chapters” vs “assets”
• Split automation into “checks” vs “release build”
All three can be derived directly from the file tree and README, and together they form the “best and most accurate” architectural representation for a docs/publishing project.