#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."
#DX#DeveloperPortals#APIs#APIDocumentation#InformationArchitecture#TechnicalWriting: "An out-of-the-box developer portal can speed up your go-to-market. But after a quick launch, a developer portal that cannot be customized can become a roadblock to the long-term success of your API program. As the API portfolio grows and matures, your strategy will probably change and require more specific business experiences. In this case, a preset solution may no longer suit all the desired goals, and retooling might become necessary.
The Codat Docs team went through such a journey: they wanted to have more flexibility and control over their docs, and they built their own custom solution. Now, their documentation site is more resilient. With the help of the new landscape, large-scale changes can be managed on over three hundred pages of content without interrupting the existing user experience.
To mention another example, the Monite API Developer Portal uses a robust content management system that is exclusively tailored for developer documentation. The comprehensive resource was designed to provide an end-to-end self-service experience to developers.
The ability to extend and customize your developer portal plays a crucial role in executing on the API business strategy."
Friends. I’m looking for work. I’m a UX designer/researcher, information architect, and UI designer/developer. I bring over two decades of experience to the table. I’m also an accessibility/usability expert.
If you have a need I’d love to talk with you. If you know folks, I’d love a boost. Thank you! 🙌🏻
Care about an excellent information architecture before you start designing anything. When you know what belongs where, you will get a better understanding how things fit together.
The URLs have been simplified to drop the foundations/ path, which may affect other topics in this section as well, so expect more broken links.
This sort of reorg is pretty common as content evolves and #InformationArchitecture adapts accordingly, but there’s no reason to break previously published links.