27–29 September 2017, Churchill College, Cambridge

How to write minimum viable documentation

A 90 minute Case Study by:

Peter Hilton

Peter Hilton Consulting

About this Case Study

"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:

  • development management: agile documentation planning and risk reduction for developers and writers
  • documentation requirements: understanding why we need system documentation
  • content guidelines: deciding what to document and discovering the responsible minimum
  • technical writing: learning basic techniques for effective writing
  • documentation types: comparing essential documentation with special-purpose docs
  • production pipelines: using tools to publish software documentation with continuous integration

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.

About the Speaker

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.


Tickets are available now

buy tickets

See the full programme

full programme

Join our mailing list

We respect your email privacy

Agile Cambridge was organised by Software Acumen, based in Cambridge, England. We build communities to help technology professionals grow.

© 2013-2021 Software Acumen. Agile Cambridge and the Agile Cambridge logos are trademarks of Software Acumen LTD.

Software Acumen Limited | Registered in Cardiff | Registration No. 05210967 | VAT No. 896 7958 26