Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Speaker Deck
PRO
Sign in
Sign up for free
How to make a better FM
Awesome Incremented
October 09, 2015
Technology
1
360
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
41
Continuous License Compliance-Analysis
awesomeincremented
0
10
(Almost) Continuous Delivery with Docker in offline environments
awesomeincremented
0
11
Update on Technology Radar
awesomeincremented
0
29
Docker Build Automation with Jenkins
awesomeincremented
1
50
Software Quality
awesomeincremented
1
46
Code Reviews
awesomeincremented
0
46
Coding Guidelies
awesomeincremented
0
35
Oracle Spatial 101 - An Introduction
awesomeincremented
0
86
Other Decks in Technology
See All in Technology
20230121_BuriKaigi
oyakata2438
0
180
データベースの発表には RDBMS 以外もありますよ
maroon1st
0
230
Periodic Multi-Agent Path Planning
hziwara
0
110
230125 モニターマウントLT ITガジェット翁(Ryu.Cyber)さん
comucal
PRO
0
4.6k
Optimizing your Swift code
kateinoigakukun
0
1.4k
OCI技術資料 : ロード・バランサー 詳細 / Load Balancer 200
ocise
2
7.2k
03_ユーザビリティテスト
kouzoukaikaku
0
330
- Rでオブジェクト指向プログラミング- クラス設計入門の入門
kotatyamtema
1
720
Deep Neural Networkの共同学習
hf149
0
160
01_ユーザーリサーチ実施の進め方
kouzoukaikaku
0
350
NGINXENG JP#2 - 4-NGINX-エンジニアリング勉強会
hiropo20
0
110
SRE Lounge 2023/SRE Lounge 2023
lmi
1
340
Featured
See All Featured
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
rmw
22
1.7k
Fashionably flexible responsive web design (full day workshop)
malarkey
396
63k
Intergalactic Javascript Robots from Outer Space
tanoku
261
26k
The Web Native Designer (August 2011)
paulrobertlloyd
76
2.2k
実際に使うSQLの書き方 徹底解説 / pgcon21j-tutorial
soudai
44
14k
Art Directing for the Web. Five minutes with CSS Template Areas
malarkey
196
9.8k
Docker and Python
trallard
30
1.9k
ParisWeb 2013: Learning to Love: Crash Course in Emotional UX Design
dotmariusz
101
6.2k
Writing Fast Ruby
sferik
613
58k
Building an army of robots
kneath
301
40k
Atom: Resistance is Futile
akmur
256
24k
How STYLIGHT went responsive
nonsquared
89
4.2k
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!