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
81
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
Docker - Hello Ground!
indigo
0
51
OSMC 2017 - Another year with OpenNMS
indigo
1
280
Run Your Own Fucking Infrastructure
indigo
0
160
Introduction to OpenNMS
indigo
0
210
We don't need no documentation
indigo
2
110
OpenNMS meets Grafana
indigo
0
560
VMware and OpenNMS in Real World
indigo
0
160
Make the net work
indigo
0
49
Monitoring Virtualization Infrastructure with OpenNMS
indigo
1
470
Other Decks in Technology
See All in Technology
Vertex AI を中心に 生成AIのアップデートを共有します
kaz1437
0
290
Janus
bkuhlmann
1
490
Java EE/Jakarta EEの現状と将来―クラウドネイティブ時代にJava EEは対応できるのか?―
takakiyo
1
130
EMとして2023年度に頑張ったこと / What we did well in FY2023 as a EM
pauli
1
160
Meta Quest 3 で動く桜マシマシ WebXR アプリを IBM Cloud Code Engine と Babylon.js で作った話
1ftseabass
PRO
0
120
VS CodeでAWSを操作しよう
smt7174
7
1.6k
Postman v10リリース後を振り返る
nagix
0
170
2024/4/26 コンピュータ歴史博物館解説告知
toshi_atsumi
0
220
Databricks における 『MLOps』
databricksjapan
2
170
GraphQL 成熟度モデルの紹介と、プロダクトに当てはめた事例 / GraphQL maturity model
mh4gf
7
1.3k
サーバー間 GraphQL と webmock-graphql の話 / server-to-server graphql and webmock-graphql
qsona
2
180
本当のAWS基礎
toru_kubota
0
490
Featured
See All Featured
The Invisible Side of Design
smashingmag
294
49k
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
116
18k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
227
16k
Designing with Data
zakiwarfel
96
4.8k
Teambox: Starting and Learning
jrom
128
8.4k
Designing Experiences People Love
moore
136
23k
What’s in a name? Adding method to the madness
productmarketing
PRO
16
2.6k
StorybookのUI Testing Handbookを読んだ
zakiyama
13
4.6k
4 Signs Your Business is Dying
shpigford
175
21k
The World Runs on Bad Software
bkeepers
PRO
61
6.7k
Pencils Down: Stop Designing & Start Developing
hursman
117
11k
Build The Right Thing And Hit Your Dates
maggiecrowley
24
2k
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