Technical Writing and Documentation 101: Markdown and AsciiDoc Fundamentals

Markdown and AsciiDoc Fundamentals

Markdown and AsciiDoc Fundamentals: A Practical Study Guide

For aspiring technical writers, developers transitioning into writing, and current writers modernizing their skills

What This Is

Markdown and AsciiDoc are lightweight markup languages that let you write formatted text in plain text files—no clunky word processors required. They’re the backbone of docs-as-code workflows, where documentation lives alongside code in Git repos, gets reviewed via pull requests, and is published via static site generators (like Hugo, Docusaurus, or Antora). For example, Stripe’s API docs (a gold standard in tech writing) are written in Markdown and built with a custom static site generator. Mastering these tools means you can write faster, collaborate with engineers seamlessly, and publish beautiful, version-controlled docs.

Key Terms & Tools

• Markdown (CommonMark, GitHub Flavored Markdown - GFM):
  A plain-text syntax for formatting (e.g., # Headings, bold, - lists). Used in GitHub READMEs, Slack, and most static site generators. Tools: VS Code (with Markdown preview), Typora, Obsidian.

• AsciiDoc:
  A more powerful alternative to Markdown with built-in features like tables of contents, cross-references, and conditional content. Often used for complex docs (e.g., Kubernetes, Fedora). Tools: Asciidoctor, Antora, IntelliJ AsciiDoc plugin.

• Docs-as-Code:
  Treating docs like code: stored in Git, written in Markdown/AsciiDoc, built with static site generators, and reviewed via PRs. Example: Google’s developer docs use this workflow.

• Static Site Generator (SSG):
  A tool that converts Markdown/AsciiDoc files into HTML websites. Examples: Hugo (Markdown), Docusaurus (Markdown), Antora (AsciiDoc).

• Front Matter:
  Metadata at the top of a Markdown/AsciiDoc file (e.g., title:, author:, date:) in YAML, TOML, or JSON. Used by SSGs to generate pages. Example: ```yaml

title: "Payment API Reference" sidebar_label: "Payments"

```

• Code Blocks:
  Formatted snippets in docs (e.g., ```python for Python). In AsciiDoc, you can add callouts (<1>) for annotations. Example: markdownbash curl -X POST https://api.example.com/payments \
  -H "Authorization: Bearer $TOKEN"

• Cross-References:
  Links to other sections/files. Markdown uses [text](#heading-id), while AsciiDoc uses <<section-id>>. Example: asciidoc See <<authentication>> for details.

• Conditional Content:
  Showing/hiding content based on variables (e.g., ifdef::env-github[]). AsciiDoc supports this natively; Markdown requires SSG plugins.

• OpenAPI (Swagger):
  A spec for describing REST APIs. Tools like Swagger UI or Redoc auto-generate interactive docs from YAML/JSON files. Example: Stripe’s API reference uses OpenAPI + Markdown.

• Mermaid:
  A Markdown extension for diagrams (e.g., flowcharts, sequence diagrams). Example: markdownmermaid graph TD;
  A-->B;
  A-->C;

• Linting:
  Automated checks for syntax errors, style violations, or broken links. Tools: markdownlint, vale (for prose), textlint.

• Versioning:
  Managing docs for multiple product versions (e.g., v1, v2). AsciiDoc + Antora handles this natively; Markdown requires SSG plugins (e.g., Docusaurus versioning).

Step-by-Step / Process Flow

How to write and publish docs in Markdown/AsciiDoc:

1. Set Up Your Workspace
2. Install a text editor (VS Code, IntelliJ) with Markdown/AsciiDoc plugins.
3. Clone the docs repo (e.g., git clone https://github.com/company/docs.git).

4. Install dependencies (e.g., npm install for Docusaurus, gem install asciidoctor for AsciiDoc).

5. Write the Content

6. Start with a template (e.g., template.md or template.adoc in the repo).
7. Use front matter for metadata (title, description, sidebar position).
8. Structure content with headings (#, ##), lists (-), and code blocks.

9. Example (Markdown):
   markdown
---
title: "Getting Started"
---
# Getting Started with Acme API
To authenticate, send a `POST` request to `/auth` with your API key.bash
   curl -X POST https://api.acme.com/auth \
   -H "Authorization: Bearer YOUR_API_KEY"
   

10. Add Diagrams and Media

11. For Markdown: Use Mermaid for diagrams or embed images (![alt text](path/to/image.png)).

12. For AsciiDoc: Use image::path/to/image.png[] or ASCII art for simple diagrams.

13. Preview Locally

14. Run the SSG’s dev server (e.g., npm run start for Docusaurus, asciidoctor -D output/ file.adoc for AsciiDoc).

15. Check for rendering issues (e.g., broken links, missing images).

16. Submit for Review

17. Commit changes (git add ., git commit -m "Add getting started guide").
18. Push to a feature branch (git push origin add-getting-started).

19. Open a PR and request reviews from engineers and other writers.

20. Publish

21. Merge the PR (triggers a CI/CD pipeline, e.g., GitHub Actions, Netlify).
22. Verify the live site (e.g., https://docs.company.com).

Common Mistakes

• Mistake: Using HTML in Markdown for complex layouts (e.g., <div> for columns).
  Correction: Stick to Markdown/AsciiDoc syntax. For complex layouts, use an SSG component (e.g., Docusaurus’s <Grid>) or switch to AsciiDoc, which supports tables, admonitions (NOTE:, WARNING:), and more natively.

• Mistake: Hardcoding version numbers in docs (e.g., “This feature is available in v2.3.1”).
  Correction: Use variables (e.g., {version} in AsciiDoc) or SSG versioning features. Why: Hardcoded versions become outdated fast.

• Mistake: Ignoring linting (e.g., inconsistent heading levels, trailing spaces).
  Correction: Set up markdownlint or textlint in your editor or CI pipeline. Why: Linting catches errors before PRs and enforces consistency.

• Mistake: Writing long paragraphs without visual breaks (e.g., walls of text).
  Correction: Use lists, code blocks, and admonitions (> NOTE:) to improve scannability. Why: Developers skim docs; dense text frustrates them.

• Mistake: Not testing code examples.
  Correction: Run every code snippet in a sandbox (e.g., Postman for APIs, a REPL for CLI tools). Why: Broken examples erode trust in your docs.

Tech Writing Interview / Portfolio Tips

• Show, Don’t Tell:
  Hiring managers want to see real docs you’ve written. Include:
• A Markdown/AsciiDoc file (e.g., a README, API guide, or tutorial).
• A PR with doc changes (shows collaboration with engineers).

• A published doc (e.g., a GitHub Pages site or Netlify demo).

• Know the Distinctions:

• Conceptual doc (e.g., “How OAuth Works”) vs. tutorial (e.g., “Build a Login System with OAuth”).
• Reference (e.g., API endpoint list) vs. guide (e.g., “Migrate from v1 to v2”).

• Swagger UI (interactive API explorer) vs. Redoc (static, beautiful API docs).

• Talk About Workflows:
  Be ready to explain:

• How you’d sync docs with code (e.g., “I’d add a pre-commit hook to run markdownlint”).
• How you’d handle versioning (e.g., “I’d use Docusaurus’s versioning feature or Antora for AsciiDoc”).

• How you’d measure doc quality (e.g., “I’d track page views, time on page, and support tickets related to docs”).

• Tool-Specific Tips:

• For Markdown: Know how to use extensions (e.g., markdown-it plugins for tables, footnotes).
• For AsciiDoc: Highlight features like conditional content (ifdef::[]) and cross-references (<<>>).
• For OpenAPI: Explain how you’d generate docs from a YAML spec (e.g., “I’d use swagger-codegen to create a Markdown template”).

Quick Check Questions

1. Scenario: A developer complains that the API docs are outdated. How would you ensure docs stay in sync with code?
   Answer: Use docs-as-code with automated checks:
2. Add a pre-commit hook to lint docs and run tests (e.g., markdownlint).
3. Set up CI/CD to rebuild docs on every code merge (e.g., GitHub Actions).

4. Use OpenAPI to auto-generate API docs from the spec (ensures accuracy).
   Why: Automation reduces manual updates and catches drift early.

5. Scenario: You’re writing a tutorial in Markdown. How do you decide whether to use a numbered list vs. a code block for steps?
   Answer: Use a numbered list for high-level steps (e.g., “1. Install the CLI”) and a code block for commands or code snippets (e.g., npm install -g acme-cli). Why: Lists are scannable; code blocks preserve formatting (e.g., line breaks, syntax highlighting).

6. Scenario: Your team wants to add a warning box to a guide. How would you implement this in Markdown vs. AsciiDoc?
   Answer:

7. Markdown: Use blockquotes (> WARNING:) or an HTML <div> (less ideal).
8. AsciiDoc: Use built-in admonitions (WARNING: This will delete your data!).
   Why: AsciiDoc’s syntax is cleaner and more semantic.

Last-Minute Cram Sheet

1. Markdown: # Heading, bold, - list, `code`, [link](url).
2. AsciiDoc: = Heading, *bold*, - list, `code`, <<xref>>.
3. Front Matter: YAML/TOML at the top of a file (e.g., title: "Guide").
4. Code Blocks: ```language in Markdown; [source,language] in AsciiDoc.
5. Cross-References: [text](#id) (Markdown) vs. <<id>> (AsciiDoc).
6. Conditional Content: ifdef::[] (AsciiDoc only).
7. Tables: | Syntax | Description | (Markdown) vs. |=== (AsciiDoc).
8. Admonitions: > NOTE: (Markdown) vs. NOTE: (AsciiDoc).
9. Mermaid: ```mermaid for diagrams in Markdown.
10. ⚠️ Trap: “A tutorial teaches concepts by building (e.g., ‘Build a To-Do App’); a how-to guide solves a specific problem (e.g., ‘Reset Your Password’).”