knoxbug2016
TRANSCRIPT
You Too can Doc Like an Egyptian
Dru LavigneDocumentation Lead, iXsystemsKnoxBUG May 26, 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 why iXsystems switched toSphinx for its open source documentation
How you can help improve the documentationfor the PC-BSD, Lumina, SysAdm, or FreeNASopen source projects
What is Sphinx?
BSD-licensed tool for generating documentation inmultiple formats (eg PDF, HTML, ePUB) from ASCIItext files
Originally created by the Python Project for their docs
What is Sphinx?
Uses the reStructuredText markup syntax (.rst)
http://www.sphinx-doc.org
http://docutils.sourceforge.net/rst.html
Our Workflow Before Sphinx
Docs edited in MediaWiki
Before release, docs copy/pasted to OpenOffice in order togenerate HTML and PDF
Spent several years(!) convincing the MediaWiki translationplugin to work
Why This SuckedWikis have no concept of versions or Table of Contents
Wikis tend to be 90% SPAM management and 10%user-generated content
Time suck cleaning up generated HTML and PDFs
What we NeededEasy-to-use, cross-platform, collaborative tool withminimal software requirements
Integration with our existing git repositories, CI(Continuous Integration) and build infrastructure,and Pootle translation system
Ability to publish in multiple formats with minimalpain
Why Sphinx?
Easy-to-learn markup language
Writers can use any ASCII text editor (or theirweb browser and github)
Integrates easily into existing infrastructure andconversion utilities are available for existing docs
Why Sphinx?Theming support
A variety of extensions (eg automatic figurenumbering)
Useful build targets (eg link checker) and easy torun an automated spellchecker against multiplefiles
Our Doc Reposhttps://github.com/pcbsd/pcbsd/tree/master/src-qt5/docs
https://github.com/pcbsd/lumina-docs/
https://github.com/pcbsd/sysadm/tree/master/api
https://github.com/freenas/freenas/tree/master/docs/userguide
Sample Layout
(Mostly) Formatted Sample
Fully Formatted HTML
And Its Markup
Getting Started on Github
Fork the Repo to Edit
Click the Edit Icon to Open the Editor
Use a Descriptive Commit Message
Create a New Pull Request
Review Edits
Again, Useful Commit Message
Pull Request Succeeded
What the Reviewer Sees
Editing Tips
When updating a screenshot, increment theexisting name by the next letter (when updatinginstall1c.png, name the new image install1d.png)
If the text is formatted (eg with * or :ref:), editthe text but not the formatting
Interaction
Join us on #pcbsd, #freenas, or #lumina-desktopfor discussion (IRC Freenode)
Be descriptive in your commit message so itis clear what has changed and why
Be responsive to comments on pull requests
Resources
http://doc.pcbsd.org
http://doc.freenas.org
http://lumina-desktop.org/handbook
https://api.sysadm.us
