Peter Hilton

Software Developer

Peter Hilton is a product manager, developer, writer, speaker, trainer, and musician. Peter’s professional interests are business process management, workflow automation, software functional design, agile software development methods, and software documentation. Peter consults for software companies and development teams, and delivers the occasional presentation and workshop.

Peter has previously presented at numerous European developer conferences, co-authored ‘Play for Scala’ (Manning Publications), and has taught ‘Fast Track to Play with Scala’, and more recently his own training course on ‘How to write maintainable code’.

Technical documentation is a backup so make sure it works

Apr 09, 2020

Imagine working on a team of programmers who write perfect code, never forget anything, never leave the team, have perfect verbal communication skills, and love meetings. That would be weird on many levels, but at least then you’d have a chance of not needing any technical documentation. For the rest of us, who have legacy code to deal with, we need to know how to write useful documentation. Otherwise, other peoples’ code will become a single point of failure to understand what’s going on.

Technical documentation is our backup for not being able to easily understand a system and its code just by looking at it. Unfortunately, your backups probably haven’t been tested recently and don’t actually work. The solution is to write less documentation, not more, but not none. By writing less documentation, you can focus on writing documentation that counts, actually maintaining what you write, and have more time left over for writing code.