Skip to content

DITA Sample: Managed macOS Onboarding Guide

One-sentence summary:
A structured authoring sample that adapts a managed macOS onboarding guide into DITA using concept, task, reference, troubleshooting, and map-based organization.

Overview

This project reworks an end-user managed macOS onboarding guide into a modular DITA documentation set. The sample separates explanatory, procedural, reference, and troubleshooting content into distinct topic types and organizes them with a DITA map. It was created to demonstrate foundational DITA knowledge and show how the same documentation scenario can be presented in both Markdown and structured XML.

Audience

  • Hiring managers reviewing structured writing samples
  • Documentation teams using DITA or topic-based authoring
  • End users receiving a company-managed Mac

Documentation Goal

The goal of this sample is to demonstrate basic DITA authoring skills by converting an existing onboarding guide into reusable, topic-based XML. It shows an understanding of structured content, topic type separation, and map-based documentation assembly.

What This Sample Demonstrates

  • Basic DITA authoring
  • Topic-based documentation design
  • Concept, task, reference, and troubleshooting topic types
  • DITA map organization
  • Structured XML writing
  • Adaptation of existing Markdown documentation into modular content

Tools / Methods

  • DITA XML
  • Markdown
  • GitHub
  • Structured authoring principles
  • Topic-based writing
  • Content modularization

Challenges / Writing Considerations

  • This sample required restructuring a linear onboarding guide into topic-based content that aligns with DITA conventions.
  • The content needed to be split into appropriate topic types so that explanation, procedures, support information, and troubleshooting were clearly separated.
  • Because this was a first DITA project, the scope was intentionally limited to core topic types and map structure rather than advanced publishing or reuse features.

Deliverables

  • DITA map
  • Concept topic
  • Task topics
  • Reference topics
  • Troubleshooting topic
  • Project page describing the DITA documentation set
  • Source files stored in the portfolio repository

Outcome / Why It Matters

This sample demonstrates the ability to learn and apply structured authoring concepts in a practical documentation scenario. It shows adaptability across formats and provides evidence of foundational DITA skills alongside Markdown-based portfolio work.

View the Project

DITA, structured authoring, topic-based writing, XML, end-user documentation, troubleshooting documentation, content modularity