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
100
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
26
Docker - Hello Ground!
indigo
0
70
OSMC 2017 - Another year with OpenNMS
indigo
1
390
Run Your Own Fucking Infrastructure
indigo
0
190
Introduction to OpenNMS
indigo
0
220
We don't need no documentation
indigo
2
110
OpenNMS meets Grafana
indigo
0
600
VMware and OpenNMS in Real World
indigo
0
180
Make the net work
indigo
0
59
Other Decks in Technology
See All in Technology
Developers Summit 2025 浅野卓也(13-B-7 LegalOn Technologies)
legalontechnologies
PRO
0
150
Oracle Base Database Service 技術詳細
oracle4engineer
PRO
6
57k
まだ間に合う! エンジニアのための生成AIアプリ開発入門 on AWS
minorun365
PRO
4
580
自動テストの世界に、この5年間で起きたこと
autifyhq
10
7.1k
生成AIの利活用を加速させるための取り組み「prAIrie-dog」/ Shibuya_AI_1
visional_engineering_and_design
1
140
MC906491 を見据えた Microsoft Entra Connect アップグレード対応
tamaiyutaro
1
480
依存関係があるコンポーネントは Barrel ファイルでまとめよう
azukiazusa1
3
530
現場の種を事業の芽にする - エンジニア主導のイノベーションを事業戦略に装着する方法 -
kzkmaeda
2
1.5k
明日からできる!技術的負債の返済を加速するための実践ガイド~『ホットペッパービューティー』の事例をもとに~
recruitengineers
PRO
3
100
ハッキングの世界に迫る~攻撃者の思考で考えるセキュリティ~
nomizone
12
4.5k
Postmanを使いこなす!2025年ぜひとも押さえておきたいPostmanの10の機能
nagix
2
120
テストアーキテクチャ設計で実現する高品質で高スピードな開発の実践 / Test Architecture Design in Practice
ropqa
3
710
Featured
See All Featured
Visualizing Your Data: Incorporating Mongo into Loggly Infrastructure
mongodb
44
9.4k
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
31
2.1k
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
rmw
33
2.8k
Scaling GitHub
holman
459
140k
RailsConf 2023
tenderlove
29
1k
Art, The Web, and Tiny UX
lynnandtonic
298
20k
"I'm Feeling Lucky" - Building Great Search Experiences for Today's Users (#IAC19)
danielanewman
226
22k
Building a Modern Day E-commerce SEO Strategy
aleyda
38
7.1k
Principles of Awesome APIs and How to Build Them.
keavy
126
17k
Templates, Plugins, & Blocks: Oh My! Creating the theme that thinks of everything
marktimemedia
29
2.2k
Side Projects
sachag
452
42k
What's in a price? How to price your products and services
michaelherold
244
12k
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