Technical Writing and Documentation 101: Organizing Content (Card Sorting, Topic‑based Authoring, DITA)

Organizing Content (Card Sorting, Topic‑based Authoring, DITA)

Study Guide: Organizing Content (Card Sorting, Topic-Based Authoring, DITA)

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

What This Is

Organizing content means structuring documentation so users (developers, admins, end-users) can find, understand, and use information without frustration. Poor organization leads to support tickets, abandoned onboarding, or failed API integrations. For example: - A payment gateway API reference (like Stripe’s) must group endpoints logically (e.g., "Charges," "Refunds," "Webhooks") so developers can quickly locate the right call.
- A cloud service getting-started guide (like AWS EC2) must separate conceptual overviews ("What is an instance?") from step-by-step tasks ("Launch your first instance") to avoid overwhelming beginners.

Good organization reduces cognitive load, speeds up adoption, and turns documentation into a product feature—not an afterthought.

Key Terms & Tools

• Card Sorting: A UX research method where users group topics (written on "cards") to reveal how they expect information to be organized. Tools: OptimalSort, Miro, or physical sticky notes.
• Topic-Based Authoring: Writing content in small, reusable chunks (topics) instead of long, linear documents. Each topic answers one question (e.g., "How do I authenticate?" or "What are rate limits?"). Formats: DITA, Markdown, AsciiDoc.
• DITA (Darwin Information Typing Architecture): An XML-based standard for topic-based authoring. Defines three core topic types:
• Concept: Explains what something is (e.g., "What is OAuth?").
• Task: Explains how to do something (e.g., "Configure OAuth in 3 steps").
• Reference: Provides factual data (e.g., API endpoint parameters, error codes).
  Tools: Oxygen XML Editor, Adobe FrameMaker, DITA-OT (open-source toolkit).
• Information Architecture (IA): The structure and hierarchy of content (e.g., navigation menus, site maps). Tools: Treejack (for testing IA), Lucidchart, Figma.
• Docs-as-Code: Treating docs like code—stored in Git, written in Markdown/AsciiDoc, built with static site generators (e.g., Hugo, Sphinx, Docusaurus), and reviewed via pull requests.
• Single Sourcing: Writing content once and reusing it across multiple outputs (e.g., web docs, PDFs, embedded help). Tools: DITA, MadCap Flare, Sphinx.
• Modular Documentation: Breaking docs into independent, reusable modules (e.g., a "Troubleshooting" topic reused in multiple guides). Enables easier updates and translations.
• OpenAPI (Swagger): A specification for describing REST APIs. Tools like Swagger UI or ReDoc auto-generate interactive docs from OpenAPI files.
• Static Site Generators (SSGs): Tools that convert Markdown/AsciiDoc into HTML websites (e.g., Hugo, Jekyll, Docusaurus). Used in docs-as-code workflows.
• Metadata: Hidden labels (e.g., audience: developer, difficulty: advanced) that help organize and filter content. Tools: DITA, Markdown frontmatter (YAML/TOML).
• Taxonomy: A classification system for content (e.g., tagging topics by product area, user role, or task type). Tools: CMS like Contentful, WordPress, or custom scripts.

Step-by-Step / Process Flow

1. Plan Your Information Architecture (IA)

Action: Conduct card sorting to understand how users group topics.
- For new docs: Run an open card sort (users create their own categories) with 5–10 target users (e.g., developers, admins).
- For existing docs: Run a closed card sort (users sort topics into predefined categories) to validate your IA.
- Tool: Use OptimalSort or Miro for remote sessions. For in-person, use sticky notes.
- Output: A sitemap or navigation hierarchy (e.g., "Get Started → Concepts → How-To Guides → Reference").

Example:
| User Group | Expected Categories | |------------|-----------------------------| | Developers | API Reference, SDKs, Webhooks | | Admins | Installation, Configuration, Troubleshooting |

2. Define Topic Types (DITA or Custom)

Action: Map each topic to a type (Concept/Task/Reference) or your own taxonomy.
- Concept: "What is a webhook?" (Explanation + diagram).
- Task: "Create a webhook in 3 steps" (Numbered steps + screenshots).
- Reference: "Webhook payload schema" (JSON example + parameter tables).
- Tool: Use a spreadsheet or DITA’s <concept>, <task>, <reference> tags.

Example (Markdown):

---
title: "What is a Webhook?"
type: concept
audience: developer
---

Webhooks are HTTP callbacks that notify your app when an event occurs (e.g., a payment succeeds).
Unlike polling, webhooks push data to your server in real time.

3. Write Modular Topics

Action: Draft each topic to stand alone (no cross-references like "as mentioned above").
- Rule: One topic = one purpose. If a topic answers two questions, split it.
- Tool: Write in Markdown/AsciiDoc (for docs-as-code) or DITA XML.
- Tip: Use metadata (frontmatter or DITA attributes) to tag topics by audience, product, or difficulty.

Example (DITA Task Topic):

<task id="create_webhook">
  <title>Create a Webhook</title>
  <taskbody>
    <steps>
      <step><cmd>Go to the Dashboard &gt; Webhooks.</cmd></step>
      <step><cmd>Click <uicontrol>New Webhook</uicontrol>.</cmd></step>
      <step><cmd>Enter your callback URL and select events.</cmd></step>
    </steps>
  </taskbody>
</task>

