"At least with waterfall, we knew what documentation to write."
Software documentation remains agile software development’s neglected problem. Development teams rightly avoid the waste that accompanies legacy documentation practices, but often fail to apply lean principles and avoid the problems of inadequate documents. Development teams need minimum viable documentation. The solution is to improve basic technical writing skills, integrate documentation with agile software development methods, and learn about modern tools. This workshop’s topics include:
This workshop teaches how to produce documentation in line with agile principles. You will learn to write and publish effective documentation with less effort, and develop a long-term skill. This benefits all software development teams, because good system documentation is a universal software requirement.
The workshop is based on a number of 20-minute sessions. Each session includes a group discussion or exercise, and the workshop ends with a short wrap-up.
Agile software development practitioners, in general, are wary of time spent on documentation, because it adds overhead to software delivery. Documentation is waste.
This leaves us with a problem. We prioritise working software over comprehensive documentation, but we still need software documentation in practice. After all, software documentation is a kind of insurance against needing information in the future and not already having it in your head. The trouble is, we don’t have a shared understanding of how to approach documentation.
As John Wanamaker might have said, "Half the money I spend on documentation is wasted; the trouble is I don't know which half." Agile software development methods rightly focus on developing the software, and typically ignore secondary needs such as documentation. "At least with waterfall we knew what documentation to write," they say.
The first step in solving the agile documentation problem is learning how to write the minimum viable documentation. My workshop teaches what to document and what not to, starting with README Driven Development. You will learn about setting goals, defining the essential structure, basic technical writing skills, and how to incorporate all of this into agile software development.
Peter Hilton is a software developer, writer, speaker, trainer and musician. His professional interests are business process management, web application development, functional design, software development methodology, agile methods, project management and software documentation.
Peter currently works as a product developer and technical writer for Signavio, working remotely from Rotterdam, and delivers the occasional lecture and training course. He has presented at many European developer conferences, including Joy of Coding, ACCU, Scala eXchange, Devoxx, Øredev, Jfokus, Javazone, geecon and TopConf. Peter co-authored the book Play for Scala (Manning Publications) and has taught the Fast Track to Play with Scala training course.