Technical Writing and Documentation 101: Docs‑as‑Code (Git, CI/CD, Static Site Generators like Docusaurus, MkDocs, Hugo)

Docs‑as‑Code (Git, CI/CD, Static Site Generators like Docusaurus, MkDocs, Hugo)

Docs-as-Code: A Practical Study Guide for Modern Technical Writers

What This Is

Docs-as-Code is a workflow where documentation is treated like software code—stored in Git, written in Markdown or AsciiDoc, built with static site generators (SSGs), and deployed via CI/CD pipelines. This approach ensures docs stay in sync with code, enables collaboration via pull requests (PRs), and automates publishing.

Real-world example:
A payment gateway API reference (e.g., Stripe’s docs) is written in Markdown, version-controlled in Git, and auto-generated from OpenAPI specs. When engineers update the API, the docs rebuild automatically, ensuring accuracy.

Key Terms & Tools

• Docs-as-Code: Treating documentation like source code—stored in Git, reviewed via PRs, and built with static site generators.
• Static Site Generator (SSG): A tool that converts Markdown/AsciiDoc into HTML (e.g., Docusaurus, MkDocs, Hugo, Next.js).
• Git: Version control system for tracking changes in docs (and code). Key commands: git clone, git commit, git push, git pull.
• GitHub/GitLab/Bitbucket: Platforms for hosting Git repos, managing PRs, and running CI/CD pipelines.
• Markdown (.md): Lightweight markup language for writing docs (e.g., # Heading, bold, [link](url)).
• AsciiDoc (.adoc): A more powerful alternative to Markdown (supports tables, cross-references, conditional content).
• OpenAPI (Swagger): A spec for describing REST APIs, enabling auto-generated docs (e.g., Swagger UI, ReDoc, Stoplight).
• CI/CD (Continuous Integration/Deployment): Automated pipelines that test and deploy docs (e.g., GitHub Actions, GitLab CI, CircleCI).
• Pull Request (PR): A proposed change to docs (or code) that must be reviewed before merging.
• Linter: A tool that checks docs for style/grammar errors (e.g., Vale, Markdownlint, textlint).
• Preview Deployments: Temporary live previews of docs changes (e.g., Netlify, Vercel, GitHub Pages).
• Docs-as-Code Toolchain: The full stack (Git + SSG + CI/CD + Linter + Preview).

Step-by-Step / Process Flow

1. Set Up the Docs Repository

• Action: Clone the docs repo (or create one if starting fresh).
  bash git clone https://github.com/your-org/docs.git cd docs
• Tool Tip: Use a .gitignore file to exclude build artifacts (e.g., node_modules/, build/).

2. Write in Markdown/AsciiDoc

• Action: Draft content in .md or .adoc files.
  ```markdown # Getting Started with Acme API

## Authentication Use an API key in the Authorization header: bash curl -H "Authorization: Bearer YOUR_API_KEY" https://api.acme.com/v1/users ``` - Tool Tip: Use VS Code with extensions like Markdown All in One or AsciiDoc Preview.

3. Test Locally

• Action: Run the SSG locally to preview changes.
• Docusaurus:
  bash
npm install
npm start
• MkDocs:
  bash
pip install mkdocs
mkdocs serve
• Tool Tip: Check for broken links with mkdocs serve --strict (MkDocs) or npm run build (Docusaurus).

4. Submit a Pull Request (PR)

• Action: Commit changes and open a PR for review.
  bash git add .
git commit -m "Add authentication section to API docs" git push origin main
• Tool Tip: Use GitHub’s "Squash and Merge" to keep a clean commit history.

5. Automate with CI/CD

• Action: Configure a CI pipeline (e.g., GitHub Actions) to:
• Lint docs (e.g., Vale for style).
• Build and deploy on merge.
• Generate a preview for PRs.
• Example GitHub Actions Workflow (.github/workflows/deploy.yml):
  yaml name: Deploy Docs on:
push:
branches: [ main ] jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install
- run: npm run build
- run: npm run deploy

6. Monitor and Update

• Action: Use GitHub Issues or Jira to track doc bugs.
• Tool Tip: Set up Dependabot to auto-update dependencies (e.g., Docusaurus, MkDocs plugins).

Common Mistakes

Mistake 1: Treating Docs Like a Wiki (Not Code)

• Problem: Editing docs directly in a CMS (e.g., Confluence) instead of Git.
• Correction: Store docs in Git to enable versioning, PRs, and CI/CD. Why? Wikis lack automation and review workflows.

Mistake 2: Ignoring CI/CD for Docs

• Problem: Manually building and deploying docs.
• Correction: Use CI/CD to auto-deploy on merge. Why? Manual deploys lead to outdated docs and human error.

Mistake 3: Writing in Word/Google Docs

• Problem: Drafting docs in Word/Google Docs before moving to Markdown.
• Correction: Write directly in Markdown/AsciiDoc. Why? Converting formats wastes time and introduces errors.

Mistake 4: Not Using Preview Deployments

• Problem: Reviewing docs only in local previews.
• Correction: Use Netlify/Vercel for PR previews. Why? Stakeholders can review changes without running the SSG locally.

Mistake 5: Overcomplicating the Toolchain

• Problem: Using 10 tools when 3 would suffice (e.g., Git + MkDocs + GitHub Actions).
• Correction: Start simple, then add tools as needed. Why? Complexity slows down contributors.

Tech Writing Interview / Portfolio Tips

1. Showcase a Docs-as-Code Project

• What to Include:
• A GitHub repo with Markdown docs, CI/CD workflows, and PRs.
• A live demo (e.g., GitHub Pages, Netlify).
• Before/after screenshots of improvements (e.g., "Added OpenAPI spec → auto-generated API docs").
• Example Portfolio Project:

  "I migrated Acme’s API docs from Confluence to a Docusaurus site with GitHub Actions. Reduced deployment time from 30 minutes to 2 minutes and cut doc bugs by 40%."

  
  

2. Explain the "Why" Behind Tools

• Tricky Distinction: Swagger UI vs. ReDoc
• Swagger UI: Interactive, good for testing APIs.
• ReDoc: Cleaner UI, better for reference docs.
• Interview Answer:
  > "I’d use Swagger UI for internal teams who need to test endpoints, but ReDoc for public-facing docs because it’s more readable."

3. Differentiate Doc Types

• Conceptual Doc vs. Tutorial vs. How-To Guide
• Conceptual: Explains what (e.g., "What is OAuth?").
• Tutorial: Teaches how by building (e.g., "Build a Payment App with Stripe").
• How-To Guide: Solves a specific problem (e.g., "How to Refund a Payment").
• Interview Answer:
  > "A tutorial is hands-on and opinionated (e.g., ‘Follow these steps to build X’), while a how-to guide is flexible (e.g., ‘Here are 3 ways to solve Y’)."

4. Highlight Collaboration

• What Hiring Managers Look For:
• Experience with PR reviews (e.g., "I reviewed 50+ PRs for docs accuracy").
• Developer empathy (e.g., "I paired with engineers to test API endpoints before documenting them").
• Metrics (e.g., "Reduced doc-related support tickets by 25%").

Quick Check Questions

1. A developer complains that the API docs are outdated. How would you ensure docs stay in sync with code?

Answer:
Use OpenAPI specs and CI/CD to auto-generate docs from code. Set up a pre-commit hook or GitHub Action to validate docs against the spec.
Why? Auto-generation reduces manual updates and human error.

2. Your team wants to migrate from a CMS to Docs-as-Code. What’s the first step?

Answer:
Audit the existing docs and choose a static site generator (SSG) (e.g., Docusaurus for React-based docs, MkDocs for simplicity). Set up a Git repo and CI/CD pipeline for the new workflow.
Why? The SSG determines the toolchain (e.g., Docusaurus needs Node.js, MkDocs needs Python).

3. A PR adds a new feature but no docs. How do you enforce doc updates?

Answer:
Add a required status check in GitHub/GitLab that blocks merges if docs are missing. Use a template for PRs that includes a "Docs Updated?" checkbox.
Why? Automated checks ensure docs are treated as part of the feature.

Last-Minute Cram Sheet

1. Docs-as-Code = Git + SSG + CI/CD + Markdown/AsciiDoc.
2. Docusaurus = React-based, great for SPAs. MkDocs = Python-based, simpler.
3. OpenAPI 3.0 vs. 2.0: 3.0 supports callbacks, links, and better examples. ⚠️ Always use 3.0+.
4. Markdown quirks:
5. Fenced code blocks: ```python (not tabs).
6. Links: [text](url) (not <a href="url">text</a>).
7. CI/CD for docs: GitHub Actions > Travis CI (faster, free for public repos).
8. Linters: Vale for style, Markdownlint for syntax.
9. Preview deployments: Netlify/Vercel auto-generate URLs for PRs.
10. ⚠️ A tutorial is not a how-to guide: Tutorials teach concepts by building; how-tos solve specific problems.
11. Git commands:
12. git rebase -i HEAD~3 (squash commits).
13. git stash (temporarily save changes).
14. OpenAPI tools:
    • Swagger UI = interactive.
    • ReDoc = prettier.
    • Stoplight = design-first API docs.