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
65
Software Quality
awesomeincremented
1
61
Code Reviews
awesomeincremented
0
55
Coding Guidelies
awesomeincremented
0
47
Oracle Spatial 101 - An Introduction
awesomeincremented
0
110
Other Decks in Technology
See All in Technology
[OCI Skill Mapping] AWSユーザーのためのOCI(2025年8月20日開催)
oracle4engineer
PRO
2
110
Oracle Base Database Service:サービス概要のご紹介
oracle4engineer
PRO
2
20k
Yahoo!広告ビジネス基盤におけるバックエンド開発
lycorptech_jp
PRO
0
200
Yahoo!ニュースにおけるソフトウェア開発
lycorptech_jp
PRO
0
210
会社にデータエンジニアがいることでできるようになること
10xinc
9
1.5k
S3のライフサイクル設計でハマったポイント
mkumada
0
100
イオン店舗一覧ページのパフォーマンスチューニング事例 / Performance tuning example for AEON store list page
aeonpeople
1
160
我々は雰囲気で仕事をしている / How can we do vibe coding as well
naospon
2
200
Devinを使ったモバイルアプリ開発 / Mobile app development with Devin
yanzm
0
150
datadog-distribution-of-opentelemetry-collector-intro
tetsuya28
0
240
ウォンテッドリーのアラート設計と Datadog 移行での知見
donkomura
0
300
Gaze-LLE: Gaze Target Estimation via Large-Scale Learned Encoders
kzykmyzw
0
300
Featured
See All Featured
Distributed Sagas: A Protocol for Coordinating Microservices
caitiem20
333
22k
Reflections from 52 weeks, 52 projects
jeffersonlam
351
21k
Embracing the Ebb and Flow
colly
87
4.8k
Done Done
chrislema
185
16k
Optimising Largest Contentful Paint
csswizardry
37
3.4k
Understanding Cognitive Biases in Performance Measurement
bluesmoon
29
1.8k
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
44
2.4k
The Cult of Friendly URLs
andyhume
79
6.5k
The Success of Rails: Ensuring Growth for the Next 100 Years
eileencodes
46
7.6k
Why Our Code Smells
bkeepers
PRO
338
57k
Stop Working from a Prison Cell
hatefulcrawdad
271
21k
Principles of Awesome APIs and How to Build Them.
keavy
126
17k
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!