Doc-as-code workflow

Treating documentation as code means applying software engineering practices — version control, branching, review gates, and automated quality checks — to the authoring and delivery of documentation. This page explains how that works in practice.

What doc-as-code means in practice

"Docs-as-code" covers a spectrum, from storing markdown in a Git repository at one end to full CI/CD validation, automated link checking, and programmatic generation from OpenAPI specs at the other. The relevant question is not "are we doing docs-as-code?" but "which docs-as-code practices solve the problems we actually have?"

Practice	Problem it solves	Applied in this portfolio
Source control (Git)	Change history, rollback, concurrent authoring without conflicts	Yes — every project lives in a public GitHub repository
Branching strategy	Parallel work, safe drafts, isolated review cycles	Yes — feature branches per project or major change, merged via pull request
Pull request review	Catches errors before publication, creates an audit trail of content decisions	Yes — PR descriptions document the scope, audience, and IA decisions for each change
Static delivery (GitHub Pages)	No server to maintain, no CMS login, fast global delivery, offline-capable	Yes — all projects deployed to GitHub Pages from the `main` branch
Automated linting (Vale)	Enforces style guide rules at the authoring stage, before review	Configured in adjacent projects; demonstrable on demand
Link validation	Prevents broken links from reaching production	GitHub Actions workflow for link checking on pull requests

Toolchain decisions

Every toolchain decision involves tradeoffs. The choices made for this portfolio are documented here with their rationale, not because they are universally correct, but because the reasoning is reproducible in any documentation project.

Plain HTML + CSS over Markdown + static site generator

The most frequently asked question about this portfolio is: why not use a static site generator (MkDocs, Docusaurus, Jekyll) and write in Markdown?

Short answer

Portability, transparency, and full design control. A plain HTML file opens in any browser, works offline, requires no build step, has no dependency tree to rot, and can be reviewed by any stakeholder without installing a tool. This is maximally useful for a portfolio that needs to be readable anywhere.

The longer answer involves three specific tradeoffs:

Portability vs. authoring efficiency

Markdown is faster to write. HTML with full CSS is faster to read and more portable. For a portfolio, the reader experience is the higher priority. The authoring overhead is a one-time cost; the reader experience is permanent.

Control vs. convention

Static site generators impose conventions: directory structures, front matter schemas, theme constraints. Plain HTML has no conventions. Every design decision is explicit and visible in the CSS. This makes the codebase easier to understand and modify, at the cost of having to make (and document) every decision.

Dark mode implementation

CSS custom properties with a data-theme attribute on <html> provides full dark/light mode without JavaScript frameworks, build steps, or CSS-in-JS. An inline <script> in <head> sets the attribute before the browser paints, preventing the flash of wrong theme (FOUC).

No runtime dependencies

The JavaScript in this portfolio uses only the Clipboard API, localStorage, and standard DOM methods. No React, no Vue, no bundler, no package.json. The pages load in under 200ms on a cold cache because there is nothing to download except the fonts.

Why not MadCap Flare for this portfolio?

MadCap Flare is the primary authoring tool for enterprise documentation projects (it is used in the MadCap Flare source repo referenced in this portfolio). It is not used here because:

Flare projects require a Flare installation to author and build — this removes the accessibility advantage of plain HTML
Flare's output is optimized for enterprise documentation portals, not GitHub Pages hosting
For a portfolio, showing proficiency in building docs tooling (not just using it) is more demonstrative of skills

Branch strategy for documentation

Documentation branching strategy differs slightly from software feature branching because documentation changes are usually tied to product releases, not deployable independently of the product they document.

Strategy used for this portfolio

# main — production-ready, always deployable to GitHub Pages
main
  └─ feature/phase-6-sdk-docs     # full phase development
  └─ fix/error-table-http-codes   # targeted corrections
  └─ update/changelog-v2-1-0      # scheduled content updates

Each branch maps to a single logical unit of work. Pull request descriptions include the following structured metadata:

Field	Content
What changed	Files added or modified, and the type of change (new page, edit, fix)
Audience	Who this change is for and why they need it
IA decision	Where this content lives in the documentation hierarchy and why
Review checklist	MSTP compliance, code example accuracy, link validity, heading hierarchy, accessibility
Source of truth	The API spec, product spec, or SME that validates the technical accuracy

