What I Wanted to Demonstrate
I wanted a public project complex enough to demonstrate the way I actually design and maintain documentation systems, without exposing proprietary work.
The result needed to prove three things at once: I can write the documentation, architect the information, and engineer the system that keeps the documentation reliable. It also needed to be inspectable. A reviewer should be able to read the published guidance, inspect the Markdown, trace the build and validation logic, and compare the generated formats with the maintained source.
The Fictional Product
Greenhouse Sentinel is a fictional environmental-monitoring controller. A local hub receives readings from temperature, humidity, and soil sensors, evaluates three consecutive samples against versioned thresholds, and reports a Normal, Watch, or Act state with response guidance.
The hub does not control pumps, vents, heaters, or other physical equipment. That boundary keeps the fictional product understandable while creating realistic material for setup, operation, concepts, state behavior, troubleshooting, safety notes, and contributor guidance.
The Documentation I Designed
The documentation follows the reader from first setup through daily use, explanation, recovery, and contribution. These pages show the technical writing itself—not only the machinery around it:
- Quick Start — a short setup-and-verification procedure with prerequisites, a success state, and a clear next step.
- Daily Operations — task-focused operating guidance organized around routine checks and response decisions.
- Architecture and Decision States — a conceptual explanation of system boundaries, components, state behavior, retention, and failure handling.
- Troubleshooting — symptom-first recovery guidance that preserves diagnostic evidence and links back to the governing concepts.
- Writing Guide — contributor guidance that makes the documentation model maintainable by someone other than its original author.
- Release Checklist — the human review and release controls that surround the automated checks.
Together, the set covers quick start, installation and configuration, operating guidance, troubleshooting, concepts and architecture, alert-state behavior, and contributor documentation.
The Decisions I Made
Organize Around Reader Tasks
The primary path begins with what a reader needs to accomplish: connect the hub, verify the sensors, perform the daily check, interpret a state, and recover from a visible symptom. Architectural explanation supports those tasks without becoming the entry point for every reader.
Separate Content Types Without Isolating Them
Procedures, concepts, troubleshooting, and contributor guidance have different jobs. I separated them so each page has a clear purpose, then used descriptive cross-references to connect the moment of action with the explanation or recovery path a reader may need next.
Use Stable Anchors for Important Destinations
Critical cross-references point to deliberate anchors rather than depending on generated heading fragments. This makes the links resilient when nearby headings change and gives the validator an explicit contract to check.
Maintain One Reviewed Source
The website, Word handbook, and PDF are presentations of the same Markdown source. The maintained record is the reviewed source commit, not three independently edited outputs that must be reconciled later.
Automate Objective Checks and Preserve Human Judgment
Automation checks facts with repeatable answers: whether pages exist, navigation includes the maintained content, links and anchors resolve, the build succeeds, and expected artifacts are produced. People remain responsible for accuracy, reader needs, safety, accessibility judgment, visual quality, and release approval.
The Documentation System
Authors maintain one reviewed set of Markdown files. An explicit navigation configuration defines the publishing order. Automated checks verify the source before Zensical builds the HTML site, a Python exporter creates a styled Word handbook, and LibreOffice converts that handbook to PDF. GitHub Actions repeats the entire sequence from a clean copy of every accepted change and publishes the outputs together.
| Capability | How It Is Implemented | What It Demonstrates |
|---|---|---|
| Single-source authoring | One maintained set of Markdown files under docs/ |
Website, Word, and PDF content can stay synchronized without three competing sources |
| Explicit information architecture | An ordered navigation list in zensical.toml plus checks for omitted pages |
Page order is deliberate, reviewable, and traceable |
| Stable cross-references | Deliberate anchors plus automated file-and-fragment validation | Important links do not silently fail when nearby headings change |
| Automated quality gates | A renderer-independent validator checks navigation, files, links, anchors, headings, and image text | Routine defects are caught before publication and leave objective pass-or-fail evidence |
| Accessible authoring | Semantic Markdown, descriptive links, structured tables, theme overrides, and a release checklist | Accessibility is considered during authoring and review rather than as a late repair |
| Replaceable branding | Purpose-based CSS variables, separate image assets, and publishing configuration outside the source content | A team can change visual identity without rewriting technical meaning |
| Multi-format publishing | Zensical produces HTML, Python produces Word, and headless LibreOffice produces PDF | Different delivery channels can share one reviewed source and release process |
| Self-documentation | The site explains its architecture, authoring process, automation, construction, and release checks | Another writer can inspect, reproduce, explain, or adapt the workflow |
How Authoring and Publishing Work
- An author identifies a reader need and edits the relevant Markdown source.
- Local validation checks navigation, structure, files, links, and stable anchors.
- A local Zensical build lets the author review the content in its published context.
- A pull request records the exact source change and automated results for review.
- After approval, the workflow repeats validation, builds the site, generates Word, converts Word to PDF, checks the expected artifacts, and publishes the accepted version.
The Markdown commit is the maintained record. The website, Word handbook, and PDF are generated presentations of that record.
What Automation Does—and Does Not Do
Automation answers repeatable questions with objective answers: whether every configured page exists, whether maintained pages appear in navigation, whether links and anchors resolve, whether the build succeeds, and whether the expected deliverables were produced.
People remain responsible for technical accuracy, reader needs, useful procedures, accessibility judgment, visual quality, safety, and release approval. The workflow saves reviewer time by moving mechanical checks out of the judgment-heavy part of review.
Why This Demonstration Matters
Greenhouse Sentinel makes both the writing and the documentation engineering visible. A reviewer can assess the finished procedures and explanations, then inspect the source, information architecture, configuration, validation logic, commit history, release workflow, and generated deliverables behind them.
That inspectability is the point. The project does not ask a reviewer to accept invented client constraints or fictional outcomes. It shows an original product created specifically to make my working methods public and verifiable.