Re: PPIG discuss: Documentation for large systems
Ruven E Brooks wrote: 3. I didn't rule out active discovery of content. In fact, that's what people do today in our organization; they look at the code and analyze the code, using tools of varying degrees of sophistication. The problem is, it's terribly time consuming, and the same discovery process has to be repeated by each new team member; that's what takes the 6-12 months - active discovery of content. I'd like to jump start or shortcut the process. [I note that In educational theory, active learning doesn't mean that you put the students on a desert island and expect them to actively discover particle physics; it means that you carefully set up situations in which the students participate that enable them to learn. I can think of equivalents for learning a large piece of software, but developing them requires even more work than writing the 20 page document.] Yes, its good to call out this point even though I was trying to make the contrast stark for clarity. As in: put the (constructivist?) particle physics professor on the desert island instead of plunking down an undergraduate college textbook. An intermediate position might be to have a teacher PLUS a book. Of course, you appear to be making a case for avoiding repeated work by creating a reusable knowledge resource, so my line of thought wasn't exactly on topic. I guess a better line of questioning leans towards the classic build for reuse question: will the knowledge stored in the document be reused enough (before it is outdated, say) to warrant its expense? At least this question is constructive enough to produce a documentation rule you might be able to use: hesitate including anything that is likely to change before you get a new Chief Architect ;) (Although since you suggest that certain forms of learning materials are very costly I still wonder about the cost effectiveness of providing tutors to software immigrants in lieu of certain efforts to document. Since none of the original developers are around, however, this question may be somewhat moot in your case). Andrew -- 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/
Re: PPIG discuss: Documentation for large systems
So theoretically, 20% of the team have just gone through this learning process. What did they misunderstand? What questions were they asking their mentors and why. Ask if you can read the notes they made, and interview them about those notes -- which bits actually turned out to be useful and which were blind alleys? Hopefully, that'll quite quickly tell you what level they are getting stuck at -- whether they have difficulty getting the big picture, or whether there are specific details that are missing -- whether it's a navigational problem or an understanding problem, etc. (I'm hoping 20% of the team doesn't just mean 1 additional new grad, but that you might get a breadth of responses) regards, Will. On 7 Nov 2007, at 14:23, Ruven E Brooks wrote: Let me elaborate a bit on my original request. 1. I'm assuming that most or all of the previous developers/ architects of the system are unavailable. All that's left are the artifacts, code plus whatever else. There's no one to talk to about where to start, etc. or about the overall structure. 2. Imagine that, instead of being a new chief architect, that the plan is to replace 20% of the developers on the project every year but not to increase staffing levels by 20% (which is what would be required with the current methods of getting people up to speed.) 3. I didn't rule out active discovery of content. In fact, that's what people do today in our organization; they look at the code and analyze the code, using tools of varying degrees of sophistication. The problem is, it's terribly time consuming, and the same discovery process has to be repeated by each new team member; that's what takes the 6-12 months - active discovery of content. I'd like to jump start or shortcut the process. [I note that In educational theory, active learning doesn't mean that you put the students on a desert island and expect them to actively discover particle physics; it means that you carefully set up situations in which the students participate that enable them to learn. I can think of equivalents for learning a large piece of software, but developing them requires even more work than writing the 20 page document.] Ruven
Re: PPIG discuss: Documentation for large systems
Ruven E Brooks [EMAIL PROTECTED] writes: 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? 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. My superprogrammer colleague suggested that what he wanted was a list of the actual files that were installed, together with an explanation of each one. Other thoughts, suggestions are welcome. Ruven Brooks Dave Parnas Elequently addressed this question in two papers Using Documentation as a Design Medium and a A rational Design Process, How and Why to Fake It. Since these papers, which include two examples, a rationale and some useful and very practical commentary, defined the field for documentation in Software Engineering, I would begin there. Tom Wheeler University of Maine -- 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/
Re: PPIG discuss: Documentation for large systems
Let me elaborate a bit on my original request. 1. I'm assuming that most or all of the previous developers/architects of the system are unavailable. All that's left are the artifacts, code plus whatever else. There's no one to talk to about where to start, etc. or about the overall structure. 2. Imagine that, instead of being a new chief architect, that the plan is to replace 20% of the developers on the project every year but not to increase staffing levels by 20% (which is what would be required with the current methods of getting people up to speed.) 3. I didn't rule out active discovery of content. In fact, that's what people do today in our organization; they look at the code and analyze the code, using tools of varying degrees of sophistication. The problem is, it's terribly time consuming, and the same discovery process has to be repeated by each new team member; that's what takes the 6-12 months - active discovery of content. I'd like to jump start or shortcut the process. [I note that In educational theory, active learning doesn't mean that you put the students on a desert island and expect them to actively discover particle physics; it means that you carefully set up situations in which the students participate that enable them to learn. I can think of equivalents for learning a large piece of software, but developing them requires even more work than writing the 20 page document.] Ruven
