#TechnicalWriting#SoftwareDocumentation#Markdown#XML#DITA: "Think about how in Markdown you would ensure that “all our how-to guides must have an h1 title, followed by one or more paragraphs, followed by one or more steps to achieve the guide’s goal”, and then consider how easy it is in DITA.
This is just not really possible today, at least in any popular Markdown-based framework.
There is a path
Bridging the gap between Markdown and structured authoring will require building new tooling and standards. It’s unlikely that CommonMark or any other popular Markdown flavor would consider going in this direction, so we’ll have to create tools around Markdown.
We at Doctave have some ideas about how to achieve this, and have a roadmap on how to get there. At a high level there are a few things we would need:
✅ A parser and template system that is Markdown-aware
❌ A language for describing constraints and rules for your Markdown content
❌ An engine that enforces those rules on your content
We’re already part of the way there!"
#TechnicalWriting#DITA#XML#DITAXML#Documentation#InformationArchitecture#StructuredAuthoring: "DITA is defined in its specification as “an XML-based architecture for authoring, producing, and delivering topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways”. Originally developed by IBM in the early 2000s, DITA stands for Darwin Information Typing Architecture. “Darwin” refers to the naturalist Charles Darwin and his theory of evolution, reflecting DITA’s principles of specialization, inheritance, and adaptation.
DITA topics are standalone, context-free blocks of content, with content types kept clearly separate. There are three main topic types in DITA, all of which are inherited from the base topic type <topic>:
<concept>: background information that users must know before using the product
<task>: step-by-step instructions that users need to perform a task
<reference>: product specifications, commands, or other reference material
You create a document by selecting which existing topics should be reused and referencing them in what’s called a DITA map (similar to a table of contents).
Being an open standard, DITA has no proprietary restrictions. But while you’re not forced to buy a specific tool to use it, commercial XML editors have many features, such as visual editing and validation, that make writing DITA content much easier."
#TechnicalWriting#SoftwareDocumentation#DITA#CCMS: "Whether we are talking about technology, governments, business, culture, or the environment – we live in a world of constant change. In our field of work, many of us see changes impact our documentation on a weekly, if not daily, basis. To keep pace with these changes and maximize content reuse, it has become standard practice to employ some form of topic-based authoring tool.
However, when technical communication professionals consider their content authoring and management strategies, the best solution is not always clear. Does it require a component content management system (CCMS) based on the Darwin Information Type Architecture (DITA)? Or will a more general solution for topic-based authoring provide the necessary features?"
#TechnicalWriting#DITA#Markdown#SoftwareDocumentation: "Moving from DITA (Darwin Information Typing Architecture) to Markdown for technical documentation involves weighing several benefits and risks, which are pertinent to the specific needs and workflow of technical writers
While Markdown offers notable advantages in terms of productivity, collaboration, and alignment with modern development workflows, it also presents significant challenges in content structure, scalability, and feature richness.
Technical writers must be prepared to navigate the less-structured environment of Markdown and may need to employ additional tools and practices to compensate for the loss of certain key capabilities inherent in DITA’s more complex system.
The decision to transition should therefore be made with a thorough understanding of these trade-offs and an assessment of the specific needs of the documentation project.