How to make a better FM
Dev.Talk
October 2015
Marcel Körtgen
Slide 2
Slide 2 text
No content
Slide 3
Slide 3 text
Agenda
•Traditional documentation
•Alternative approaches
•Demo: docs as part of the build
• Architectural documentation
• UI sketches
•Conclusions & Perspectives
Slide 4
Slide 4 text
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
Slide 5
Slide 5 text
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?
Slide 6
Slide 6 text
Introducing MkDocs
Why Markdown?
•simple plain-text → easy to integrate (git, build, …)
•decouples styling → easy to write & view
•lots of tooling around...
Avoiding Drift
UML is ...
• usually one-way
• suspect to BDUF and technical drift
Solution: introduce feedback loop. Again.
→ “Yes, this is a pattern!”
Slide 13
Slide 13 text
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
Slide 14
Slide 14 text
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
Slide 15
Slide 15 text
UI Prototyping with Salt
Salt: plain UML! no code! Feedback?
Slide 16
Slide 16 text
UI Prototyping with Salt
Salt: plain UML! no code! Feedback?
Slide 17
Slide 17 text
Demo Time
Using mkdocs, plantuml, NPlant & salt
https://github.com/mkoertgen/hello.NPlant
Slide 18
Slide 18 text
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
Slide 19
Slide 19 text
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
Slide 20
Slide 20 text
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