We don't need no documentation

Using complex software requires documentation. This talk is about why documentation is essential and the developers dream about auto-generated documentation. The OpenNMS project tries to solve problems in this area since 15 years and people in the community tried different approaches. This is an experience talk what the project tried and why it does documentation today differently. Especially the circumstance working in a free project working with volunteers is challenging and needs to be addressed. This talk will give an insight view about ideas how to separate types of documentation, establishing workflows to get them back under control and empower people to contribute.

Talk: http://cfp.opennms.eu/en/ouce2015/public/events/104

Transcript

1. We don’t need no documentation. https://github.com/indigo423/ouce2015-docs
2. Motivation started as OpenNMS user Experienced the lack of docs Found friends wrote a book 2nd Edition another year?
3. Outdated It’s just wrong Explain stuff you already know Does not exist Problems with docs?
4. Outdated It’s just wrong Explain stuff you already know Problems with docs? Does not exist Informiert den Techniker!
5. Source code our documentation is! http://goo.gl/cIYrF1
7. http://www.strangedangers.com/content/item/155295.html
8. http://www.fosterandpartners.com/projects/millau-viaduct/
9. http://whenonearth.net/cross-moses-bridge-fort-de-roovere-netherlands/
10. http://whenonearth.net/cross-moses-bridge-fort-de-roovere-netherlands/
11. Source code is the what, not the why. https://scalibq.wordpress.com/2011/07/06/source-code-is-not-documentation/
12. source code == documentation http://goo.gl/7M4YeZ
13. http://goo.gl/4qw2rF
14. Wrong understanding of documentation http://goo.gl/4qw2rF
15. Wrong understanding of documentation http://goo.gl/4qw2rF Write docs to have docs.
16. Why? http://goo.gl/7M4YeZ
17. Why? Empower people to use your software in the most efficient and right way. http://goo.gl/7M4YeZ
18. shared understanding! http://goo.gl/7M4YeZ
19. But How? shared understanding! http://goo.gl/7M4YeZ
20. Wiki Docbook OpenNMS Book Let’s see … White paper
21. Wiki Docbook OpenNMS Book Let’s see … White paper !! !!
22. User Admin Developer
23. Works in NOC Works with the WebUI Has to know about concepts User Admin Developer
24. Works in NOC Works with the WebUI Configures
 OpenNMS Has to enable monitoring Has to know about concepts implements monitoring requirements User Admin Developer
25. Works in NOC Works with the WebUI Configures
 OpenNMS Has to enable monitoring Has to know about concepts implements monitoring requirements Implements new features Fixes bugs Enhance the framework User Admin Developer
26. https://github.com/OpenNMS/opennms/tree/develop/opennms-doc
27. • 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
28. git Wiki 3rd party configs Tutorials Integrations Architecture Concepts Features
29. git Wiki 3rd party configs Tutorials Integrations Architecture Concepts Features tight to a version of OpenNMS integrate my Juniper SRX 240
30. Dashboard Dashlet 1 … Dashlet n Monitors for service tests Monitor 1 … Monitor n Data collection Collector 1 … Collector n
36. docs.opennms.org lists.sourceforge.net/lists/listinfo/opennms-docs