Technical Writing and Documentation 101: Content Management Systems (Confluence, MadCap Flare, Paligo)

Content Management Systems (Confluence, MadCap Flare, Paligo)

Study Guide: Content Management Systems (Confluence, MadCap Flare, Paligo)

A practical, portfolio-ready guide for technical writers, developers transitioning into writing, and professionals modernizing their skills.

What This Is

A Content Management System (CMS) is a software platform that helps technical writers create, organize, publish, and maintain documentation at scale. Unlike static docs (e.g., Markdown files in Git), a CMS provides structured authoring, version control, collaboration tools, and publishing workflows—critical for teams producing large volumes of docs (e.g., API references, user manuals, or internal knowledge bases).

Real-world example:
A SaaS company uses Confluence to document internal processes (e.g., onboarding checklists, incident response playbooks) while publishing customer-facing API docs in MadCap Flare (for PDF/HTML5 output) and Paligo (for XML-based single-sourcing). Without a CMS, teams would waste time manually updating files, risking inconsistencies and broken links.

Key Terms & Tools

• Confluence (Atlassian):
  A wiki-style CMS for collaborative documentation, often used for internal docs, project tracking, and knowledge bases. Supports macros (e.g., Jira integration, Gliffy diagrams), but lacks native single-sourcing for complex outputs.

• MadCap Flare:
  A desktop-based authoring tool for technical writers, supporting single-sourcing (write once, publish to PDF, HTML5, Word, etc.), conditional content (e.g., "show this section only for Enterprise users"), and topic-based authoring. Uses XML under the hood but hides complexity with a WYSIWYG editor.

• Paligo:
  A cloud-based XML CMS built on DITA (Darwin Information Typing Architecture), enabling structured authoring, content reuse, and multi-channel publishing (e.g., web, mobile, embedded help). Ideal for regulated industries (e.g., medical devices, aerospace) where compliance and versioning are critical.

• Single-Sourcing:
  Writing content once and reusing it across multiple outputs (e.g., a "Troubleshooting" topic appears in a PDF manual, web help, and an embedded UI tooltip). Tools like Flare and Paligo excel here; Confluence requires workarounds (e.g., Excerpt Include macros).

• DITA (Darwin Information Typing Architecture):
  An XML standard for technical documentation, breaking content into topics (concept, task, reference) for modular reuse. Paligo and Oxygen XML Editor support DITA; Flare uses a proprietary XML schema.

• Conditional Text:
  Content that appears only for specific audiences (e.g., "Admin-only" steps, "Linux vs. Windows" instructions). Flare and Paligo support this via tags or variables; Confluence uses user macros or page restrictions.

• Versioning & Branching:
  Managing multiple versions of docs (e.g., v1.0 vs. v2.0 of an API). Paligo and Flare support branching; Confluence relies on page history or Space permissions.

• Output Formats:

• Confluence: Web pages, PDF (via export), Word.
• Flare: HTML5, PDF, Word, EPUB, mobile apps, embedded help.

• Paligo: HTML5, PDF, Word, SCORM (for e-learning), JSON (for APIs).

• Content Reuse:
  Avoiding duplication by referencing or transcluding content. Examples:

• Confluence: Excerpt Include macro.
• Flare: Snippets or variables.

• Paligo: Reusable components (DITA-based).

• WYSIWYG vs. Code-Based Editing:

• WYSIWYG (What You See Is What You Get): Confluence and Flare’s default editor (like Microsoft Word).

• Code-Based: Paligo’s XML editor or Flare’s "Text Editor" mode (for advanced users).

• Integrations:

• Confluence: Jira, Trello, Slack, GitHub (via apps).
• Flare: Git, Jenkins (for CI/CD), MadCap Central (for cloud collaboration).

• Paligo: Git, Salesforce, Zendesk, translation tools (e.g., Lingotek).

• Accessibility (a11y):
  Ensuring docs are usable by people with disabilities. Flare and Paligo support WCAG compliance (e.g., alt text, semantic HTML); Confluence requires manual checks (e.g., color contrast, screen reader testing).

Step-by-Step / Process Flow

How a technical writer creates and manages docs in a CMS (using MadCap Flare as an example):

1. Plan the Structure
2. Define outputs (e.g., PDF + HTML5 help) and audience (e.g., developers vs. end users).
3. Create a content model (e.g., DITA topics: Concept, Task, Reference).

4. Example: For an API doc, structure might include:

   
   
   • Concept: "Authentication Overview"
   • Task: "How to Generate an API Key"
   • Reference: "Endpoints" (auto-generated from OpenAPI).

5. Set Up the Project

6. In Flare, create a new project and select targets (e.g., "WebHelp" + "PDF").
7. Import existing content (e.g., Markdown, Word) or start from scratch.

8. Tool tip: Use Flare’s "Import Word" feature to convert legacy docs—clean up styles afterward!

9. Write Modular Content

10. Break docs into reusable topics (e.g., a "Prerequisites" snippet used in 10 guides).
11. Use conditional tags (e.g., <MadCap:conditions product="Enterprise">).

12. Example: A "Deployment" topic might have:
    xml
<p>For <MadCap:variable name="ProductName" /> Cloud:</p>
<ol>
<li>Go to the <b>Dashboard</b>.</li>
</ol>
<MadCap:conditions product="Enterprise">
<p>For self-hosted:</p>
<ol>
<li>Run <code>docker-compose up</code>.</li>
</ol>
</MadCap:conditions>

