olf2016
TRANSCRIPT
Doc Like an Egyptian
Dru LavigneDirector of Technical Documentation, iXsystemsOLF October 8, 2016
All the old paintings on the tombs,They do the sand dance, don't you know?
If they move too quick (oh whey oh),They're falling down like a domino.
Walk Like an Egyptian, The Bangles
Outline
Overview of tools and processes forcreating/maintaining documentation
Introduction to Sphinx, an open source tool for generating documentation
In Theory: Docs... Are published with each software release, in multiple formats which suit the needs and devices of that software's userbase, in multiple translations which match that software's global audience, and are grammatically and technically correct.
In Reality...
Docs are incomplete or outdated (assuming they evenexist,are given lower priority than code,noone wants to write docs / noone reads docs anyways,and no perfect doc management solution exists.
Incomplete/Outdated Docs
Software is a MOVING target and outdated, unversioned docs are worse than no docs
Need process for versioning and archiving docs, andfor finding the correct docs for each software version
I Get No Respect Around Here
Cultural issue: docs are as important as code and Q/A and users do want useful docs
Gently point users to the pertinent section of the docs and create bug reports or doc updates
Finding the “Perfect” Tool
Is its formatting language easy to learn ora significant barrier to entry?
Are syntax editors available?
Does it support the required formatting?
Finding the “Perfect” Tool
1st Law of Doc Tools: the number/qualityof outputs is inversely proportional to theease of the markup language.2nd Law of Doc Tools: the fewer the docmaintainers, the higher the number of desiredoutputs.
Example: doc/odt
Good: WYSIWYG editor available to anyauthor
Bad: templates are painful; difficult tocollaborate; outputs are limited
Example: wiki
Good: entry barrier fairly low and syntax quick tolearnBad: no concept of ToC, content flow, or versioning;limited outputsIf you build it, they don't necessarily come (exceptfor the spambots)
Example: LaTeX
Good: rich formatting language; multiple outputsintegrate well into build and translation systems
Bad: very high barrier to entry as it takes adedicated time (and interest) commitment to learn(and teach) the formatting language
Sphinx FeaturesRelatively easy-to-learn formatting languagethat supports many outputs: HTML, PDF, ePUB,LaTeX, Texinfo, man pages, txt, API docs, etc.
Provides a number of extensions such asauto-numbered figures
Sphinx FeaturesAutomatic generation of ToC, index, glossary
Source files are text and easily integrate intoexisting revision control, translation, build, andCI infrastructures
Sphinx Features
Fully customizable conf.py for controlling doclayout
Several useful built-in builders (e.g. linkchecker)
Sphinx FeaturesSeveral built-in themes and support for customthemes; layout fully customizable using CSS
Custom preprocessors can be used to control whichelements appear in which documentation, allowingfor a “write once, publish many” workflow
Sphinx Features
Writers can use any text editor on any systemwith Python installed (or issue git pull requests)
Anything can be linked (figures, keywords,headings, etc.)
Sphinx Limitations
Some odd formatting limitations require CSSworkarounds (e.g. bold italic)
Documentation is limited, assumes you arefamiliar with Python, and needs more usageexamples
Converting Docs
Open source conversion utilities exist formost formats
Experiment by converting a small doccontaining required formatting
Expectations
Will you be versioning docs or onlycreating the latest and greatest?
What outputs are required? VersionedPDFs? HTML on project page? Built intosoftware itself as a help system?
Source Repo
Determine the doc versioning system andlayout of .rst files
Update the README with instructionsfor authors to create their own doc buildenvironment or how to create pull requests
Create a Cheat Sheet
Include a list of formatting tags and conventionsused by your docs and any gotchas to help newauthors quickly get up-to-speed
Publish the cheat sheet (or include inREADME) in doc repository
Review What's Available
Spend some time playing with conf.py andexperiment with existing themes BEFOREwriting new docs as themes affect layout
Review available extensions and determineif CSS customization is required
Resources & Examples
http://sphinx-doc.org
https://github.com/trueos/trueos-docs
https://github.com/freenas/freenas-docs
https://weblate.org
Questions?
Contact
URL to slides
http://slideshare.net/dlavigne/olf2016