Introduction to agile documentation

Talk within the newcomer track at JavaLand 2016

Transcript

1. INTRODUCTION TO AGILE DOCUMENTATION Daniel Grycman / bilstein group, Ennepetal / @danielgrycman
2. ABOUT ME Software Developer & Consultant at Ferdinand Bilstein GmbH + Co. KG, Ennepetal Specialist for Dynamic Publishing Processes, Atlassian Stack 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
5. CENTRAL SERVICE SOLUTIONS Data Maintenance Division System Development Division
6. 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
7. DOCUMENTING WITH AN AGILE MINDSET 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
8. WHY DOCUMENT? Needed for what purpose? Target audience? Use of documentation?
9. WHAT TO DOCUMENT?
10. BEFORE THE PROJECT STARTS Technical view High-level architecture diagrams Functional view Main epics to identify the main characteristics of the development case
11. DURING THE PROJECT
12. DURING THE PROJECT / TECHNICAL VIEW Test-Driven Development (TDD) Behaviour-Driven Development (BDD) Well structured code Code as documentation
13. DURING THE PROJECT / FUNCTIONAL VIEW User story as requirements for developers with well-defined, clear in meaning acceptance criteria Acceptance criteria as documentation
14. AFTER IMPLEMENTATION AND ROLLOUT
15. AFTER IMPLEMENTATION AND ROLLOUT / TECHNICAL VIEW Code as technical documentation
16. AFTER IMPLEMENTATION AND ROLLOUT / FUNCTIONAL VIEW Code as living documentation
17. WHERE TO DOCUMENT? Accessible and updatable repository
18. WHEN TO DOCUMENT? Produce documentation incrementally Evolve documentation along with the development
19. ASCIIDOC(TOR) Ruby implementation of python-based Asciidoc interpreter Asciidoc is a lightweight markup language Single source publishing toolchain
20. JBAKE — Dan Allen Jekyll of the JVM
21. JBAKE originally a static site / blog generator support of several template engine implementable in a build pipeline
22. DEMO TIME
24. REFERENCES Images 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
25. Generated with Asciidoctor v1.5.4.