> If you could have a 20 page initial document on the internal structure of > this system, what would that document contain? > > My own initial thought was some kind of box-and-line major subsystems > document but the exact semantics of the boxes > and the lines is still open. Beside the major architectural components and relations I would make explicit a top of the *hidden assumptions* that belong to the project. By hidden assumption I mean things that are not clear when reading the code and that are central for using/extending the a module. Central hidden assumptions are those that are known by (almost) all of the experienced project participants.
I would also include a (upper-)ontology of the domain (say: most important 100 domain concepts) and the relation to the places in the code where are the concepts implemented. The ontology makes the terminology of the project explicit and the relations to the code offer an "interpretation" of the program. Dan -- Daniel Ratiu Institut für Informatik Technische Universität München Boltzmannstr. 3 D-85748 Garching Germany Email: [EMAIL PROTECTED] Phone: +49 (89) 289-17882 Fax: +49 (89) 289-17307 Room: 00.09.059 ---------------------------------------------------------------------- PPIG Discuss List (discuss@ppig.org) Discuss admin: http://limitlessmail.net/mailman/listinfo/discuss Announce admin: http://limitlessmail.net/mailman/listinfo/announce PPIG Discuss archive: http://www.mail-archive.com/discuss%40ppig.org/