Unconference Session #3 Notes – TC Camp 2017

Tools for documenting APIs

Top Takeaways

How to choose a tool:

  • See www.indoition.com — A website on technical documentation know-how
  • OpenAPI is hot
  • Some writers “do it by hand” in Frame or similar
  • YAML — not a markup language. RAML — REST API markup language. All RAML is YAML, but not all YAML is RAML


What tools?

  • Swagger, PostMAN, RAML, Jekyll
  • Facilitator used Jekyll-based modified to use RAML
  • Readme.io — publishes on public site (considered a drawback)
  • Box, Android, GoogleMaps, Stripe, Digital Ocean,
  • Swagger (openAPI) takes JSON and makes display
  • Various home-grown tools are out
  • Jekyll is written in Ruby
  • How to do cross-references between a generated doc and expository doc (e.g., developer guide)
  • How to choose a tool?
  • Is there a survey?
  • Google API Discovery Service is similar to Swagger

Large, complex doc systems with markdown and Git

Top Takeaways

  • Top trend, especially with MS Docs; MS to Azure evolution
  • Major challenges: Search, link validation, finding files, reuse, structure
  • Most solutions involve custom programming to scale
  • Check out Ralph Squillace presentation
  • What works on a small scale probably requires more and more programming at a large scale
  • Translation is an obstacle; vendors don’t often accept markdown


  • Does it scale to a gigantic system?
  • Is this trend the future?
  • Can you apply it to different industries (machinery, pharma)?
  • What do you run into at this scale? IBM — you need a custom program
  • How to keep track of topics? Schema for adding structured metadata to find content; reuse; automation; translation
  • Why did MS make this move? Empower employees to write
  • What works on a small scale, may not scale to a larger system
  • How to you validate links? Xenu is a tool
  • Running validation scripts is huge
  • Writer using markdown is aware of potential problems with search and scale
  • One writer uses custom Ruby syntax
  • One writer wants to move to markdown to simplify

Case Studies

Top Takeaways

  • Sources: Marketing docs, Engineering docs, bug reports, field visits, Marketing, engineers, tech support
  • “I know this. Can you tell me the next step?” building a relationship with engineers
  • Ask the right questions; guiding the conversation for what is the problem and what we are trying to solve


  • This skill is important for all tech writers
  • New and returning tech writers find it difficult to gather information
  • Communicating with customers is important in gathering material
  • Users are more important than developers
  • Marketing wish list: MRD, ERD, use case scenarios give information about the product, but not the use
  • Know the user
  • Site visit good source
  • Tech writer’s role to give feedback to developers on usability to improve design
  • Quality of raw material is important; if raw material isn’t of good quality, ask questions
  • If using MRD, QA and tech support are a good source of raw material
  • Bug reports

Creating a Documentation Delivery Platform

Top Takeaways

  • Get buy-in and support from multiple teams
  • Workflow to determine tool instead of vice versa
  • Trade offs for custom-built vs. out-of-the-box solution
  • OK to use many tools and customizations
  • No one right solution


Skills: XSSLI, HTML, CSS, design, getting from source to output

Creating requirements, project management, get buy-in

Development buy-in handy to really get support involved and integrate their requirements

Single domain search

Team ownership: different views, different stakes

In what instance should you do HTML or out-of-the-box solutions?

  • Tools are expensive and require implementation and customization
  • Want to look unique
  • Is the tool over built?
  • You don’t get fixes
  • Must maintain customization

Public vs. Private: depends on content

What tools are people using?

  • Mediawiki: Great publishing tool. Accepts HTML and wiki text. Open source and free development extensions

Tool process:

  • DITA->OxYGen->Git->DITA Open Toolkit->HTML/JSON->support portal->Swift-type->Docs

Tailor things to your internal process

Use Google Docs for collaboration; go to markdown, and then HTML

Workflow more important than having a custom tool


  • Who wants PDF?
  • XML
  • HTML5
  • epub
  • What devices are people using?
  • Research format

Markdown handy for code review

Localization issues

Session cancelled. No notes.

DITA vs Markdown

Top Takeaways

  • No “vs.” it’s a different use case
  • Reuse/conditional text, mapping topics, semantic tagging
  • Large topics unmanageable in markdown
  • Markdown is great for simple authoring and formatting small topics
  • Markdown popular with developers
  • Interest and amount of activity in SourceForge, and markdown capabilities.
  • DITA needs simpler tools to market to SMEs/developers


Tom Johnson: Developers like markdown; kind of like a text editor with some tagging.


  • popular with people who don’t use DITA
  • Format but no reuse or conditional text
  • Purely for formatting simple text — very simple
  • Simple conversion, usually to HTML


  • Criticized for complexity — developers don’t want to use DITA

Markdown so popular, many DITA tools convert it

What can tech writers learn from simplicity of markdown and its popularity?

  • Internal software API — markdown is DEV & QA -> endpoint internal wiki, website
  • Complex use cases will fail: cross links, cross references likely to fail

Markdown source compatible with features like HTML tables, but cumbersome

Consider markdown a tool for SME/DEV

Contributors consider markdown a “young person’s” (millennials) tool

Is there a future if the key players for DITA are gone?

Do we need to produce large document sets?

Better to think of end product, and see what tool fits

Open source and markdown is hot

Key Features Comparison

  • Arrangement/mapping:  DITA (2) Markdown (1)
  • Topic typing: DITA (2) Markdown (0)
  • Basic revisions: DITA (2) Markdown (1)
  • Metadata: DITA (2) Markdown (2)
  • Semantic tagging: DITA (2) Markdown (0)