Branch strategy in production environments

In a product team, documentation branching strategy aligns with the release train. The pattern below applies to teams that use feature-branch development:

main                 # live docs, mirrors production
  └─ release/v3.2    # docs for upcoming release, merges on release day
  └─ docs/feature-x  # feature docs developed in parallel with eng feature branch
  └─ hotfix/typo-fix # urgent corrections, fast-tracked review

Common failure mode: docs on a separate branch from code

Documentation committed to a separate docs branch that is never merged into main creates a permanent de-sync between the docs and the product. Documentation must track the same main branch as the code it describes.

Review and quality process

Documentation review is not the same as code review. A code reviewer validates correctness and performance. A documentation reviewer validates accuracy, clarity, completeness, and style. These require different reviewers and different checklists.

Review types

Review type	Reviewer	What they check
Technical accuracy	Subject-matter expert (engineer, PM, or product owner)	Code examples work, parameter names are correct, error codes match implementation, process descriptions are accurate
Style and MSTP compliance	Senior technical writer or editor	Active voice, second person, no minimizers, sentence-case headings, present tense, consistent terminology
Completeness	Documentation lead or IA owner	All prerequisite steps covered, error states documented, examples testable, navigation updated
Peer technical writing	Another technical writer	Reader perspective — does this make sense without insider knowledge? Is anything assumed that should be stated?

Automated quality checks with Vale

Vale is a prose linter that enforces style rules defined in a configuration file. For MSTP compliance, the configuration checks:

# .vale.ini — MSTP style enforcement
StylesPath = styles
MinAlertLevel = warning

[*.md]
BasedOnStyles = Microsoft

# Custom rules added on top of the Microsoft style:
# - Flags passive voice constructions
# - Flags minimizer words (simply, just, easy, straightforward)
# - Flags future tense in procedural content
# - Flags title-case headings

Vale runs as a pre-commit hook (blocks non-compliant commits locally) and as a GitHub Actions check on pull requests (blocks merge if there are errors). Warning-level violations are reviewed manually; error-level violations block merge.

Delivery pipeline

Every project in this portfolio follows the same deployment path from authoring to live publication.

Author on a feature branch

Write content on a named feature branch isolated from main. This allows work in progress to exist in the repository without affecting the live published documentation.
Run automated checks locally

Vale linting catches style violations before the pull request is opened, reducing the reviewer's burden. HTML link checkers catch broken internal links.
Open a pull request with structured metadata

Pull request description documents the change scope, audience, IA rationale, and review checklist items. This makes reviews faster and creates a searchable history of content decisions.
Automated CI checks run on the PR

GitHub Actions runs: Vale style linting, HTML link validation, and accessibility checks. Failures block merge, preventing broken or non-compliant content from reaching the live site.
Technical accuracy review by SME

The appropriate subject-matter expert signs off on technical accuracy. Their approval is documented in the PR review history.
Merge to main — GitHub Pages deploys automatically

Merging to main triggers the GitHub Pages build, publishing the updated documentation within 30–90 seconds. No manual deployment step, no FTP, no staging server.

The single-command deployment advantage

git push origin main is the entire deployment command. Documentation updates reach readers in under two minutes from merge. Rollback is git revert. This is the core operational benefit of docs-as-code over CMS-based documentation systems.

When docs-as-code is not the right approach

Docs-as-code is well-suited to developer-facing documentation maintained by people who are comfortable with Git. It is less well-suited to:

Enterprise compliance documentation with non-technical authors. If the primary authors are compliance officers, lawyers, or business analysts who do not use Git, the workflow overhead will be rejected. A CMS (Confluence, SharePoint) or purpose-built regulatory documentation tool is more appropriate.
High-volume translation workflows. CMS platforms with built-in translation memory and connector APIs to professional translation services are more efficient than handling translated content as separate file sets in Git.
Documentation with complex single-sourcing requirements. Products with many variants (10+ product configurations, region-specific editions, OEM white-labelling) benefit from structured authoring tools like MadCap Flare or DITA that have conditional publication built in.

The best documentation toolchain is the one the team will actually use consistently. Optimising for workflow adoption over technical elegance is the correct priority.