Initiator: Bohdan Hanchuk
Participants: Martin, Scott, Costa, Dimitri, Joe Rainsberger
There is no singe answer, no single approach, no right answer.
Suggestion: if you decide to take this discussion offline to a newsgroup, please indicate the location of the group here so others can join you.
It seems that the real underlying issue, is knowledge transfer. How is the knowledge that one group possesses transfered to another group in an effective manner. It was the general concensus that most written documents were ineffective in performing this function. Oral discussions, brief diagrams and frequent interactions are the best way to communicate knowledge and ideas between groups.
Our experience says that written documentation is insufficient to the purpose of knowledge transfer. This is why the argument 'we need documentation for knowledge transfer' is not very compelling.
Another point to consider is the issue of legacy documentation. What to leave behind when a system is placed into production. In all probability, the original development team is long gone (even the original developers forget the details) and the maintenance team has limited knowledge of the system.
It was suggested the most effective approach was a high level roadmap (2 to 3 pages long) to orient new developers. Anything longer is generally not read in any case.