In a perfect world we'd be building simple websites with easily re-usable modules and plugins, written by people much more dedicated to their particular niches. This is reality, and sometimes we are building terribly complicated web applications with hordes of custom modules and plugins. Hordes: like the orcish armies in the Lord of the Rings. They are ugly, and mean, and smelly, and while you're paying attention to one group there's another group you've forgotten about and they're building a bloody catapult.
Recently I found myself so overwhelmed by my own code that I had to take a day and write documentation. Despite my best attempts at organizing things, there was just too much of it to keep straight. Things I had not worked on in months would come up and it was impossible to find the function I was looking for, if it even existed, because I had no idea what was there anymore.
Arrogant programmers always say "I know my own code." But after a month or two, or six, or god forbid you have to use someone else's code, having to wade through 2000+ lines of code to figure out what's there and how it works will make you unhappy.
So I read up on Drupal's documentation guidelines for module development, which take advantage of Doxygen. I spent a whole day writing documentation. I set up a development server to automatically compile documentation every night. This has proved useful because code I wrote yesterday is automatically documented and ready for me today. The documentation is formatted as HTML, and it's super easy to look up what the function does, what it's called, what parameters I need to pass to it, and what I'm going to get back.
Development continues. Almost overnight I changed how I write code because of the documentation. I don't write the function first, test it, fix it, and maybe go back and write documentation later. Now I write the documentation first. I write documentation before I write any code. This gives me a way to abstract the function, to focus on "what does this do" instead of on the details. It actually makes writing the function easier because I've already defined what it does.
We have another big project that's been live for about two years. The client is looking at improving the search functionality and we're looking at making significant changes to the structure of the data. Do you think there's any documentation for any of this? As we rebuild it, writing documentation will be a part of the process.