Workflow for documentation in Open Source projects

Slide 1

Slide 1 text

Workﬂow for documentation in Open Source projects Ronny Trommer https://github.com/indigo423/clt2015

Slide 2

Slide 2 text

Research project enRZet GPL freelancer OFE e.V.

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

http://goo.gl/4qw2rF

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

Wiki Docbook OpenNMS Book Let’s see … White paper

Slide 20

Slide 20 text

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

Slide 21

Slide 21 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 22

Slide 22 text

+ +

Slide 23

Slide 23 text

Link by JIRA issue number Driven by commits against branch

Slide 24

Slide 24 text

No content

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

http://xkcd.com/1285 Review for docs • Native speaker, language, grammar • Complete • Useful • Iteration on Pull Request Content

Slide 27

Slide 27 text

http://wiki.opennms.org/

Slide 28

Slide 28 text

• 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

Slide 29

Slide 29 text

git Wiki 3rd party configs Tutorials Integrations Architecture Concepts Features

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

No content

Slide 32

Slide 32 text

No content

Slide 33

Slide 33 text

No content

Slide 34

Slide 34 text

No content

Slide 35

Slide 35 text

Ascii for the win Low barrier to edit Version controlled

Slide 36

Slide 36 text

Markdown Some evaluation

Slide 37

Slide 37 text

No content

Slide 38

Slide 38 text

Maven support Allows multiple outputs Features GitHub support Themes for PDF and HTML

Slide 39

Slide 39 text

No content

Slide 40

Slide 40 text

No content

Slide 41

Slide 41 text

No content

Slide 42

Slide 42 text

OS independent Graph UML + PNG Free of charge … even commercial

Slide 43

Slide 43 text

OS independent Graph UML + PNG Free of charge … even commercial redistribution and use in automation

Slide 44

Slide 44 text

GitHub AsciiDoc JIRA establish some rules … yEd

Slide 45

Slide 45 text

http://xkcd.com/1285

Slide 46

Slide 46 text

http://xkcd.com/1285 Easier diffs Identify too long sentences Sentence beginning Less conflicts

Slide 47

Slide 47 text

No content

Slide 48

Slide 48 text

No content

Slide 49

Slide 49 text

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