lois patterson: markup languages and warp-speed documentation
TRANSCRIPT
What this presentation is about
• How software development culture is moving towards Dev Ops
• Using markup languages to adjust to the Dev Ops culture
• Advantages and disadvantages of different markup languages
• How content written in a markup language is converted to attractive documentation
• How you can switch to using markup languages
Lois Patterson - Presentation
Agile development
• Agile workflows <-> continual, timely updates of code and docs
Lois Patterson - Presentation
Book recommendation:Modern Technical Writing: An Introduction to Software Documentation Kindle Edition
by Andrew Etter
Lois Patterson - Presentation
Documentation is not separate from the product
• Part of the product, embedded in the product
Lois Patterson - Presentation
Markup languages and doc ops
• Simplify!
o Writing
o Docs production
o Integration of docs with product
Lois Patterson - Presentation
What is a markup language?
• Plain text, with various tags or other elements that indicate how the text should be processed
• HTML is best-known
• XML – family of markup languages
• Simple, doc-friendly markup languages:
• reStructuredText
• AsciiDoc
• Markdown
Lois Patterson - Presentation
Simple vs. complex markup languages
• DITA and DocBook
• reStructuredText, Markdown, and AsciiDoc
• Overhead versus structure
Lois Patterson - Presentation
Markup languages foster content collaboration
• Learn a markup language quickly
• Constant documentation updates require cross-team contributors
• Make life easy for all contributors
Lois Patterson - Presentation
Proprietary vs. open source
• Expensive and difficult tools, limited licenses
• Free tools, unlimited users
Lois Patterson - Presentation
Markup + Processor
• General principle: Write doc in markup language
• Process the markup to get your final docs
• DITA Open Toolkit, Sphinx (for reStructuredText), Jekyll (for Markdown)
• Static site generators produce static HTML
• Dynamic site generators render on the fly
• GitHub processes various markup formats instantaneously
Lois Patterson - Presentation
GitHub, markup languages, and collaborative culture
• Github as an exemplar
• Full engagement from team
• Widespread contributions
• We’re in this together
Lois Patterson - Presentation
You can be a contributor
• Help out open source software
• Learn new technologies
• Build your portfolio
Lois Patterson - Presentation
Challenges of unstructured languages
• DITA forces unity among writers. Deviation is punished.
• Impose structure with templates and standards.
• “You can, but you shouldn’t.”
• Structure and unity particularly important if localization is happening.
Lois Patterson - Presentation
Let’s look at reStructuredText
• Start at readthedocs.org. (Docs at https://docs.readthedocs.io/ .)
• Python community origin
• Versatile
• Used with Sphinx static site generator
Lois Patterson - Presentation
Let’s look at reStructuredText
• ReadTheDocs page, editable at GitHub
• Rendered at GitHub
• Rendered at ReadTheDocs.org
• You can do the same!
Lois Patterson - Presentation
restructuredText looks like this
Getting Started
===============
This document will show you how to get up and running with Read the Docs.
You will have your docs imported on Read the Docs in 5 minutes,
displayed beautifully for the world.
If you are already using Sphinx or Markdown for your docs, skip ahead to
:ref:`import-docs`.
XML (DITA XML) – VERY SIMPLE FILE• <?xml version="1.0" encoding="UTF-8"?>
• <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
• <topic id="topic_qk5_knc_fg">
• <title>Troubleshooting</title>
• <body>
• <p>Troubleshoot most common issues.</p>
• </body>
• </topic>
SPHINX AND RESTRUCTUREDTEXT
• reStructuredText (reST) is rather like Markdown.
• Sphinx is a static site generator.
• restructuredText other stuff (HTML, PDF, etc.)
• restructuredText/Sphinx:: Markdown/Jekyll
SPHINX, DOCUTILS, RST - SUMMARY• Output formats
• Extensive cross-references
• Hierarchical structure
• Automatic indices
• Code handling
• Extensions
• Contributed extensions
• Uses reStructuredText for markup, and Docutils for parsing
See more: http://sphinx-doc.org/index.html
Want to author in reStructuredText and generate in Sphinx?
Install Python first. (We used a 2.7.x version, but 3.3+ supported too.)
Sphinx Tutorial: http://sphinx-doc.org/tutorial.html
YouTube too! https://www.youtube.com/watch?feature=player_embedded&v=oJsUvBQyHBs
Look, copy, build, experiment
Static site generators
• Server load reduced
• Less prone to network difficulties and intermittent errors
• Speed, security
• Available offline (many clients require this)
• Recent count: 394 different ones
• Choosing a well-supported one is key
• Disadvantages too
Lois Patterson - Presentation
Incorporating content from code
• Pull content from the code
• DRY (Don’t Repeat Yourself)
Lois Patterson - Presentation
WHY WE LEFT THE CUSTOM XML WORLD
• Custom XML locked us in.
• HTML-based systems (e.g., MadCap Flare) do not easily integrate into our vision of all devs write
• Did not really leave after all
GREAT THINGS ABOUT SPHINX AND RST
• Well-developed eco-system
• Python!
• Versatile outputs
• Easy to write
• Easy to read
• Text-based
• Encourages topic-based authoring!
MORE BENEFITS
• Everyone writes
• Tool-agnostic (emacs, vim, Notepad++, SublimeText, whatever you love)
• Version-control friendly
OLD VS. NEW
Structured XML• Proprietary format
• Complex build machinery
• Tightly coupled with product (in a bad way)
• Supports MathJax
Positives
Enforced programming structure
It’s ours!
Sphinx/rsT• Open format
• Easy to build
• Easy to write
• Easy to read
• Supports MathJax
• Negatives
• Some customization needed
TYPICAL CONVERSION WORKFLOW (XML TO RST)
• High-level website design
• Create templates (for our sanity)
• Convert content
• Create content
• (All the time be building)
• Integrate into product and build system
WEBSITE DESIGN (DOCUMENTATION SYSTEM)
• A corporate-branded site, not a personal or open-source look
• Standard UX and design work
• Liaise with Marketing and other stakeholders
• jinja templating engines are a starting point
CREATE RESTRUCTUREDTEXT TEMPLATES
• restructuredText allows you to author without much structure (ironic?)
• Enforce structure with templates and code reviews.
CASE STUDY
• Rackspace (along with NASA invented OpenStack) switched/is switching OpenStack docs from DocBook XML to Sphinx/RST.
• http://justwriteclick.com/2015/02/23/state-of-the-migration-to-sphinxrst/
• https://wiki.openstack.org/wiki/Documentation/Migrate
RESOURCES• http://sphinx-doc.org/
• http://readthedocs.org
• http://www.pandoc.org
http://justwriteclick.com/2015/02/23/state-of-the-migration-to-sphinxrst/
https://wiki.openstack.org/wiki/Documentation/Migrate
http://sphinx-doc.org/tutorial.html
https://www.youtube.com/watch?feature=player_embedded&v=oJsUvBQyHBs
In summary
Lois Patterson - Presentation
• Technical writers must work faster than ever
• Technical writers must collaborate across teams
• Markup languages facilitate a collaborative culture
• You have huge flexibility in the solutions you choose
• Structure, standards, and process are as important as ever
THANK YOU!
• Lois Patterson
• Twitter: @LoisRP
• Tumblr: http://www.AnAPIaDay.tumblr.com