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. Doc Like an Egyptian Dru Lavigne Documentation Lead, iXsystems FOSSETCON, November 21, 2015
  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 documentation goals and inherent difficulties Introduction to Sphinx as part of a documentation solution Disclaimer: based on my experiences. While from an open source perspective, discussion also applies to proprietary documentation.
  4. 4. In Theory....Docs: are published with each software release... in multiple formats which suit the needs/devices of that software's user base... in multiple translations which match that software's global audience... and are grammatically and technically correct... all using open source tools, of course.
  5. 5. The Reality <insert>giggles or tears here</insert> Docs are incomplete or outdated (assuming they even exist) Docs are given lower priority than code Noone wants to write docs / Noone reads docs anyways No perfect doc management solution exists (open source or proprietary)
  6. 6. Incomplete/Outdated Docs Software is a MOVING target with varying release schedules Outdated, unversioned docs are actually worse than no docs Need process for versioning docs, providing revision control, archiving older docs, and helping people find the correct docs for their software version
  7. 7. I Get No Respect Around Here... Cultural issue: docs are equally important to code and both are equally important to Q/A Know your audience and give them credit (users actually want readable/usable documentation) Train projects' question answerers to gently point users to the pertinent section of the docs and to create bug reports (or update docs) when no pertinent section exists
  8. 8. Finding the “Perfect” Tool Markup (Writing Format) Is it easy to learn or a significant barrier to entry? (e.g. WYSIWYG or wiki markup vs XML or LaTeX) Are editors available which understand the syntax? Does it support the required layout? (code excerpts, table of contents, glossary, searchability, internal and external links, indexes, images, charts, localization, notes/warnings, footnotes, etc.)
  9. 9. Finding the “Perfect” Tool Outputs (Published Format) Dru's 1st Law of Doc Tools: the number and quality of the outputs is inversely proportional to the ease of the markup language Dru's 2nd Law of Doc Tools: the fewer the number of doc maintainers, the higher the number of desired outputs Understand your audience and your project's limitations
  10. 10. Some Painful Examples doc/odt Good: WYSIWYG editor available to any author Bad: templates are painful - collaborative editing and tracking changes is often a tangled mess of emails (who has the latest version?), editing conflicts, or waiting for someone else to make their changes - outputs are limited and require various degrees of cleanup
  11. 11. Some Painful Examples wiki Good: entry barrier fairly low and syntax quick to learn Bad: no concept of ToC, content flow, or versioning - if you build it, they don't necessarily come (except for the spambots...) - outputs are very limited and typically require a lot of cleanup; translation tools are clunky
  12. 12. Some Painful Examples LaTeX Good: multiple outputs integrate well into build and translation systems Bad: very high barrier to entry as it takes a dedicated time (and interest) commitment to learn (and teach) the formatting language
  13. 13. Sphinx Features Relatively easy-to-learn formatting language Supports common outputs: HTML, PDF, ePUB, LaTeX, Texinfo, man pages, txt, API docs Provides a number of extensions (eg automatic figure numbering) Automatic generation of ToC, index, glossary Source files are text and easily integrate into existing revision control, translation, build, and CI infrastructures
  14. 14. Sphinx Features Fully customizable conf.py for controlling doc layout Several useful built-in builders (eg link checker) Several built-in themes and support for custom themes; layout fully customizable using CSS Anything can be linked (figures, keywords, headings, etc.) Writers can use any text editor on any system with Python installed (or issue git pull requests)
  15. 15. Sphinx Limitations Some odd formatting limitations require CSS workarounds (eg bold italic) Search SUCKS (and ironically there is a search engine of the same name) Documentation is limited and needs more usage examples
  16. 16. Sample Text
  17. 17. Sample HTML Output
  18. 18. Sample Pootle Interface
  19. 19. Helpful Tips What About Existing Docs? Do you plan to convert existing docs or archive those in current format and start with new docs? Open source converter utilities exist for most formats, often mutliple utilities per format Experiment by converting a small doc that contains most of your formatting requirements Expect to spend time cleaning up the conversion
  20. 20. Helpful Tips Determine Your Publishing Needs Is your goal to have the docs match a specific software version? to have only one version that is the latest and greatest? What output formats are required? Versioned PDFs? HTML on your project page? Built into the software itself as a help system?
  21. 21. Helpful Tips Review Your Code Repository You do have one, right? (if not, you need one!) Determine the required doc versioning system and where to commit your .rst files within the existing code repository Update the README.md (or equivalent) with instructions for authors to create their own doc build environment
  22. 22. Helpful Tips Create a Cheat Sheet Review your converted docs and make a list of the formatting tags and conventions used by your project Include any gotchas to help new authors quickly get up-to-speed Publish the cheat sheet (eg README.md in doc directory of repo)
  23. 23. Helpful Tips Spend some time playing with conf.py and experiment with existing themes BEFORE writing new docs (themes change the layout which may affect how you use formatting tags) Research, experiment with, and install extensions that are useful for your docs Determine how much layout customization is required and who has the CSS skills for extra customizations
  24. 24. Resources http://sphinx-doc.org/ http://pootle.translatehouse.org/
  25. 25. Questions Contact: dru@freebsd.org URL to Slides: http://slideshare.net/dlavigne/fossetcon15