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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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.
   

   View Slide

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
   

   View Slide

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
   

   View Slide

9. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016
   Sample API docs from DITA source
   

   View Slide

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.
    
    
    
    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)"
    }
    

    View Slide

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
    

    View Slide

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…
    

    View Slide

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:
    
    
    
    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.
    

    View Slide

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 .
    Definition lists use the PHP Markdown Extra format, so
    Term
    : Definition.
    becomes a DITA definition list:
    
    
    Term
    Definition.
    
    
    

    View Slide

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 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 and 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.
    

    View Slide

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.
    

    View Slide

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
    

    View Slide

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.
    

    View Slide

19. Write The Docs London @ Aviation house (Government Digital Services) March 4, 2016
    Sample GitBook output
    

    View Slide

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
    

    View Slide