Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Sign up for free
Menu
Search
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Pricing
Search
Sign in
Sign up for free
Workflow for documentation in Open Source projects
Search
Sponsored
·
Ship Features Fearlessly
Turn features on and off without deploys. Used by thousands of Ruby developers.
→
Ronny Trommer
February 15, 2016
Technology
140
0
Share
Embed
Copy iframe code
Copy JS code
Copy link
Start on current slide
Workflow for documentation in Open Source projects
Talk given at Chemnitzer Linux-Tage 2015.
Ronny Trommer
February 15, 2016
Transcript
49 slides
Workflow for documentation in Open Source projects Ronny Trommer https://github.com/indigo423/clt2015
Research project enRZet GPL freelancer OFE e.V.
Motivation started as OpenNMS user Experienced the lack of docs
Found friends wrote a book 2nd Edition another year?
Source code our documentation is! http://goo.gl/cIYrF1
None
http://www.strangedangers.com/content/item/155295.html
http://www.fosterandpartners.com/projects/millau-viaduct/
http://whenonearth.net/cross-moses-bridge-fort-de-roovere-netherlands/
http://whenonearth.net/cross-moses-bridge-fort-de-roovere-netherlands/
Source code is the what, not the why. https://scalibq.wordpress.com/2011/07/06/source-code-is-not-documentation/
source code == documentation http://goo.gl/7M4YeZ
http://goo.gl/4qw2rF
Wrong understanding of documentation http://goo.gl/4qw2rF
Wrong understanding of documentation http://goo.gl/4qw2rF Write docs to have docs.
Why? Empower people to use your software in the most
efficient and right way. http://goo.gl/7M4YeZ
But How? shared understanding! http://goo.gl/7M4YeZ
Outdated It’s just wrong Explain stuff you already know Does
not exist Problems with docs?
Outdated It’s just wrong Explain stuff you already know Does
not exist Informiert den Techniker! Problems with docs?
Wiki Docbook OpenNMS Book Let’s see … White paper
Wiki Docbook OpenNMS Book Let’s see … White paper !!
!!
• 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
+ +
Link by JIRA issue number Driven by commits against branch
None
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
http://xkcd.com/1285 Review for docs • Native speaker, language, grammar •
Complete • Useful • Iteration on Pull Request Content
http://wiki.opennms.org/
• 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
git Wiki 3rd party configs Tutorials Integrations Architecture Concepts Features
Dashboard Dashlet 1 … Dashlet n Monitors for service tests
Monitor 1 … Monitor n Data collection Collector 1 … Collector n
None
None
None
None
Ascii for the win Low barrier to edit Version controlled
Markdown Some evaluation
None
Maven support Allows multiple outputs Features GitHub support Themes for
PDF and HTML
None
None
None
OS independent Graph UML + PNG Free of charge …
even commercial
OS independent Graph UML + PNG Free of charge …
even commercial redistribution and use in automation
GitHub AsciiDoc JIRA establish some rules … yEd
http://xkcd.com/1285
http://xkcd.com/1285 Easier diffs Identify too long sentences Sentence beginning Less
conflicts
None
None
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
More Decks by Ronny Trommer
See All by Ronny Trommer
Netflow mit OpenNMS
indigo
0
93
Docker - Hello Ground!
indigo
0
110
OSMC 2017 - Another year with OpenNMS
indigo
1
540
Run Your Own Fucking Infrastructure
indigo
0
260
Introduction to OpenNMS
indigo
0
280
We don't need no documentation
indigo
2
150
OpenNMS meets Grafana
indigo
0
670
VMware and OpenNMS in Real World
indigo
0
240
Make the net work
indigo
0
90
Other Decks in Technology
See All in Technology
メール到達性を支える、リンク先URLのドメイン評価の扱い方
wind111
0
140
AI時代における医療情報システムのセキュリティ / Security of Healthcare IT Systems in the AI Era
henryofficial
0
190
アラートを見直していたら営業組織への理解にちょっとだけ繋がった話
z63d
1
210
Re:ゼロから始めるシェアハウスのペットな鯖
silmin_
0
240
20261113_JAWS_Osaka
takuyay0ne
1
580
Context != Context: One window, many lifecycles (AI Native DevCon, Nov 2026)
birgitta410
0
160
少ない人手 限られた予算 それでも守る 消せない・見つける・戻れる オールハザード型BCP on AWS / 20261107 Mitsutoshi Matsuo
shift_evolve
PRO
0
410
異夢同船〜異なる夢でも同じ船でなんとかする〜
fortegp05
1
500
パスワードのない鍵で、 データを手元に置く
ginjihayashi
0
280
CloudTrail を推したい
kazzpapa3
1
130
目を覚ませ!僕らの認証情報が何者かに侵略されてるぞ
tkito
2
450
SORACOM × AWS IoT Core でSREする
butadora
0
110
Featured
See All Featured
Building the Perfect Custom Keyboard
takai
2
960
Rails Girls Zürich Keynote
gr2m
96
14k
The browser strikes back
jonoalderson
0
2k
Dealing with People You Can't Stand - Big Design 2015
cassininazir
367
27k
brightonSEO & MeasureFest 2025 - Winning Strategies for Black Friday CRO & PPC - Christian Goodrich
cargoodrich
3
900
Testing 201, or: Great Expectations
jmmastey
46
8.4k
Facilitating Awesome Meetings
lara
57
7.2k
WENDY [Excerpt]
tessaabrams
15
41k
Design in an AI World
tapps
1
390
Design of three-dimensional binary manipulators for pick-and-place task avoiding obstacles (IECON2024)
konakalab
0
660
A better future with KSS
kneath
240
18k
Efficient Content Optimization with Google Search Console & Apps Script
katarinadahlin
PRO
1
990