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
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
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
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
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
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`.
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
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.
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
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
Hi, I’m Lois Patterson. I’ve worked at many software companies in different roles. My focus for the past few years has been developer documentation. Much of this presentation was written while I was at my previous role as a Technical Communications Manager at a company where we did a large conversion project for our documentation.
Let’s look at the shift in culture. What are markup languages and dev ops? Why use one language over another?
A release every year or two was common. The docs would go to the printers. We would get proofs. It would take weeks!
Delays between development and documentation were expected.
Long release cycles.
Printing, corrections – it was a different world.
Who does this? Google, Atlassian, many companies who need to go live with new content all the time.How can you keep documentation in sync if you go through a print house review cycle? Consider the code review process for software development.
Who has a technical documentation team with a defined set of writers using proprietary tools?(Gatekeeping model, may be necessary in certain environments)
Who has a technical documentation team with writers, but also outside contributors? (Typical software world)
Who has no official tech docs team, but a host of contributors? (E.g., last I heard, Twitter has 4 technical writers. But look where Twitter is.)
Agile means something different to every person and every company, but we generally agree that it’s a way to develop working software continuously and incrementally, rather than waiting for a big bang product.Do not get hung up on the philosophy differences. The idea is the teams are continuously checking in against each other, and delivering improvements almost all the time.
We all strive to be.But still not completely suitable for all cases.
Modeling requirements and planning are still important (and can be part of Agile).
Book recommendation
I recently read this book, and he covers many of the same concepts I discuss in this talk. I recommend reading it if you can.
If you get Kindle Unlimited, then it’s free (a plug).
For many products, the documentation is integrated into the product. It’s not possible to pull them apart. Not all documentation is in the product, but enough of it is that you have to keep up to date.
Dev ops means you will likely hear about Ansible, Puppet, Chef, Docker. Agile development continues through to the IT team. Fully integrated dev ops has development, QA, documentation, IT deployment, and customer support all prepared and all aligned with the current product version at any given moment.
How can you do this type of rapid, continuous development, integration, and deployment if you do not simplify processes? Judicious use of markup languages, and treating docs as code, allows you to vastly speed up your process.
You have used markup languages, I’m sure. I’m focusing on the simple ones for this presentation – perhaps I should have said – Why use simple markup languages for documentation?
I don’t want to make a hard and fast division. easyDITA, FluidTopics, and other vendors are working on ways to make DITA work in a high-speed environment. But I’m discussing what has worked for us, and what I know has worked for many others working particularly in the field of developer documentation.
XML markup, like DITA and DocBook vs. simpler markup, like reStructuredText, Markdown, and AsciiDoc
Different domains – different requirements
Situation is evolving!
Balance of overhead versus structure
By quickly, I mean within an hour. Just like anyone can write in a wiki. Some writers worry they are less valuable if everyone is documenting. No – you do necessarily take an editorial role, but there are always documents to write, particularly for complex software. You can go well beyond the basics.
The right use of markup languages allows anyone to become a contributor with close to zero rampup, and no concern about licenses or weeks of training.
If you use markup languages, you need a way to process the raw documents into a finished product. So here’s the general process.
My portfolio page at GitHub
Markdown is highly versatile, widely used
Different flavors hinder compatibility
Customizations are common
We’ve taken a look at Markdown. Now we’ll look at reStructuredText.
Github is an example of what collaborative culture can look like.
GitHub phenomenon has a general theme: widespread contributors
We’re in this together
Technical writers, to produce constantly updated docs, require full contributions from other team members
Dev/Doc Ops requires an engaged, fully coordinated team
Every developer knows markup languages; contribution is straightforward
->I just saw this quote on Twitter.
I just saw this quote on Twitter. Developers know they need good documentation to use new APIs, new languages, and so forth. Having excellent technical contributors in no way diminishes technical writers.
Let’s take this idea of contribution more generally. Not only in the company you work for, but for the tools you know and love. You can see this collaborative culture with everyone who has contributed to Github or other open communities. Many excellent open-source software projects with great developers need technical documentation
Use of markup languages, a knowledge of Git, and a willingness to follow the process required
Build your portfolio
Growing trend for hiring managers to look at GitHub commits
We all strive to be.But still not completely suitable for all cases.
Modeling requirements and planning are still important (and can be part of Agile).
Let’s look a some technical details of using markup languages.
Some possible negatives. I’m discussing positives throughout, so I want to keep these in mind.
Let’s take some look at some examples.
I am very partial to reStructuredText. I love Python, which is where reST originated (not to be confused with REST APIs). So many excellent projects are using rest, and you can see many of these projects at the Read The Docs site. We were very fortunate to have the resources of an experienced Python developer, who is very familiar with the build system, how content is pulled in from various places, and who was just generally a superstar developer.
You can get an idea of how flexible rest is. The ReadTheDocs page is editable at Github, and you can see the source. You can also see it rendered at Github, and you can also see it rendered at ReadTheDocs. If they wanted to make a PDF, or some other format, they could.
Remember reStructuredText designed to work with Python functions originally
Look at RackSpace implementations
Stripe’s API docs
General principle: Write a script that pulls content out of code and into a markup file, which is then processed into documentation
DRY (Don’t Repeat Yourself)
I have done so much copy and paste in my life, but you are setting yourself up for error. We need to automate!
Automation is what makes Agile work, what makes dev ops work, and what will make markup languages work for you.
If ever you find yourself copying and pasting, see if there’s a way you can automate that.
Having continuously updated docs relies on automation.
What are some examples of automation that you use?
Templates, variables, planning, thinking – markup languages are a tool, but technical documentation still requires planning and organizing.