4. Assemble Topics into Deliverables

Action: Combine topics into guides, tutorials, or reference docs.
- For a tutorial: Sequence topics in a logical order (e.g., "1. Set up → 2. Authenticate → 3. Make your first API call").
- For a reference: Group topics alphabetically or by function (e.g., "Endpoints: Charges, Refunds, Customers").
- Tool: Use a static site generator (e.g., Hugo) or DITA-OT to compile topics into HTML/PDF.

Example (Hugo Frontmatter for a Tutorial):

---
title: "Build a Payment App"
weight: 1
type: tutorial
topics:
  - "set-up-sdk"
  - "authenticate"
  - "create-charge"
---

5. Validate with Users

Action: Test your organization with real users.
- Tree Testing: Use Treejack to see if users can find topics in your navigation.
- Usability Testing: Ask users to complete tasks (e.g., "Find the rate limit for the API") and observe where they get stuck.
- Tool: Hotjar (for heatmaps), UserTesting.com, or guerrilla testing (e.g., Slack polls).

Example Feedback:

"I expected ‘Authentication’ to be under ‘Get Started,’ not ‘API Reference.’"

6. Iterate and Maintain

Action: Update topics and IA based on feedback and product changes.
- Docs-as-Code: Store topics in Git, use PRs for reviews, and automate builds (e.g., GitHub Actions).
- DITA: Use conditional processing to generate different outputs (e.g., "Developer Guide" vs. "Admin Guide").
- Tool: Set up a docs linter (e.g., Vale) to enforce style rules.

Common Mistakes

Tech Writing Interview / Portfolio Tips

What Hiring Managers Look For

1. Can you organize content for different audiences?
2. Show examples of docs tailored to developers (API reference), admins (installation guide), and end-users (UI help).

3. Tricky Distinction: A tutorial teaches concepts by building (e.g., "Build a Slack bot in 10 steps"), while a how-to guide solves a specific problem (e.g., "Fix a 403 error").

4. Do you understand topic-based authoring?

5. Include a DITA or Markdown topic in your portfolio (e.g., a standalone "How to Authenticate" task topic).

6. Tricky Distinction: A reference doc lists facts (e.g., API parameters), while a guide explains how to use them (e.g., "Use pagination to fetch large datasets").

7. Can you work in a docs-as-code workflow?

8. Show a GitHub repo with Markdown docs, PRs, and a CI/CD pipeline (e.g., GitHub Actions building a Hugo site).

9. Tricky Distinction: Swagger UI (interactive API docs) vs. ReDoc (static, prettier docs)—know when to use each.

10. Have you tested your documentation?

11. Describe a time you used card sorting, tree testing, or usability testing to improve docs. Example:
    > "I ran a card sort with 8 developers and discovered they expected ‘Webhooks’ under ‘Integrations,’ not ‘API Reference.’ I updated the IA, reducing support tickets by 30%."

Portfolio Ideas

• Before/After: Show a poorly organized doc (e.g., a wall of text) and your improved version (modular topics + clear IA).
• DITA Example: Include a DITA topic (XML) and its rendered output (HTML/PDF).
• API Docs: Create an OpenAPI spec (YAML) and generate docs with Swagger UI or ReDoc.
• Case Study: Write a 1-pager on how you improved a doc’s organization (e.g., "Reduced onboarding time by 40% with topic-based authoring").

Quick Check Questions

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

Answer: Implement docs-as-code with automated checks: - Store docs in the same repo as the code.
- Use OpenAPI/Swagger to auto-generate API reference docs from code annotations.
- Set up CI/CD (e.g., GitHub Actions) to fail builds if docs don’t match the spec.
- Why: Manual updates are error-prone; automation ensures accuracy.

2. Your team wants to translate docs into 5 languages. How would you structure content to make this easier?

Answer: Use modular, topic-based authoring with: - Standalone topics (no cross-references like "see above").
- Metadata to tag translatable content (e.g., translate: yes).
- DITA or Markdown for easy extraction/reuse.
- Why: Translators work faster with small, context-free chunks.

3. Users can’t find the "Troubleshooting" section in your docs. How would you diagnose and fix this?

Answer: Run a tree test (e.g., Treejack) to see where users expect "Troubleshooting" to live. Common fixes: - Move it to the top-level navigation (not buried under "Advanced").
- Rename it to "Errors & Fixes" if card sorting shows users expect that term.
- Why: IA should match user mental models, not internal product structure.

Last-Minute Cram Sheet

1. Card sorting reveals how users group topics; run it before designing IA.
2. DITA topic types: Concept (what), Task (how), Reference (data).
3. Docs-as-code = Git + Markdown/AsciiDoc + static site generator (e.g., Hugo).
4. OpenAPI (Swagger) describes APIs; use Swagger UI for interactive docs, ReDoc for static.
5. Metadata (e.g., audience: developer) enables filtering and personalization.
6. Modular docs = write once, reuse everywhere (e.g., a "Troubleshooting" topic in multiple guides).
7. Tree testing validates IA; use Treejack or Optimal Workshop.
8. ⚠️ Tutorial ≠ How-to guide: Tutorials teach concepts by building; how-tos solve specific problems.
9. Static site generators: Hugo (fast), Jekyll (GitHub Pages), Docusaurus (React-based).
10. DITA-OT = open-source toolkit to compile DITA into HTML/PDF.