13. Add Media & Interactivity

14. Insert screenshots (use Flare’s "Capture" tool or Snagit).
15. Embed videos (host on YouTube/Vimeo and link) or interactive demos (e.g., Storybook for UI components).

16. Pro tip: Use Flare’s "Micro Content" for tooltips or pop-ups (e.g., hover over "API Key" to see a definition).

17. Configure Outputs

18. Customize HTML5 skins (e.g., add a search bar, logo, dark mode).
19. Set PDF styles (e.g., cover page, headers/footers, TOC depth).

20. Example: In Flare’s "Target" settings, enable:

    
    
    • Search: "Enable Google Analytics"
    • PDF: "Include page numbers in footer"

21. Publish & Maintain

22. Publish to a server (e.g., MadCap Central, Netlify, or an internal wiki).
23. Set up CI/CD (e.g., Jenkins or GitHub Actions) to auto-build docs on code changes.
24. Real-world workflow:
    • Developer updates an API → OpenAPI spec changes → Flare auto-generates new endpoint docs → Jenkins rebuilds HTML5 help → Docs stay in sync.

Common Mistakes

Tech Writing Interview / Portfolio Tips

What Hiring Managers Evaluate

1. CMS Experience:
2. Can you migrate docs from Word/Markdown to a CMS? (e.g., "I imported 200 pages into Flare using its Word importer.")

3. Do you understand single-sourcing? (e.g., "I reused a ‘Troubleshooting’ topic in 5 guides using Flare snippets.")

4. Tool-Specific Nuances:

5. Confluence: "How would you structure a knowledge base for a dev team?" (Answer: Use Spaces for teams, Page Trees for hierarchy, and Jira macros for issue tracking.)
6. Flare: "How do you handle conditional content?" (Answer: Use tags and targets to show/hide content for different audiences.)

7. Paligo: "How does DITA improve content reuse?" (Answer: DITA’s topic-based authoring lets you reuse concepts, tasks, and references across outputs.)

8. Portfolio Showcase:

9. Include before/after examples (e.g., "I migrated this Word doc to Flare—here’s the improved structure").
10. Show conditional content (e.g., "This PDF has ‘Admin’ and ‘User’ versions from the same source").
11. Demonstrate CI/CD (e.g., "I set up GitHub Actions to auto-build docs on merge").

Tricky Distinctions

• Conceptual Doc vs. Tutorial:
• Conceptual: Explains what (e.g., "What is OAuth?").
• Tutorial: Teaches how by building (e.g., "Build a Login System with OAuth").
• Reference vs. Guide:
• Reference: Facts only (e.g., API endpoint parameters).
• Guide: Step-by-step (e.g., "How to Call the API").
• Swagger UI vs. ReDoc:
• Swagger UI: Interactive (try endpoints in-browser), but heavier.
• ReDoc: Static, sleeker, better for embedded docs.

Quick Check Questions

1. Scenario: A developer complains that the API docs are outdated. How would you ensure docs stay in sync with code?
2. Answer: Use OpenAPI/Swagger to auto-generate docs from the spec, and set up CI/CD (e.g., GitHub Actions) to rebuild docs on every code merge.

3. Why: Manual updates are error-prone; automation ensures accuracy.

4. Scenario: Your team wants to publish the same content as a PDF manual and a web help site. How would you avoid duplicating work?

5. Answer: Use single-sourcing (e.g., Flare or Paligo) to write content once and publish to multiple formats.

6. Why: Duplication leads to inconsistencies and maintenance headaches.

7. Scenario: A manager asks, "Why not just use Confluence for all our docs?" What’s your response?

8. Answer: Confluence is great for collaborative internal docs, but lacks single-sourcing, conditional content, and advanced outputs (e.g., EPUB, embedded help) needed for customer-facing docs.
9. Why: Confluence is a wiki, not a technical authoring tool—it’s not designed for complex publishing workflows.

Last-Minute Cram Sheet

1. Confluence: Best for internal docs and collaboration; weak for single-sourcing.
2. MadCap Flare: Desktop tool for technical writers; supports PDF, HTML5, Word, EPUB.
3. Paligo: Cloud-based DITA CMS; ideal for regulated industries (e.g., medical, aerospace).
4. Single-sourcing: Write once, publish everywhere (e.g., reuse a "Prerequisites" topic in 10 guides).
5. Conditional content: Show/hide content for different audiences (e.g., "Admin" vs. "User").
6. DITA: XML standard for modular docs; breaks content into concepts, tasks, references.
7. ⚠️ A tutorial is not a how-to guide: A tutorial teaches concepts by building (e.g., "Build a Blog with React"); a how-to solves a specific problem (e.g., "Fix a 404 Error").
8. OpenAPI vs. Swagger: OpenAPI is the spec; Swagger is a toolset (e.g., Swagger UI, Swagger Editor).
9. Flare shortcuts:
10. Ctrl+Shift+T = Insert snippet.
11. F9 = Toggle between WYSIWYG and text editor.
12. Accessibility quick wins:
    • Add alt text to images.
    • Use semantic HTML (<h1>, <table>).
    • Test with WAVE or axe DevTools.