Ever started work on an existing software project that has NO technical documentation whatsoever?
I have recently, and I immediately felt lost.
No coding standards, no testing guidelines and most importantly, no notes at all about how the existing codebase was designed.
Why is this a problem? Well, for me it meant a lot of time reverse engineering the codebase and subsequently generating new documentation. I had to learn the project from scratch. It added a huge amount of time before I could do any real work on the project.
Every little piece of documentation that you add to your project can help save time later on – either for yourself or for another person working on the project.
What’s the minimum you should have in your project documentation?
- Database schema in visual form
- Coding standards
- Source control branching strategy
- Deployment instructions for all environments (e.g. staging and/or production)
- Development environment setup
Wikis are perfect for collecting this kind of documentation. They are free-form, so you have freedom to structure as you wish.
Have no documentation at all? Fear not, it’s easy to get up and running. A few ideas to start with:
- Use a database management tool, such as MySQL Workbench, to reverse engineer your database schema and produce a graphical model
- Use your unit testing framework to produce agile documentation from your tests – for example, PHPUnit has a –testdox option for generating documentation.
- Start using standard inline documentation. For example, use phpDocumentor for PHP code.
Take a look at the documentation you have for the project you are currently working on. If a new developer came onto the project today, would the documentation be enough to get them up to speed? If not, what would you need to add?
image credit: LimeSurvey v2 schema by juhansonin, on Flickr
Glen Scott
I’m a freelance software developer with 18 years’ professional experience in web development. I specialise in creating tailor-made, web-based systems that can help your business run like clockwork. I am the Managing Director of Yellow Square Development.
Follow Me:
