The Manifesto for Agile Software Development states “Working software over comprehensive documentation” and for a long time many teams and individuals have taken this to mean that we don’t need to document our software.
Writing documentation can be hard. Not everyone is a fantastic wordsmith, especially in the development community where, mostly, we just want to build stuff. However, the same manifesto also states “Individuals and interactions over processes and tools”. What better way to enable individuals than to have decent documentation. Documentation that points you in the right direction, that explains things in ways that the code never can. Documentation that records design decisions so that those same interactions flow well.
Simon Brown, in his book “Visualising Software Architecture“, and Patrick Kua in his talk “Travel Guide to Software Systems” both advocate a “travel guide” style set of documentation. They argue that context setting is a necessary component of software development in much the same way that you would use a travel guide and map as a way to orient yourself in a city or country that you are unfamiliar with.
The travel guide concept is useful because it suggests a lightweight approach; something to get you started on your journey. An entry point into the tangled mess of an unknown software application. It can outline areas to watch out for. It can serve as a reminder for those who have travelled there before, including ourselves since we can often forget where we’ve been in this modern world of multi-tasking on projects.
What are the best things to document? Simon Brown suggests at a minimum you should include the following:
Start by imagining that you were on-boarding new people to the project. What do you think they need to know? Create answers to those questions and build up the documentation as you go. Make sure everyone is involved and above all remember to keep it light, exposing the essential details.
Don’t forget the documentation.