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
How to make a better FM
Search
Awesome Incremented
October 09, 2015
Technology
1
450
How to make a better FM
Continuous documentation - using mkdocs, PlantUML, NPlant, salt & msbuild
Awesome Incremented
October 09, 2015
Tweet
Share
More Decks by Awesome Incremented
See All by Awesome Incremented
Fast GeoIp Lookup using Redis
awesomeincremented
0
71
Continuous License Compliance-Analysis
awesomeincremented
0
23
(Almost) Continuous Delivery with Docker in offline environments
awesomeincremented
0
23
Update on Technology Radar
awesomeincremented
0
38
Docker Build Automation with Jenkins
awesomeincremented
1
64
Software Quality
awesomeincremented
1
60
Code Reviews
awesomeincremented
0
54
Coding Guidelies
awesomeincremented
0
47
Oracle Spatial 101 - An Introduction
awesomeincremented
0
110
Other Decks in Technology
See All in Technology
250627 関西Ruby会議08 前夜祭 RejectKaigi「DJ on Ruby Ver.0.1」
msykd
PRO
2
290
Model Mondays S2E02: Model Context Protocol
nitya
0
220
あなたの声を届けよう! 女性エンジニア登壇の意義とアウトプット実践ガイド #wttjp / Call for Your Voice
kondoyuko
4
450
監視のこれまでとこれから/sakura monitoring seminar 2025
fujiwara3
11
3.9k
5min GuardDuty Extended Threat Detection EKS
takakuni
0
140
第9回情シス転職ミートアップ_テックタッチ株式会社
forester3003
0
240
強化されたAmazon Location Serviceによる新機能と開発者体験
dayjournal
2
210
2年でここまで成長!AWSで育てたAI Slack botの軌跡
iwamot
PRO
4
710
生成AI活用の組織格差を解消する 〜ビジネス職のCursor導入が開発効率に与えた好循環〜 / Closing the Organizational Gap in AI Adoption
upamune
3
2.1k
【TiDB GAME DAY 2025】Shadowverse: Worlds Beyond にみる TiDB 活用術
cygames
0
1.1k
HiMoR: Monocular Deformable Gaussian Reconstruction with Hierarchical Motion Representation
spatial_ai_network
0
110
AIのAIによるAIのための出力評価と改善
chocoyama
2
550
Featured
See All Featured
The Myth of the Modular Monolith - Day 2 Keynote - Rails World 2024
eileencodes
26
2.9k
Code Reviewing Like a Champion
maltzj
524
40k
YesSQL, Process and Tooling at Scale
rocio
173
14k
Rails Girls Zürich Keynote
gr2m
94
14k
Intergalactic Javascript Robots from Outer Space
tanoku
271
27k
How GitHub (no longer) Works
holman
314
140k
Writing Fast Ruby
sferik
628
61k
Producing Creativity
orderedlist
PRO
346
40k
Site-Speed That Sticks
csswizardry
10
660
We Have a Design System, Now What?
morganepeng
53
7.7k
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_iinuma
124
52k
How to Think Like a Performance Engineer
csswizardry
24
1.7k
Transcript
How to make a better FM Dev.Talk October 2015 Marcel
Körtgen
None
Agenda •Traditional documentation •Alternative approaches •Demo: docs as part of
the build • Architectural documentation • UI sketches •Conclusions & Perspectives
Traditional documentation Docs feedback ultra-slow, if any •Written as very
last step • if it fails, no time for a 2nd shot •“Documentation Drift” • code changes lot faster • docs maintained out of band
Alternative approaches “Build-Measure-Learn” again • introduce a feedback loop (make
it short) → put docs close to code (git) → make docs part of build process → How?
Introducing MkDocs Why Markdown? •simple plain-text → easy to integrate
(git, build, …) •decouples styling → easy to write & view •lots of tooling around...
MarkdownPad...
Visual Studio...
Dillinger.io (online)...
...or MkDocs (offline)
Architectural Documentation Guidelines → Software Guidebook (Simon Brown) → arc42
Template (in Germany) Tooling → PlantUML
Avoiding Drift UML is ... • usually one-way • suspect
to BDUF and technical drift Solution: introduce feedback loop. Again. → “Yes, this is a pattern!”
Avoiding Drift: NPlant NPlant: code-based fluent DSL for diagrams •
generates UML notation • wraps PlantUML to generate images → “Notice the irony?” build integration: compile & test
UI Prototyping with Salt Salt: PlantUML subproject @startuml salt {
Just plain text [This is my button] () Unchecked radio (X) Checked radio [] Unchecked box [X] Checked box "Enter text here " ^This is a droplist^ } @enduml
UI Prototyping with Salt Salt: plain UML! no code! Feedback?
UI Prototyping with Salt Salt: plain UML! no code! Feedback?
Demo Time Using mkdocs, plantuml, NPlant & salt https://github.com/mkoertgen/hello.NPlant
Demo Time Generating docs & diagrams as part of your
build • git clone https://github.com/mkoertgen/hello.NPlant.git • build.bat /t:Docs /v:m
Summary •Traditional documentation evolves too slow •Documentation needs to be
part of the daily build process •Code generates documentation (and not vice versa) •Markdown, PlantUML & Co. do the work for you
Some references • D.Matthews - MkDocs: Documenting projects with Markdown
(ep2015) • Architekturdokumentation mit Entwicklerwerkzeugen (jaxenter) • write-the-docs.org, EU 2014 Presentations • GitHub Pages • sphinx-doc.org
Thank You Time for Questions!