Slides for May KnoxBUG meeting.

1. You Too can Doc
Like an Egyptian
Dru Lavigne
Documentation Lead, iXsystems
KnoxBUG May 26, 2016

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

3. Outline
Overview of why iXsystems switched to
Sphinx for its open source documentation
How you can help improve the documentation
for the PC-BSD, Lumina, SysAdm, or FreeNAS
open source projects

4. What is Sphinx?
BSD-licensed tool for generating documentation in
multiple formats (eg PDF, HTML, ePUB) from ASCII
text files
Originally created by the Python Project for their docs

5. What is Sphinx?
Uses the reStructuredText markup syntax (.rst)
http://www.sphinx-doc.org
http://docutils.sourceforge.net/rst.html

6. Our Workflow Before Sphinx
Docs edited in MediaWiki
Before release, docs copy/pasted to OpenOffice in order to
generate HTML and PDF
Spent several years(!) convincing the MediaWiki translation
plugin to work

7. Why This Sucked
Wikis 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

8. What we Needed
Easy-to-use, cross-platform, collaborative tool with
minimal 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 minimal
pain

9. Why Sphinx?
Easy-to-learn markup language
Writers can use any ASCII text editor (or their
web browser and github)
Integrates easily into existing infrastructure and
conversion utilities are available for existing docs

10. Why Sphinx?
Theming support
A variety of extensions (eg automatic figure
numbering)
Useful build targets (eg link checker) and easy to
run an automated spellchecker against multiple
files

11. Our Doc Repos
https://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

12. Sample Layout

13. (Mostly) Formatted Sample

14. Fully Formatted HTML

15. And Its Markup

16. Getting Started on Github

17. Fork the Repo to Edit

18. Click the Edit Icon to Open the Editor

19. Use a Descriptive Commit Message

20. Create a New Pull Request

21. Review Edits

22. Again, Useful Commit Message

23. Pull Request Succeeded

24. What the Reviewer Sees

25. Editing Tips
When updating a screenshot, increment the
existing name by the next letter (when updating
install1c.png, name the new image install1d.png)
If the text is formatted (eg with * or :ref:), edit
the text but not the formatting

26. Interaction
Join us on #pcbsd, #freenas, or #lumina-desktop
for discussion (IRC Freenode)
Be descriptive in your commit message so it
is clear what has changed and why
Be responsive to comments on pull requests

27. Resources
http://doc.pcbsd.org
http://doc.freenas.org
http://lumina-desktop.org/handbook
https://api.sysadm.us

28. Questions?
Contact:
dru@freebsd.org
URL to slides:
http://slideshare.net/dlavigne/knoxbug2016