API docs in DITA & Markdown

This talk proposes a hybrid approach to API documentation that combines Markdown output generated by API docs tools like API Blueprint, RAML, or Swagger with more complex content authored in DITA and published via the DITA-OT Markdown plug-in for delivery via GitBook or other Markdown-based publishing systems.

Presented March 4, 2016 at the Write The Docs London mini-conference on Documenting APIs hosted by the UK’s Government Digital Service.

Transcript

1. API docs in DITA …and a bit of Markdown. infotexture Information Architecture & Content Strategy Roger W. Fienhold Sheen
2. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 ! Agenda Why Do Docs In DITA? Why Wouldn’t You? API Docs Challenges Markdown Mediation Hybrid Docs — DITA Meets Markdown Benefits & Use Cases
3. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 " Why Do Docs In DITA? The Darwin Information Typing Architecture “An XML architecture for designing, writing, managing, and publishing information” — dita.xml.org Originally developed by IBM for internal use, DITA is now an open standard published by OASIS, the Organization for the Advancement of Structured Information Standards. Why the funny name? Darwin: DITA utilizes principles of inheritance for specialization Information Typing: DITA was designed for technical information based on an information architecture of Concept, Task and Reference Architecture: DITA is a model for extending both design and processes
4. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 # Structured Authoring Benefits Separates content from presentation Focuses attention on meaning rather than appearance Ensures consistency Rules enforce document structure Template-based formatting deters manual tweaking Encourages creation of modular documents Allows documents to be easily reorganized Supports multiple variations of the same document Profiling, conditional text (Show/hide info on optional components) Facilitates automated publishing Build latest documentation along with new software Structured documents are easy to translate Keep the structure of elements & attributes; replace only the text
5. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 $ Single Source Publishing Content management approach in which the same source content is re-used in different document variants and/or media. Multiple Variants in a Single Document Different text content for product variants Filtering & profiling based on attributes FrameMaker’s “conditional text” Multi-channel publishing Generate multiple output variants for different media Often with the same text content
6. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 % Conditional Processing & Re-Use Options DITA was designed for modular content re-use and single-source publishing, with built-in support for multiple output variants, profiling, filtering, flagging. Maps — Defining new deliverables Keys — Exchanging variable definitions Conrefs — Re-use with content references Attributes — Profiling content by applicability Filtering — Conditional processing with DITAVAL files Which mechanism is most appropriate depends on the use cases, content models, authors’ skill level, abstraction aversion and tolerance for complexity.
7. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 Why Wouldn’t You? Despite all the benefits, XML authoring has a steep learning curve that presents significant barriers worth considering. XML authoring obstacles hard to read hard to write incredibly verbose intimidating to novices annoying to developers
8. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 API Docs Challenges Requires close collaboration between writers & devs Writers & devs have preferences for different tools and sometimes radically divergent ideas on ease-of-use Mindset shift for writers: treat docs like code Large portions of generated content High volume of re-use Volatile content Code samples Automation
9. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 Sample API docs from DITA source
10. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 Pulling In Code Samples API docs typically include code samples, which change frequently and are often generated programmatically from source code. <codeblock outputclass="json"> <coderef href="../json/address.json" format="json"/> </codeblock> To facilitate updates, code samples should usually be stored in external files and pulled in to the documentation by reference. "address": { "street": "125 Kingsway", "postalCode": "WC2B 6NH", "city": "London", "countryCode": "UK", "country": "United Kingdom", "text": "Aviation house (Government Digital Services)" }
11. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 & Markdown Mediation Created in 2004 by John Gruber & Aaron Swartz, Markdown is: 1. a plain text formatting syntax; and 2. software … that converts the plain text formatting to HTML “The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.” makes it easier to write without worrying about angle brackets and tags encourages authors to focus on structure rather than presentation good match for structured authoring scenarios with minimal markup
12. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 ' Hybrid Docs — DITA Meets Markdown The learning curve associated with XML dialects like DITA presents a barrier to broader adoption of structured authoring. But why ask subject matter experts to struggle with XML or learn a new tool before they can provide input? Shouldn’t we just let people write and let the tools figure out what to do? Several new solutions embrace this notion, many of which rely on Markdown: Lightweight DITA DITA Glass oXygen’s URL-based on-the-fly conversion from various file formats to DITA Some use h2d to convert to HTML as an interim format, and onward to DITA. This limits vocabulary to the original Markdown syntax — but one goes further…
13. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 ( The DITA-OT Markdown Plugin Jarno Elovirta’s DITA-OT Markdown plugin extends the toolkit so you can use Markdown files directly in topic references. Install it with the dita command: dita -install https://github.com/jelovirt/dita-ot-markdown/releases/ ↩ download/1.1.0/com.elovirta.dita.markdown_1.1.0.zip To add a Markdown topic, set the @format attribute to markdown so the plugin will recognize the source file as Markdown and convert it to DITA: <map> <topicref href="markdown-dita-topic.md" format="markdown"/> </map> The DITA-OT Markdown plugin not only enables the DITA-OT to read Markdown, it also provides a new markdown transformation type that can be used to publish existing DITA content in Markdown format.
14. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 ) The “Markdown DITA” Format The DITA-OT Markdown plugin introduces a new Markdown flavor called “Markdown DITA”, a representation of DITA content in Markdown. The shortcut reference link syntax is used to represent DITA key references, so you can just write [key] to create a cross-reference like <xref keyref="key"/> . Definition lists use the PHP Markdown Extra format, so Term : Definition. becomes a DITA definition list: <dl> <delentry> <dt>Term</dt> <dd>Definition.</dd> </delentry> </dl>
15. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 * Syntax Extensions Tables use the MultiMarkdown table extension format, and Pandoc’s header attributes can be used to define id or outputclass attributes, so # Topic title { #carrot .juice} becomes: <topic id="carrot" outputclass="juice"> <title>Topic title</title> Where necessary, Markdown DITA establishes a few conventions of its own to support additional DITA features: Specify the information type of the generated DITA topic with a header attribute like {.task} Generate <section> and <example> elements with the {.section} and {.example} attributes. The plugin’s syntax reference provides an overview of the supported constructs and illustrates how DITA’s XML structures are represented in Markdown DITA.
16. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 + Benefits & Use Cases Markdown becomes a first-class citizen Makes it easier to contribute to DITA publications Facilitates review processes with less technical audiences Feed DITA content into Markdown-based publishing systems Workflow Considerations 1. Avoid roundtripping. 2. Once complex content is converted to DITA, it stays in DITA. If the input is a one-off contribution, use the Markdown file as raw material that is easily converted to DITA and enriched with conditional processing attributes, conkeyrefs or other more complex semantics. 3. Simpler content stays Markdown. Simple content authored collaboratively over multiple versions is kept in Markdown, extended with Markdown DITA conventions and combined as necessary with more complex content maintained in DITA XML.
17. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 Sample Use Cases Maintain simple content in Markdown & publish with DITA 1. Create topic content in Markdown 2. Add topic reference to ditamap: @format="markdown" 3. Publish DITA map to multiple output formats Draft topics in Markdown for conversion to DITA 1. Draft topic content in Markdown 2. Add topic reference to ditamap: @format="markdown" 3. Publish normalized DITA output: -format dita 4. Save generated DITA topic 5. Enrich topic with DITA constructs 6. Maintain & publish subsequent revisions in DITA
18. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 Publishing DITA content with Markdown-based toolchains 1. Create simple topics in Markdown 2. Combine with complex DITA content in maps 3. Publish DITA map to Markdown-based formats: -format markdown -format markdown_github -format markdown_gitbook 4. Mix in additional Markdown content 5. Publish via GitBook, Leanpub, etc.
19. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 Sample GitBook output
20. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016 Resources http://daringfireball.net/projects/markdown https://github.com/jelovirt/dita-ot-markdown https://github.com/infotexture/ot-docs-markdown http://infotexture.net/2015/04/dita-ot-markdown-plugin