introduction to agile documentation
TRANSCRIPT
INTRODUCTION TOAGILE
DOCUMENTATIONDaniel Grycman / bilstein group, Ennepetal / @danielgrycman
ABOUT MESoftware Developer & Consultant at Ferdinand BilsteinGmbH + Co. KG, Ennepetal
Specialist for Dynamic Publishing Processes, AtlassianStack Development & Integration
Interests: IDEs & Tools, Documentation as part of SDLC,Docker, Microservice based architectures
Member of the organizing team of ruhrJUG in Essen
Local organizer of Docker Meetup Bochum
CENTRAL SERVICE SOLUTIONSData Maintenance Division
System Development Division
AGILE MANIFESTO
Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
DOCUMENTING WITH AN AGILEMINDSET
No rigid guidelines on how to document
Focus on delivering value to the customer
Rethinking the way to document
Adapting the change
Documentation should occur when necessary
WHY DOCUMENT?Needed for what purpose?
Target audience?
Use of documentation?
WHAT TO DOCUMENT?
BEFORE THE PROJECT STARTSTechnical view
High-level architecture diagrams
Functional view
Main epics to identify the main characteristics of thedevelopment case
DURING THE PROJECT
DURING THE PROJECT / TECHNICALVIEW
Test-Driven Development (TDD)
Behaviour-Driven Development (BDD)
Well structured code
Code as documentation
DURING THE PROJECT /FUNCTIONAL VIEW
User story as requirements for developers
with well-defined, clear in meaning acceptance criteria
Acceptance criteria as documentation
AFTER IMPLEMENTATION ANDROLLOUT
AFTER IMPLEMENTATION ANDROLLOUT / TECHNICAL VIEW
Code as technical documentation
AFTER IMPLEMENTATION ANDROLLOUT / FUNCTIONAL VIEW
Code as living documentation
WHERE TO DOCUMENT?Accessible and updatable repository
WHEN TO DOCUMENT?Produce documentation incrementally
Evolve documentation along with the development
ASCIIDOC(TOR)Ruby implementation of python-based Asciidocinterpreter
Asciidoc is a lightweight markup language
Single source publishing toolchain
JBAKE
— Dan Allen
Jekyll of the JVM
JBAKEoriginally a static site / blog generator
support of several template engine
implementable in a build pipeline
DEMO TIME
REFERENCESImages copyright by Bilstein Group, Ennepetal expect of:
building_blocks.jpg — Björn Egil Johansen
notebook_with_pencils — Matt Carnock
plane_start.jpg — Bernal Saborio / berkuspic
route.jpg — Over Doz
scrum_cycle.jpg — Oliver Tacke
signpost.jpg — Chris Blakeley
Generated with Asciidoctor v1.5.4.