How to make a better FM

Continuous documentation - using mkdocs, PlantUML, NPlant, salt & msbuild

Transcript

1. How to make a better FM Dev.Talk October 2015 Marcel Körtgen
3. Agenda •Traditional documentation •Alternative approaches •Demo: docs as part of the build • Architectural documentation • UI sketches •Conclusions & Perspectives
4. 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
5. 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?
6. Introducing MkDocs Why Markdown? •simple plain-text → easy to integrate (git, build, …) •decouples styling → easy to write & view •lots of tooling around...
7. MarkdownPad...
8. Visual Studio...
9. Dillinger.io (online)...
10. ...or MkDocs (offline)
11. Architectural Documentation Guidelines → Software Guidebook (Simon Brown) → arc42 Template (in Germany) Tooling → PlantUML
12. Avoiding Drift UML is ... • usually one-way • suspect to BDUF and technical drift Solution: introduce feedback loop. Again. → “Yes, this is a pattern!”
13. 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
14. 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
15. UI Prototyping with Salt Salt: plain UML! no code! Feedback?
16. UI Prototyping with Salt Salt: plain UML! no code! Feedback?
17. Demo Time Using mkdocs, plantuml, NPlant & salt https://github.com/mkoertgen/hello.NPlant
18. 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
19. 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
20. 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
21. Thank You Time for Questions!