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
地方拠点で エンジニアリングマネージャーってできるの? 〜地方という制約を楽しむオーナーシップとコミュニティ作り〜
1coin
1
130
第13回 Data-Centric AI勉強会, 画像認識におけるData-centric AI
ksaito_osx
0
360
飲食店予約台帳を支えるインタラクティブ UI 設計と実装
siropaca
6
1.4k
現場の種を事業の芽にする - エンジニア主導のイノベーションを事業戦略に装着する方法 -
kzkmaeda
2
1.5k
WAF に頼りすぎない AWS WAF 運用術 meguro sec #1
izzii
0
460
技術的負債解消の取り組みと専門チームのお話 #技術的負債_Findy
bengo4com
1
1.2k
30分でわかる『アジャイルデータモデリング』
hanon52_
9
2.2k
Googleマップ/Earthが一般化した 地図タイルのイマ
mapconcierge4agu
1
200
FastConnect の冗長性
ocise
1
9.6k
依存関係があるコンポーネントは Barrel ファイルでまとめよう
azukiazusa1
3
530
事業継続を支える自動テストの考え方
tsuemura
0
300
インフラをつくるとはどういうことなのか、 あるいはPlatform Engineeringについて
nwiizo
5
2.1k
Featured
See All Featured
Embracing the Ebb and Flow
colly
84
4.6k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
231
53k
Practical Tips for Bootstrapping Information Extraction Pipelines
honnibal
PRO
12
950
Designing for humans not robots
tammielis
250
25k
Docker and Python
trallard
44
3.3k
Building Better People: How to give real-time feedback that sticks.
wjessup
366
19k
Build The Right Thing And Hit Your Dates
maggiecrowley
34
2.5k
The Art of Delivering Value - GDevCon NA Keynote
reverentgeek
10
1.3k
Speed Design
sergeychernyshev
25
780
Automating Front-end Workflow
addyosmani
1367
200k
What’s in a name? Adding method to the madness
productmarketing
PRO
22
3.3k
Done Done
chrislema
182
16k
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