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
SCSAから学ぶセキュリティ管理
masakamayama
0
140
Ask! NIKKEI RAG検索技術の深層
hotchpotch
13
2.8k
テストアーキテクチャ設計で実現する高品質で高スピードな開発の実践 / Test Architecture Design in Practice
ropqa
3
710
High Performance PHP
cmuench
0
140
「海外登壇」という 選択肢を与えるために 〜Gophers EX
logica0419
0
500
関東Kaggler会LT: 人狼コンペとLLM量子化について
nejumi
3
460
モノレポ開発のエラー、誰が見る?Datadog で実現する適切なトリアージとエスカレーション
biwashi
6
770
Postmanを使いこなす!2025年ぜひとも押さえておきたいPostmanの10の機能
nagix
2
120
APIファーストで実現する運用性の高い IoT プラットフォーム: SORACOMのアプローチ
soracom
PRO
0
240
地方拠点で エンジニアリングマネージャーってできるの? 〜地方という制約を楽しむオーナーシップとコミュニティ作り〜
1coin
1
130
エンジニアのためのドキュメント力基礎講座〜構造化思考から始めよう〜(2025/02/15jbug広島#15発表資料)
yasuoyasuo
15
5.5k
Developers Summit 2025 浅野卓也(13-B-7 LegalOn Technologies)
legalontechnologies
PRO
0
150
Featured
See All Featured
Done Done
chrislema
182
16k
Chrome DevTools: State of the Union 2024 - Debugging React & Beyond
addyosmani
3
310
Code Reviewing Like a Champion
maltzj
521
39k
The Success of Rails: Ensuring Growth for the Next 100 Years
eileencodes
44
7k
KATA
mclloyd
29
14k
Fontdeck: Realign not Redesign
paulrobertlloyd
82
5.4k
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
rmw
33
2.8k
Intergalactic Javascript Robots from Outer Space
tanoku
270
27k
Fireside Chat
paigeccino
34
3.2k
The MySQL Ecosystem @ GitHub 2015
samlambert
250
12k
Making Projects Easy
brettharned
116
6k
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
129
19k
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!