Almost all developer information should be maintained in one place that can be rapidly updated.
It was a familiar scene. My manager called me into a meeting. Jason was there. “There's a project that Jason has 98% percent finished and he is now on a new project. Can you finish it?”
“Sure, can you point me in the direction of some starting documentation?”
“Well, there is a WIKI but it hasn't been updated in a while. We've been too busy.”
I opened the WIKI in my browser – it had two useless pages that had been created on the first day of the project.
“Ah, the WIKI is useless. Where is the documentation?”
“It's in an email somewhere. Hold on, I'll send it to you.”
Jason fiddled with his email search tool for five minutes while we waited. Eventually he admitted defeat.
“I'll have to email it to you later.”
“OK, can you give me a way to log in to the test server and see what is going on?”
“Sure, the login details are in an email somewhere. Hold on”.
As the meeting went on, it became apparent the project had been completely email driven. Requirements were spread in hundreds of emails between the project manager and the developers. Since Jason was going off to a customer site the following day, things were about to get a whole lot more annoying for him, with me calling him every few hours to find out basic information. It would have been much easier for Jason to be able to answer “All the information you need is on the WIKI”.
Every project that other users are expected to support should have a WIKI to pass on all relevant information to future developers.
Tip: Don't create a Tips and Tricks section in the Wiki. Every topic has a specific logical grouping. Break the wiki out into real sections such as hosting end environments, new developer setup, deployments, design, test automation.
And:
Tip: Don't attach binary requirements and API documents in the wiki. Check them into source code control where they can be versioned and managed.
