$30 off During Our Annual Pro Sale. View Details »

API docs in DITA & Markdown

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.

Roger Sheen

March 04, 2016
Tweet

More Decks by Roger Sheen

Other Decks in Technology

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