I know it's been said a thousand times before and I'm going to repeat it now:
Don't assume anything - document everything!
The hard part is actually understanding what your own assumptions are so that you can document them. The problem is, I've already failed to do this and am now stuck in a scenario where I either take a bunch of time out of my day to document existing stuff or take the time out of my day each time someone needs an answer about something.
...
Earlier today a coworker stated that he was done with his assignment. When CruiseControl rebuilt the site and published it to our dev web server, I checked out the site and it wasn't working at all. Going back to the developer, I asked him to look into the problem... of course he couldn't reproduce it on his local machine. Normally, I would ask to see the unit tests and make sure they cover all the scenarios. In this case, though, we can't unit test things very well because we are utilizing the VirtualPathProvider of ASP.NET 2.0... severely hamstrings us for unit testing when dealing with this level of API.
After his initial R&D into the issue and not being able to come up with a solution, I rolled over to his desk and took a look at his code. I found the problem immediately - he was making use of the App_Data folder in the ASP.NET project to store some template files. Why is this bad? Normally, it's not. We use the Web Application plugin (part of SP1 now) and Web Deployment Project plugin (not part of SP1 which is stupid, IMO) for our ASP.NET 2.0 Projects. In the Web Deployment project, we explicitly state that App_Data should be removed from the output because we are pre-compiling the web app into an assembly. That means we are not actually shipping the App_Data folder out to the dev web server, which means the file can't be found and the system won't work.
The point is - if I had taken the time to document our standard web project setup, a year ago, I could have saved a small chunk of re-work time because the developer would have been informed from the beginning. Instead, I was running under the assumption that everyone knows about Web Deployment projects and not using the App_Data folder. Oops.
...
Lesson learned the hard way, once again. Don't assume anything - document everything! And FYI - this applies to everything we do as developers, not just knowing what the standard project setup is like... code, process, documentation, all of it. (So how do you document the documentation standards? or better yet - which came first: the doucmentation or the documentation describing the documentation standards? HA!)