Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
Workflow for documentation in Open Source projects
Search
Ronny Trommer
February 15, 2016
Technology
0
110
Workflow for documentation in Open Source projects
Talk given at Chemnitzer Linux-Tage 2015.
Ronny Trommer
February 15, 2016
Tweet
Share
More Decks by Ronny Trommer
See All by Ronny Trommer
Netflow mit OpenNMS
indigo
0
53
Docker - Hello Ground!
indigo
0
82
OSMC 2017 - Another year with OpenNMS
indigo
1
460
Run Your Own Fucking Infrastructure
indigo
0
220
Introduction to OpenNMS
indigo
0
240
We don't need no documentation
indigo
2
120
OpenNMS meets Grafana
indigo
0
610
VMware and OpenNMS in Real World
indigo
0
200
Make the net work
indigo
0
67
Other Decks in Technology
See All in Technology
AIエージェントによる業務効率化への飽くなき挑戦-AWS上の実開発事例から学んだ効果、現実そしてギャップ-
nasuvitz
5
1.3k
20251027_findyさん_音声エージェントLT
almondo_event
2
450
ラスベガスの歩き方 2025年版(re:Invent 事前勉強会)
junjikoide
0
220
IoTLT@ストラタシスジャパン_20251021
norioikedo
0
140
dbtとAIエージェントを組み合わせて見えたデータ調査の新しい形
10xinc
2
620
様々なファイルシステム
sat
PRO
0
250
ブラウザのAPIで Nintendo Switch用の特殊なゲーム用コントローラーを体験型コンテンツに / IoTLT @ストラタシス・ジャパン
you
PRO
0
140
Azureコストと向き合った、4年半のリアル / Four and a half years of dealing with Azure costs
aeonpeople
1
300
可観測性は開発環境から、開発環境にもオブザーバビリティ導入のススメ
layerx
PRO
2
860
プロダクト開発と社内データ活用での、BI×AIの現在地 / Data_Findy
sansan_randd
0
190
MCP ✖️ Apps SDKを触ってみた
hisuzuya
0
380
激動の時代を爆速リチーミングで乗り越えろ
sansantech
PRO
1
110
Featured
See All Featured
Dealing with People You Can't Stand - Big Design 2015
cassininazir
367
27k
The Language of Interfaces
destraynor
162
25k
Agile that works and the tools we love
rasmusluckow
331
21k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
234
17k
Fantastic passwords and where to find them - at NoRuKo
philnash
52
3.5k
Statistics for Hackers
jakevdp
799
220k
How to Create Impact in a Changing Tech Landscape [PerfNow 2023]
tammyeverts
55
3k
[RailsConf 2023] Rails as a piece of cake
palkan
57
5.9k
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
34
2.5k
Chrome DevTools: State of the Union 2024 - Debugging React & Beyond
addyosmani
9
930
Intergalactic Javascript Robots from Outer Space
tanoku
272
27k
Designing for Performance
lara
610
69k
Transcript
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