We don't need no documentation

Slide 1

Slide 1 text

We don’t need no documentation. https://github.com/indigo423/ouce2015-docs

Slide 2

Slide 2 text

Motivation started as OpenNMS user Experienced the lack of docs Found friends wrote a book 2nd Edition another year?

Slide 3

Slide 3 text

Outdated It’s just wrong Explain stuff you already know Does not exist Problems with docs?

Slide 4

Slide 4 text

Outdated It’s just wrong Explain stuff you already know Problems with docs? Does not exist Informiert den Techniker!

Slide 5

Slide 5 text

Source code our documentation is! http://goo.gl/cIYrF1

Slide 6

Slide 6 text

No content

Slide 7

Slide 7 text

http://www.strangedangers.com/content/item/155295.html

Slide 8

Slide 8 text

http://www.fosterandpartners.com/projects/millau-viaduct/

Slide 9

Slide 9 text

http://whenonearth.net/cross-moses-bridge-fort-de-roovere-netherlands/

Slide 10

Slide 10 text

http://whenonearth.net/cross-moses-bridge-fort-de-roovere-netherlands/

Slide 11

Slide 11 text

Source code is the what, not the why. https://scalibq.wordpress.com/2011/07/06/source-code-is-not-documentation/

Slide 12

Slide 12 text

source code == documentation http://goo.gl/7M4YeZ

Slide 13

Slide 13 text

http://goo.gl/4qw2rF

Slide 14

Slide 14 text

Wrong understanding of documentation http://goo.gl/4qw2rF

Slide 15

Slide 15 text

Wrong understanding of documentation http://goo.gl/4qw2rF Write docs to have docs.

Slide 16

Slide 16 text

Why? http://goo.gl/7M4YeZ

Slide 17

Slide 17 text

Why? Empower people to use your software in the most efficient and right way. http://goo.gl/7M4YeZ

Slide 18

Slide 18 text

shared understanding! http://goo.gl/7M4YeZ

Slide 19

Slide 19 text

But How? shared understanding! http://goo.gl/7M4YeZ

Slide 20

Slide 20 text

Wiki Docbook OpenNMS Book Let’s see … White paper

Slide 21

Slide 21 text

Wiki Docbook OpenNMS Book Let’s see … White paper !! !!

Slide 22

Slide 22 text

User Admin Developer

Slide 23

Slide 23 text

Works in NOC Works with the WebUI Has to know about concepts User Admin Developer

Slide 24

Slide 24 text

Works in NOC Works with the WebUI Configures  OpenNMS Has to enable monitoring Has to know about concepts implements monitoring requirements User Admin Developer

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

https://github.com/OpenNMS/opennms/tree/develop/opennms-doc

Slide 27

Slide 27 text

• 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

Slide 28

Slide 28 text

git Wiki 3rd party configs Tutorials Integrations Architecture Concepts Features

Slide 29

Slide 29 text

git Wiki 3rd party configs Tutorials Integrations Architecture Concepts Features tight to a version of OpenNMS integrate my Juniper SRX 240

Slide 30

Slide 30 text

Dashboard Dashlet 1 … Dashlet n Monitors for service tests Monitor 1 … Monitor n Data collection Collector 1 … Collector n