In a Godbit interview with Leslie Camacho, VP of EllisLab, the company behind the popular CMS ExpressionEngine and the open source PHP framework CodeIgniter, Nathan Smith asked the question, “Do you have a team of in-house writers documenting your products, or is that all done by developers?”. To which Leslie responded, “It’s all done by the developers and myself.” That’s DIY Documentation right there.
I thought that was rather interesting. Having never written formal documentation for a framework or application, my only interaction with the process was reading ones already written by someone else. I had no idea how difficult or easy it was to write. I’m currently working on a project and looking back at what I’ve done so far, I realise that despite leaving little comments here and there, I think I could have done a better job documenting the code and also write some documentation for the user (I mean the application seems pretty straight forward to use but you never know). Surely that’s not a good thing and I feel a little bad now for not doing a better job of that from the get go.
Now if you have used or heard of CodeIgniter/ExpressionEngine, you’ll know they both have some pretty darn good documentation and even their code is well documented also. Derek had the following to add in response to Nathan’s question:
We feel that forcing developers to write documentation yields better code, better docs, and a better application/framework. Writing about how you do something often changes your perspective in a positive way. If it’s too complicated to write in plain English then chances are something needs to be improved in the code, interface, and/or the functionality. That’s not always true, but its a good starting point.
Usually the development team writes the initial drafts of the docs and then I go through and polish things up, add screencaps, and so on. We take our docs very seriously and will even delay release if the docs aren’t just right. Several “doc hounds” live in our community and sniff out every single error we miss. We do our best to correct those as quickly as possible.
Now I’m no expert, but this just seems to make a lot of sense to me and I thought to myself, “Man, it would have been good to have heard this when I first started on that project.” We learn something new every day and I guess from here on I’ll be making more of an effort to write better documentation.