-
Notifications
You must be signed in to change notification settings - Fork 27
DITA TC Committee Notes
Stan Doherty edited this page Jan 27, 2026
·
16 revisions
This page provides support for OASIS DITA TC members developing TC committee notes in 2026.
Attendees: Leroy, Zoe, Christina, Stan
The November proposal to the DITA TC focused on developing a comprehensive user guide. Per TC discussion, we abandon that goal in favor of the following:
We propose developing and publishing a library of OASIS DITA TC Committee Notes focused initially on three audiences:
- Beginner writers who have had little or no exposure to DITA concepts, tools, or basic coding practices.
- Intermediate DITA writers who know the basics, but want to learn best practices for using specific DITA features.
- Software engineers who need to understand how structured markup and DITA in particular benefit software development, e.g. LLM training, semantic markup, SEO, and content maintenance.
Along the way, we want to recruit new DITA TC members to support both these committee notes and the DITA 2.0 spec. Solicited technical review feedback from writing teams in the field will increase participation and adoption.
- Focus on DITA 2.0: Whatever we document or exemplify will focus on DITA 2.0 functionality.
- Authoring environment: Content being developed will live in the OASIS DITA TC GitHub wiki.
- TC approval: The DITA TC must review and approve all documents prior to publication as a TC committee note.
- Style guide: We depart from the DITA Spec writing guidelines when necessary and document departures.
- DITA 2.0 templates: The topic and map templates will be different from the spec. Probably best to start simply.
- Phases (Agile): Initially, the writing and reviewing will be performed by this subset TC members. When we know more, we can recruit other writers to join the TC from member companies and other professional groups (ACM, W3C, IEEE).
We have many possible topics to develop. Wisely, folks on the call opted to look them all over for some time before making decisions about writing. Two exceptions:
- Leroy signed up to work on the DITA 2.0 Migration Guide.
- Stan signed up to work on the Introduction to DITA for writers.
- Open - Troubleshooting Guide
We did some great brainstorming and identified some new topics to consider.
- Introduction to DITA taxonomies.
- Getting Started with the DITA Open Toolkit.
- Introduction to DITA metadata.
- Organizing and managing DITA content in GitHub.
- Introduction to DITA for software developers.
- Integrating DITA with software development tools, e.g. Elastic Search, Swimming Pool, or Semaphore.
- Prepping DITA content for AI training.
- Best practices for using DITA keys on large teams.
Did my best to organize these possible writing efforts into categories. It's a start.
- History of DITA?
- Introduction to DITA.
- Generic - How to use an element. (Maybe examples of how some elements can be/have been abused?)
- How to use Metadata elements (including how to abuse).
- Othermeta was to mimic HTML Meta element
- Interaction between Metadata elements that have the same name as profiling attributes
- How metadata is inherited from maps (what cascades, what doesn't)
- Conditional Text/Profiling
- How to specialize.
- Nesting ditavals in maps.
- How to use @prop (Reworking element reference vs architecture content in an 'easy to use' way?
- Keys, conrefs, conkeyrefs - content, phrases, images (The whole reuse thing). See Adoption TC articles C16, C17, C19, and C21 below.
- Preparing for translation. See Adoption TC articles C9, C10, C11, C22, and C23 below.
- DITA and AI.
- Glossaries (might be challenging to find best practice). See Adoption TC articles C13, C18, C20 below.
- subjectScheme maps (make them easier to understand?)
- Learning and training resources
- Machine industry resources
- Anything that can't be used out of the box (release mgmt domain, classification maps for example)
- How to use ditamaps (TOC, Submaps, Keys, relationship tables, etc., etc.) See conversation from 5 August 2025 about DITAMAPs and DITAVALs: https://groups.oasis-open.org/HigherLogic/Security/SAML/localSAMLLoginService.aspx?ReturnUrl=https%3a%2f%2fgroups.oasis-open.org%2fHigherLogic%2fSecurity%2fLoginBounce.aspx%3fReturnURL%3dhttps%253A%252F%252Fgroups.oasis-open.org%252Fhigherlogic%252Fws%252Fgroups%252Fc2c11e3a-c9cd-43d9-840b-018dc7cd5db9%252Fdocuments%252Fmeetings%252Fdocument%253Fdocument_id%253D72955
- DITA 1.3 to DITA 2.0 migration guide.
- Troubleshooting topics in DITA 2.0.
- DITA 1.3 Feature Article: User Assistance Enhancements in DITA 1.3
- DITA 1.3 Feature Article: Don't (XML) Mention It: Tagging XML Constructs in DITA 1.3
- DITA 1.3 Feature Article: Writing effective short descriptions
- DITA 1.3 Feature Article: About the DITA 1.3 release management domain
- DITA 1.3 Feature Article: Understanding Scoped Keys in DITA 1.3
- DITA 1.3 Feature Article: Making the Most of the New Math Domains in DITA 1.3
- DITA 1.3 Feature Article: Using DITA 1.3 Troubleshooting
- DITA 1.2 Feature Article: Roles and Responsibilities of a DITA Implementation
- DITA 1.2 Feature Article: Using XLIFF to Translate DITA Projects
- DITA to XLIFF and Back - Reducing the Costs and Risks of Translating XML Content
- DITA to XLIFF and Back - Understanding the Technical Solution
- DITA 1.2 Feature Article: Tools and DITA Awareness
- DITA 1.2 Feature Article: Acronym Best Practices
- DITA 1.2 Feature Article: Task Model
- DITA 1.2 Feature Article: Domain and topic integration
- DITA 1.2 Feature Description: Conref Push
- DITA 1.2 Keyref: Feature Description
- DITA 1.2 Glossary and Terminology Specialization Feature Description
- DITA 1.2 Referencing a Range of Elements: Feature Description
- DITA 1.2 Feature Description: Improved glossary and terminology handling
- Best Practices for Using the DITA Conref Attribute in DITA for Translation
- Best Practice for Indexing DITA Topics for Translation
- Best Practice for Leveraging Legacy Translation Memory when Migrating to DITA
The PDFs for all the 2.0 spec reviews are posted. Identifying the "user guide" content will require some digging.