Ruven E Brooks wrote: > I have just been given the assignment of investigating techniques for > documenting a 1.5 million line system. > > Suppose that you were hired (at an outrageous salary, of course) to be > the chief architect of this system. > If you could have a 20 page initial document on the internal structure > of this system, what would that document contain?
A succinct description, in non-technical terms, of what the system is for, who cares about it, and how it came about. On one, arbitrarily large, sheet of paper, using any sensible notational scheme, a picture of all the logical components of the system and their relationships. (I'd expect to stick this on the wall.) A design rationale document that provides, in broad-brush terms, the underlying principles of the design, such as: + favour correctness over robustness + will never have a web interface + separation of presentation and representation + must offer five nines of service availability + any user-visible defect must be fixable in 24 hours + must not depend on any single tool vendor + must never give rise to a complaint to the police If the system uses any unusual technology, I'd want to have some explanation of why, even if it's just "because Bob wanted to see if he could marry Forth and S-Expressions." A list of the deployment model in use, including how long it takes to put a change live, and who gets to stop the change. And, perhaps most importantly, a list of contact information for people who already know how the system works and how to change it without breaking it, and the authority to get them to answer my questions. Getting your head around a new software system requires being able to play with it, look around inside it, and the ability to break it to see what happens when you do. So from Day One, I'd also want: Access to the revision control system, including a complete history of all the code and data in the system. Access to the bug-reporting system, including information on all the previously-fixed problems. Details of the build system, and a scratch copy of the live system (including representative live data), so that I could immediately start poking about, and experiencing the system for myself. When finding out more, and contemplating my first attempts at working on the system, I'd then want access to arbitrarily detailed documentation, probably all online, and probably substantially automatically generated: A list of all the things in the real world that the program represents, such as: + business processes + tangible objects + scheduled events A list of all the data entities that the system manipulates, and pointers to their documentation, such as: + database tables + reference data + files + run-time data structures A list of all the interfaces the program system presents, such as : + APIs + web services + user screens + batch processed files A list of all the organizational relationships the system is a part of, such as: + contracts referring to the system + third parties who depend on the system + third parties that the system depends on + data exchanges + transactions A list of all the risks to the system, such as: + data whose correctness is assumed + tools and libraries whose proper operation is assumed + laws or regulations that the system must adhere to + staff or suppliers with critical operational knowledge + licenses or equipment with limited lifetimes A list of all the promised or pending changes to the system, who they're important to, and why. And a list of the best quiet coffee shops within walking distance. -- Frank Wales [EMAIL PROTECTED] ---------------------------------------------------------------------- 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/
