LavaCon Las Vegas 2016 Presentation

1. MARKUP LANGUAGES AND
WARP-SPEED
DOCUMENTATION
Lois Patterson – Presentation

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

3. In the olden days …
Lois Patterson - Presentation

4. Today’s demands
• Weekly, daily, hourly releases
Lois Patterson - Presentation

5. How about you?
• What type of team?
Lois Patterson - Presentation

6. Agile development
• Agile workflows <-> continual, timely updates
of code and docs
Lois Patterson - Presentation

7. Are you agile?
Lois Patterson - Presentation

8. Book recommendation:
Modern Technical Writing: An Introduction to
Software Documentation Kindle Edition
by Andrew Etter
Lois Patterson - Presentation

9. Documentation is not separate
from the product
• Part of the product, embedded in the product
Lois Patterson - Presentation

10. Dev ops and doc ops
• Dev ops, doc ops
• Full stack approach
Lois Patterson - Presentation

11. Markup languages and doc ops
• Simplify!
o Writing
o Docs production
o Integration of docs with product
Lois Patterson - Presentation

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

13. Simple vs. complex markup languages
• DITA and DocBook
• reStructuredText, Markdown, and AsciiDoc
• Overhead versus structure
Lois Patterson - Presentation

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

15. Proprietary vs. open source
• Expensive and difficult tools, limited licenses
• Free tools, unlimited users
Lois Patterson - Presentation

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

17. Let’s look at Markdown
• My portfolio page at GitHub
Lois Patterson - Presentation

18. Lois Patterson - Presentation

19. More about Github
• 35 million repositories!
Lois Patterson - Presentation

20. GitHub, markup languages, and collaborative culture
• Github as an exemplar
• Full engagement from team
• Widespread contributions
• We’re in this together
Lois Patterson - Presentation

21. Collaborative culture
Lois Patterson - Presentation

22. You can be a contributor
• Help out open source software
• Learn new technologies
• Build your portfolio
Lois Patterson - Presentation

23. Do you have a Github site?
• Will you get a Github site?
Lois Patterson - Presentation

24. Nitty-gritty
Lois Patterson - Presentation

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

26. reStructuredText
Lois Patterson - Presentation

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

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

29. Sample reStructuredText template
Lois Patterson - Presentation

30. Sample reStructuredText template
Lois Patterson - Presentation

31. Look at a specific example
Lois Patterson - Presentation

32. 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`.

33. Sphinx transforms restructuredText

34. Compare restructuredText to DITA XML
•

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

36. From source to docs with Sphinx
•

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

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

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

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

41. Incorporating content from code
• Pull content from the code
• DRY (Don’t Repeat Yourself)
Lois Patterson - Presentation

42. Automate, automate,
automate
Lois Patterson - Presentation

43. Organization – still
important
Lois Patterson - Presentation

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

45. 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!

46. MORE BENEFITS
• Everyone writes
• Tool-agnostic (emacs, vim, Notepad++, SublimeText, whatever you love)
• Version-control friendly

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

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

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

50. CREATE RESTRUCTUREDTEXT TEMPLATES
• restructuredText allows you to author without much structure (ironic?)
• Enforce structure with templates and code reviews.

51. CONVERT CONTENT
• Pandoc!
http://www.pandoc.org/
• Semi-manual
Custom scripts

52. ALWAYS BE BUILDING
Know how your docs look at any moment. (Continuous integration for docs.)

53. INTEGRATE INTO PRODUCT BUILD SYSTEM

54. CODE PRACTICES FOR DOCUMENTATION
• Code review
• Version control
• Automated testing

55. WHAT ABOUT?
• Content reuse?
• Content management systems?

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

57. CUSTOM EXTENSIONS
Docs must pull information from the code in unique ways.

58. CREATE, USE MORE EXTENSIONS
Sphinx has so many options, just finding what is available takes time.

59. WHAT COULD HAVE BEEN BETTER
NOT SO BLAMELESS POST-MORTEM

60. COULD HAVE STARTED SOONER
But Sphinx did not exist way back when ….

61. MORE AUTOMATION
Lack of time, but still …

62. MAKE TASKS MORE GRANULAR
Too big and scary a task? Break it down!

63. SHOULD YOU USE MARKUP LANGUAGES?

64. IT DEPENDS
Consider:
• Markdown (different flavors)
• AsciiDoc
• DocBook
• DITA XML
• Or ?

65. WHAT NOT TO DO
• Design your custom bespoke system from scratch by yourself.
• Except if …

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

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

68. THANK YOU!
• Lois Patterson
• LoisRPatterson@gmail.com
• Twitter: @LoisRP
• Tumblr: http://www.AnAPIaDay.tumblr.com