Writing Open Source Documentation for Open Source Projects
1 like281 views
This document discusses the process of writing open source documentation, particularly focusing on SUSE's approach and tools used, such as DocBook XML and DAPS. It outlines the various types of documentation available and highlights the importance of effective collaboration and continuous integration in documentation practices. Key lessons emphasize the need for proper feedback channels, suitable tools, and the principle that documentation should be open and accessible.
Writing Open Source Documentation for Open Source Projects
- 1. Writing Open Source Documentation for Open Source Projects How SUSE® is documented and what we can learn from it Christoph Wickert Technical Writer SUSE Linux GmbH Christoph.Wickert@suse.com
- 2. 10 WHOAMI Christoph Wickert • 1999: Linux user • 2005: FLOSS Contributor – Fedora – Xfce – LXDE – OLPC • 2010: Senior Engineer at Kolab Systems • 2016: Technical Documentation Writer at SUSE
- 4. 12 WHAT DO WE WANT?
- 5. Documentation Overview Available from SUSE website: https://www.suse.com/doc
- 6. 14 Documentation Overview Official SUSE Product documentation • Getting Started • Quick Install Guides • Deployment Guides • User Guides • Administrator Guides • Tuning Guides • Release Notes • Virtualization Guide • …
- 7. 15 TOOLCHAIN
- 8. 16 TOOLCHAIN – DOCBOOK XML DocBook • Semantic markup language for technical documentation • Originally intended for technical documents related to computer hardware and software • Can be used for any other sort of documentation DocBook XML • Based on the eXtensible Markup Language (XML) • Defines content in semantic way similar to HTML • Written as a schema which fulfills two tasks: guided editing and validation • http://docbook.org/
- 11. 19 TOOLCHAIN – DAPS DAPS examples • daps validate • daps pdf (--greyscale) | html (--single) • daps man | text | mobi | epub | webhelp • daps spellcheck • daps stylecheck • daps xmlformat • daps images • daps optipng
- 12. 20 TOOLCHAIN – DAPS Advanced daps commands • Find out in which files a certain ID is used daps -d <dc-file> list-file --rootid art.daps.quick • Print a list of all images with modification date daps -d <dc-file> getimages --modified • … and show them in a viewer daps -d <dc-file> getimages --modified --show --viewer ristretto
- 13. TOOLCHAIN – DAPS SUSE-specific commands • Generate a “localization drop” for translation daps locdrop • Unpack translated drop file daps unpack-lockdrop • Generate online documentation for the SUSE Website daps onlinedoc
- 14. TOOLCHAIN – SUSE XSLT STYLESHEETS Define the layout for SUSE documentation • Books: Manuals, Guides • Articles: Quick Starts, SUSE Best Practices, Shorter Guides • HTML pages (for all kind of documentation) Package: suse-xsl-stylesheets Book / Manual Article HTML
- 15. TOOLCHAIN – SUSE STYLE GUIDE
- 16. TOOLCHAIN – STYLE CHECKER Stylechecker • Checks whether the SUSE Styleguide guidelines are followed • Package suse-doc-style-checker
- 17. TOOLCHAIN – ADDITIONAL TOOLS Yet more tools • dapsenv – Continuous integration with docker • dbxinluder – Transclusions for DocBook with XInclude 1.1 • docmanager – Manages DocBook 5 Meta Information • docstats – Statistics and Metrics for Documentation Team • geekodoc – RELAX NG Schema for SUSE Documentation • xmldiffng – Diffing XML with RELAX NG schema Everything available from https://github.com/openSUSE/
- 18. 26 PROCESS
- 19. PROCESS – GITHUB
- 20. PROCESS – GIT WORKFLOW • ‘Successful git branching modell’ by Vincent Driessen • Development happens in develop • Master branch is only used for releases • Separate branches for – Features: feature/fate#12345 – Bugfixes: bugfix/bsc#123456 – Maintenance: maintenance/SLE12 • Constant naming with git-flow-avh • Merges through GitHub reviews • More info: http://nvie.com/posts/a-successful-git-branching-model/
- 21. PROCESS – OVERVIEW • Input comes through – FATE (Feature And Enhancement Tracker) – Bugzilla – DocComments • Evaluation & Planning • Research (with developers) • Documentation (Magic happens here!) • Feedback (from developers) • Translation • Publication
- 22. Report a bug PROCESS – FEEDBACK Provide comments and feedback
- 23. 32 PROBLEMS
- 24. PROBLEMS We have achieved a lot, still there are problems we need to solve • Continuous integration • Stuck in the Waterfall – Short time frame between when a feature is ready for testing/documenting and release • Decoupled from Development – Both feature and bug :-) – High coordination effort • Monolithic – High maintenance costs
- 26. 35 Docs or it didn’t happen!
- 27. 36 Developers should not write docs!
- 28. 37 You need feedback channels!
- 29. 38 You need (the right) tools!
- 30. 39 Start small!
- 31. 41 Documentation should be open!