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
440
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
66
Continuous License Compliance-Analysis
awesomeincremented
0
23
(Almost) Continuous Delivery with Docker in offline environments
awesomeincremented
0
20
Update on Technology Radar
awesomeincremented
0
37
Docker Build Automation with Jenkins
awesomeincremented
1
62
Software Quality
awesomeincremented
1
57
Code Reviews
awesomeincremented
0
53
Coding Guidelies
awesomeincremented
0
45
Oracle Spatial 101 - An Introduction
awesomeincremented
0
110
Other Decks in Technology
See All in Technology
依存関係があるコンポーネントは Barrel ファイルでまとめよう
azukiazusa1
3
530
マルチモーダル理解と生成の統合 DeepSeek Janus, etc... / Multimodal Understanding and Generation Integration
hiroga
0
360
目の前の仕事と向き合うことで成長できる - 仕事とスキルを広げる / Every little bit counts
soudai
22
5.8k
The 5 Obstacles to High-Performing Teams
mdalmijn
0
270
現場の種を事業の芽にする - エンジニア主導のイノベーションを事業戦略に装着する方法 -
kzkmaeda
2
1.5k
Datadogとともにオブザーバビリティを布教しよう
mego2221
0
130
現場で役立つAPIデザイン
nagix
29
10k
トラシューアニマルになろう ~開発者だからこそできる、安定したサービス作りの秘訣~
jacopen
2
1.5k
データ資産をシームレスに伝達するためのイベント駆動型アーキテクチャ
kakehashi
PRO
2
230
SCSAから学ぶセキュリティ管理
masakamayama
0
140
データ基盤の成長を加速させる:アイスタイルにおける挑戦と教訓
tsuda7
3
650
High Performance PHP
cmuench
0
140
Featured
See All Featured
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
31
2.1k
The Straight Up "How To Draw Better" Workshop
denniskardys
232
140k
Rails Girls Zürich Keynote
gr2m
94
13k
Fashionably flexible responsive web design (full day workshop)
malarkey
406
66k
Site-Speed That Sticks
csswizardry
3
370
The Cult of Friendly URLs
andyhume
78
6.2k
Performance Is Good for Brains [We Love Speed 2024]
tammyeverts
7
630
No one is an island. Learnings from fostering a developers community.
thoeni
21
3.1k
Easily Structure & Communicate Ideas using Wireframe
afnizarnur
193
16k
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
132
33k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
231
53k
Intergalactic Javascript Robots from Outer Space
tanoku
270
27k
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!