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
72
Continuous License Compliance-Analysis
awesomeincremented
0
24
(Almost) Continuous Delivery with Docker in offline environments
awesomeincremented
0
23
Update on Technology Radar
awesomeincremented
0
39
Docker Build Automation with Jenkins
awesomeincremented
1
64
Software Quality
awesomeincremented
1
61
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
KCD Lima: eBee in Peru!
lizrice
0
110
「AI駆動開発」のボトルネック『言語化』を効率化するには
taniiicom
1
230
ecspressoの設計思想に至る道 / sekkeinight2025
fujiwara3
12
2.2k
公開初日に個人環境で試した Gemini CLI 体験記など / Gemini CLI実験レポート
you
PRO
3
1.2k
Vision Language Modelと自動運転AIの最前線_20250730
yuyamaguchi
2
880
Recoil脱却の現状と挑戦
kirik
3
490
Microsoft Learn MCP/Fabric データエージェント/Fabric MCP/Copilot Studio-簡単・便利なAIエージェント作ってみた -"Building Simple and Powerful AI Agents with Microsoft Learn MCP, Fabric Data Agent, Fabric MCP, and Copilot Studio"-
reireireijinjin6
1
190
怖くない!GritQLでBiomeプラグインを作ろうよ
pal4de
1
150
AI人生苦節10年で会得したAIがやること_人間がやること.pdf
shibuiwilliam
1
230
VLMサービスを用いた請求書データ化検証 / SaaSxML_Session_1
sansan_randd
0
150
少人数でも回る! DevinとPlaybookで支える運用改善
ishikawa_pro
5
1.9k
마라톤 끝의 단거리 스퍼트: 2025년의 AI
inureyes
PRO
1
200
Featured
See All Featured
Principles of Awesome APIs and How to Build Them.
keavy
126
17k
What’s in a name? Adding method to the madness
productmarketing
PRO
23
3.6k
Visualization
eitanlees
146
16k
Save Time (by Creating Custom Rails Generators)
garrettdimon
PRO
31
1.3k
Embracing the Ebb and Flow
colly
86
4.8k
Let's Do A Bunch of Simple Stuff to Make Websites Faster
chriscoyier
507
140k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
234
17k
Building Better People: How to give real-time feedback that sticks.
wjessup
367
19k
Large-scale JavaScript Application Architecture
addyosmani
512
110k
How to Think Like a Performance Engineer
csswizardry
25
1.8k
Agile that works and the tools we love
rasmusluckow
329
21k
Building Flexible Design Systems
yeseniaperezcruz
328
39k
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!