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
410
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
56
Continuous License Compliance-Analysis
awesomeincremented
0
15
(Almost) Continuous Delivery with Docker in offline environments
awesomeincremented
0
16
Update on Technology Radar
awesomeincremented
0
35
Docker Build Automation with Jenkins
awesomeincremented
1
56
Software Quality
awesomeincremented
1
53
Code Reviews
awesomeincremented
0
50
Coding Guidelies
awesomeincremented
0
40
Oracle Spatial 101 - An Introduction
awesomeincremented
0
97
Other Decks in Technology
See All in Technology
オーナーシップを持つ領域を明確にする
konifar
13
3.2k
推しは推せるときに推せ! プロダクトにフィードバックしていこう
nakasho
0
320
Building Dashboards as a Hobby
egmc
0
230
ExaDB-D dbaascli で出来ること
oracle4engineer
PRO
0
2.1k
家族アルバム みてねにおけるGrafana活用術 / Grafana Meetup Japan Vol.1 LT
isaoshimizu
1
770
LayerXにおけるLLMプロダクト開発の今までとこれから
layerx
PRO
1
370
Cracking the KubeCon CfP
inductor
2
250
Janus
bkuhlmann
1
490
Delivering Millions of Messages within seconds @ Duolingo
pelelgrino
0
350
Azure Container Apps + Bicep 〜 こんな感じで運用しています
kaz29
2
480
地理空間データ可視化・解析・活用ソリューション Pacific Spatial Solutions (PSS)
pacificspatialsolutions
0
290
IaCジェネレーターとBedrockで詳細設計書を生成してみた
tsukasa_ishimaru
1
280
Featured
See All Featured
The World Runs on Bad Software
bkeepers
PRO
61
6.7k
Atom: Resistance is Futile
akmur
259
25k
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
kevinliebholz
2
3.4k
The Art of Programming - Codeland 2020
erikaheidi
42
12k
Agile that works and the tools we love
rasmusluckow
325
20k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
244
20k
"I'm Feeling Lucky" - Building Great Search Experiences for Today's Users (#IAC19)
danielanewman
221
21k
Designing Experiences People Love
moore
136
23k
JavaScript: Past, Present, and Future - NDC Porto 2020
reverentgeek
40
4.4k
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
125
32k
Git: the NoSQL Database
bkeepers
PRO
422
63k
How to train your dragon (web standard)
notwaldorf
73
5.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!