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
Ruven E Brooks wrote: 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?... Other thoughts, suggestions are welcome. If this email is supposed to be some kind of joke or rude satire, it's not remotely funny enough, Ruven. Surely: (a) you know as well as anyone that this is a solved problem after so much careful research, and that you should be able to quickly find your answers (check the encyclopedia, perhaps), (b) industry already knows all they need about their problems and academics are apparently unconnected to reality, so why are you asking?, (c) 1.5 MLOC...is that it?, (d) programmers don't read documentation, and (e) code is self-documenting anyway. OK, I reached way back almost to Perlis Aphorism territory for the last two but I think completeness is a virtue here. I mean, is it April 1st already? If you believe architects are not programmers per se, then asking a superprogrammer what she thinks is arguably bad requirements gathering. Perhaps it might be better to look at something along the lines of the following instead?: 1. major forces/issues the architecture must continue to meet 2. list of successes and warts of the current architecture 3. rationales for #2 relating to #1 Good luck! 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
Gaspar, Alessio (USF Lakeland) wrote: I can understand the love'em / hate'm positions regarding wikis, however I couldn't help but notice that some of the arguments below are very close to what used to be said by corporations about open source projects and development methodologies All wikis don't have to be wikipedias; they can help build collaboratively information without anonymous contributions and with clearly defined participation roles from the team members. In such a context, it can still simplify collective review and speeds up the turn around time. We're probably dealing with the classical reaction / counter-reaction surrounding any new technology; step #1 it'll solve all our problems! step #2 wait, it is now our main problem step #3 we should use it only for what it's good for... Hmm, step #3 is frequently different in my experience, as in: step #1 it'll solve all our problems! step #2 wait, it is now our main problem step #3 look, here's another shiny new paradigm! For example, step #1: Wiki will solve all our problems! step #2: wait, now it is our main problem step #3: you're not using Agile Wiki methods. [later] Correctly. I find it a little amusing to note that Ruven asked for the *content* of a static document in a producer-consumer context and the discussion has turned to the merits of an active, collaborative documentation *infrastructure*. It makes me think about the classic arguments espousing active learning/discovering (as opposed to, say, transfer theories of learning). Might be interesting to compare the ROI of (a) the manpower used to create a 20 page document against (b) providing that same manpower as research/development aids for the incoming Chief Architect during her acclimation period. 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: Hello / how we debug
First, hello to Dan Frost. C.Douce wrote: Whilst I do appreciate the simplicity (and elegance) of the 'print I'm here' approach, when it comes to developing embedded systems nothing can beat a monitor program, a serial cable and the ability to plant break points in your code when you begin to step into trouble. I cannot foresee a time in which everyone will agree about debugging. While the embedded systems argument has been made many times, I think there still will be a segment that resist it. I am reminded of Linus Torvalds' long insistence of no official kernel debug interface (http://www.uwsg.iu.edu/hypermail/linux/kernel/0009.0/1148.html) Some interesting conjectures there about the impact of tools on how people think. Torvald's comments also remind me of a previous PPIG discuss thread on the impact of compile time (http://www.mail-archive.com/discuss@ppig.org/msg00208.html). On a more personal note I have trouble separating debugging from other programming activities, and thus reserve first dibs on withdrawing from debugging debates by claiming them to be battles between straw men. ;) Regarding the earlier question of standard diagnosis procedures, there may indeed be some fairly stable and general sets of patterns that debuggers try. For example, IIRC Weisers's slicing work arose from observations of debuggers commonly performing backwards data flow tracing from the point at which actual program behaviour diverges from expected. That said, I am still having a difficult time relating medical diagnosis procedures with programming simply because of the variety in programs. Perhaps experts on debugging distributed reactive systems are specialized in ways similar to dermatologists? Still, I know studies have been done on medical problem analysis and I am intrigued as to whether anyone has specific ideas as to how they may be related. 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: Bracketing -- 4 other issues
I think this is a simple readability and/or standards issue. For example, the APA publication manual specifically separates the label from the bracket in reporting statistics and degrees of freedom, for example for an analysis of variance it is F (2, 24) not F(2, 24). I'm not so sure. At first glance, I say it might involve four different psychological issues: learning, perceptual distinction issues, esthetic and bias issues, and and task-related scanning issues. 1. Learning. Spacing may affect learning by providing cues (CD: role expressiveness) as to how to interpret the line. As Derek M. Jones says, if( may be confused with a function call, whereas if all keywords are consistently separated by whitespace, then it may prove less confusing. Still, I think its a bit of a stretch. A second point related to learning is that standards should make learning easier because of the consistency. 2. Perception distinction issues. Wayne Gary cited Rayner's article and, although I know little about this body of literature, I could offer up the following quotation. Don Norman, in chapter 3 of Things that Make Us Smart, notes the following: A: Which number is larger? 284 912 B: Which number is larger? 284 312 Much to many people's surprise, experimental psychologists discovered that people can answer problem A faster than they can B. The time differences are small, small enough that you can't notice it yourself, but large enough to be easily measured through the appropriate experiments. Even though we experience both comparisons as immediate and effortless, B takes more time and effort than A. Why is this? So far, the only answer that accounts for all the findings is that the Arabic numbers are translated into a perceptual image---an additive representation---before the comparison is performed. The greater the perceptual difference, the easier the task. From this there's two things to note. First, the difference may not be noticeable even if small differences in perfromance are experimentally measurable. Who cares about such timing differences other than notation designers with absolutely nothing else to worry about? The second is that even seemingly minor perceptual distinctions may be important. That could provide an armchair argument for adding a space. 3. Esthetic and bias issues. Some people really hate different spacing. That could affect the reader. For instance, someone's promotion might depend upon a manager perceiving that a developer's code is solid and professional. I know of absolutely no work on this sort of issue, and since it is generally outside cognitive science's currently limited scope, I suspect you'll only find related research in something like JMIS (J. Manag Info Sys). 4. Task-related scanning issues. A fourth psychological issue is how tasks and goals affect the use of the notation. If one is reading the code carefully in a code inspection, my gut feeling is that no spacing variations matter except that some forms will offend the esthetic tastes of the reader. What about someone searching for a specific comparison in a body of code (such as in an if-else-else---then chain)? Then spacing may hinder effective perceptual search. In particular, is may be that if ( foo == bar ) is easier to scan for comparisons than if(foo == bar) or if (foo == bar) Unlike in #2 above, that task-related issue may be important since, although speed might not be an important issue, accuracy might very well be. For example, missing a case during search could be disasterous. You MAY be able to twist this sort of argument into a case for why you should always add space after a keyword. However, although intuitively it seems that spaces increase readability, I believe that the research on reading suggests that eliminating spaces betweenwordsasinthisline does not significantly decrease speed. I am not quite sure where I picked up this counterintuitive factoid, but it might have been cited in: [snip] Ewww, that IS surprising if true. Does some other distinguishing feature need to be there as in MixedCaseIdentifiersAreOK? but nonmixedcaseidentifierssuck? Andrew - Automatic footer for [EMAIL PROTECTED] -- To unsubscribe from this list, mail [EMAIL PROTECTED] unsubscribe discuss To join the announcements list, mail [EMAIL PROTECTED] subscribe announce To receive a help file, mail [EMAIL PROTECTED] help This list is archived at http://www.mail-archive.com/discuss%40ppig.org/ If you have any problems or questions, please mail [EMAIL PROTECTED]
Re: PPIG discuss: What plan?
An example of a simple plan is a simple find plan: iterate through the set test each set member to see if it is the target; if it is, end the iteration Most computer scientists would (hopefully) call this the linear search algorithm -- and therefore be very worried about using it because it is O(n), proper searching should be O(log(n)) (binary chop and binary tree search) or O(1) (hash table). Not worried, no. Every practicing engineer knows its sometimes best to use linear search because its simple to write, understand, debug, and modify if necessary. For short non-critical searches its great. It appears regularly in production code. And note: linear search is a shared abstraction with a common vocabulary. It clearly qualifies as a plan which, according to your previous mailing, is not appropriate. Thus I think it is quite wrong to separate patterns and plans so dogmatically. What would you call a pattern that only you know? Moreover I would hazard to guess that when paired programmers get together and code, they use a lot of shared plans otherwise it just wouldn't work. Andrew - Automatic footer for [EMAIL PROTECTED] -- To unsubscribe from this list, mail [EMAIL PROTECTED] unsubscribe discuss To join the announcements list, mail [EMAIL PROTECTED] subscribe announce To receive a help file, mail [EMAIL PROTECTED] help This list is archived at http://www.mail-archive.com/discuss%40ppig.org/ If you have any problems or questions, please mail [EMAIL PROTECTED]
