Workflow for documentation in Open Source projects

Talk given at Chemnitzer Linux-Tage 2015.

Transcript

1. Workflow for documentation in Open Source projects Ronny Trommer https://github.com/indigo423/clt2015
2. Research project enRZet GPL freelancer OFE e.V.
3. Motivation started as OpenNMS user Experienced the lack of docs Found friends wrote a book 2nd Edition another year?
4. Source code our documentation is! http://goo.gl/cIYrF1
6. http://www.strangedangers.com/content/item/155295.html
7. http://www.fosterandpartners.com/projects/millau-viaduct/
8. http://whenonearth.net/cross-moses-bridge-fort-de-roovere-netherlands/
9. http://whenonearth.net/cross-moses-bridge-fort-de-roovere-netherlands/
10. Source code is the what, not the why. https://scalibq.wordpress.com/2011/07/06/source-code-is-not-documentation/
11. source code == documentation http://goo.gl/7M4YeZ
12. http://goo.gl/4qw2rF
13. Wrong understanding of documentation http://goo.gl/4qw2rF
14. Wrong understanding of documentation http://goo.gl/4qw2rF Write docs to have docs.
15. Why? Empower people to use your software in the most efficient and right way. http://goo.gl/7M4YeZ
16. But How? shared understanding! http://goo.gl/7M4YeZ
17. Outdated It’s just wrong Explain stuff you already know Does not exist Problems with docs?
18. Outdated It’s just wrong Explain stuff you already know Does not exist Informiert den Techniker! Problems with docs?
19. Wiki Docbook OpenNMS Book Let’s see … White paper
20. Wiki Docbook OpenNMS Book Let’s see … White paper !! !!
21. • Integration in development • Define a workflow for contribution • Allow tracking of documentation issues • Integrate in review process • Add docs to your acceptance criteria • Iteration, Iteration, Iteration Treat docs as you treat source code
22. + +
23. Link by JIRA issue number Driven by commits against branch
25. http://xkcd.com/1285 Review for docs • What is written in monospace • When use italic • When use bold • Table formatting —> easier to read • JIRA links and JIRA number Formal
26. http://xkcd.com/1285 Review for docs • Native speaker, language, grammar • Complete • Useful • Iteration on Pull Request Content
27. http://wiki.opennms.org/
28. • What is really version control relevant • fast vs. slow changing • Strong related to OpenNMS version • Slice by target group - User vs. Developer • Search for patterns and components Divide and Conquer
29. git Wiki 3rd party configs Tutorials Integrations Architecture Concepts Features
30. Dashboard Dashlet 1 … Dashlet n Monitors for service tests Monitor 1 … Monitor n Data collection Collector 1 … Collector n
35. Ascii for the win Low barrier to edit Version controlled
36. Markdown Some evaluation
38. Maven support Allows multiple outputs Features GitHub support Themes for PDF and HTML
42. OS independent Graph UML + PNG Free of charge … even commercial
43. OS independent Graph UML + PNG Free of charge … even commercial redistribution and use in automation
44. GitHub AsciiDoc JIRA establish some rules … yEd
45. http://xkcd.com/1285
46. http://xkcd.com/1285 Easier diffs Identify too long sentences Sentence beginning Less conflicts
49. Credits: ! Neo4j for AsciiDoc format conventions Spring for pointing us to AsciiDoc AsciiDoctor for building the cool tool chain Friends and community members for discussions