O slideshow foi denunciado.
Seu SlideShare está sendo baixado. ×


Mais Conteúdo rRelacionado

Audiolivros relacionados

Gratuito durante 30 dias do Scribd

Ver tudo


  1. 1. You Too can Doc Like an Egyptian Dru Lavigne Documentation Lead, iXsystems KnoxBUG May 26, 2016
  2. 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. 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. 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. 5. What is Sphinx? Uses the reStructuredText markup syntax (.rst) http://www.sphinx-doc.org http://docutils.sourceforge.net/rst.html
  6. 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. 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. 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. 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. 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. 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. 12. Sample Layout
  13. 13. (Mostly) Formatted Sample
  14. 14. Fully Formatted HTML
  15. 15. And Its Markup
  16. 16. Getting Started on Github
  17. 17. Fork the Repo to Edit
  18. 18. Click the Edit Icon to Open the Editor
  19. 19. Use a Descriptive Commit Message
  20. 20. Create a New Pull Request
  21. 21. Review Edits
  22. 22. Again, Useful Commit Message
  23. 23. Pull Request Succeeded
  24. 24. What the Reviewer Sees
  25. 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. 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. 27. Resources http://doc.pcbsd.org http://doc.freenas.org http://lumina-desktop.org/handbook https://api.sysadm.us
  28. 28. Questions? Contact: dru@freebsd.org URL to slides: http://slideshare.net/dlavigne/knoxbug2016