Upgrade to Pro — share decks privately, control downloads, hide ads and more …

How to make a better FM

How to make a better FM

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

Awesome Incremented

October 09, 2015
Tweet

More Decks by Awesome Incremented

Other Decks in Technology

Transcript

  1. How to make a better FM Dev.Talk October 2015 Marcel

    Körtgen
  2. None
  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!