Re: PPIG discuss: Documentation for large systems
On 6 Nov 2007, at 19:25, Boris Ouretskey wrote: You are welcome to visit www.wikipedia.org and convince yourself that is far away from being myth. That's an entirely different use case. That does not prove anything about wikis for managing projects or creating documentation. There are completely different primary interests of the participants involved. Michael -- 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
William Billingsley <[EMAIL PROTECTED]> writes: >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. There's a good discussion of this (with a worked example) on Hacknot: http://www.hacknot.info/hacknot/action/home;jsessionid=680FEB7AA005D599C2C58CFB4074C702 You know, it's taken me nearly two weeks of stuffing around to get a development environment setup for AccountView. That's a fair productivity hit. have you considered writing all the necessary steps down so that newcomers can just follow the instructions instead of having to piece it together for themselves. Peter. -- 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 <[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
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
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
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: Documentation for large systems
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..." -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Michael Kölling Sent: Tuesday, November 06, 2007 14:16 To: discuss@ppig.org Subject: Re: PPIG discuss: Documentation for large systems Wiki? Obligatory?? I don't believe in wikis at all. I know there is (still) a lot of hype around them, but I think it is a complete myth that they work. There is somehow the wishful thinking that the documents (documentation, in this case) write themselves. The hive-mind will fix it. "The community" (or "all the company") will write it. The result, much more often than not in my experience, is a document that nobody takes responsibility for, that has very weak overall structure, and random level of detail over various parts. No guarantee that important information is represented appropriately at all. I'd like to know who to kick if the document sucks. Michael -- 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
I think the point here is that some people like Wikis and others don't - they will work well when you have people who like them and won't when they don't. Personally, I detest them and won't use them at any price. L. -- 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
Gergely, Firstly Michael's response was related to wiki's in general and not to wiki's in corporation. So my example was going to show that at least in some cases it works fine and for that matter cannot be considered as "myth". Secondly denying completely fun, professionalism and loyalty to organization as existing factors at workplace is also something very arguable. Furthermore managing wiki pages can be driven by completely selfish reasons like saving time answering phone for example. Your critical-mass-assumption is something I also cannot agree on. In my opinion critical mass for wiki purposes is just equal to number of people in organization. If there is only one, then one it would be. I would also say that there is a reverse critical mass which means that if there are less people participating in wikis than working in organization than there is a critical point after which wiki will loose its value. Thanks -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Gergely Buday Sent: Tuesday, November 06, 2007 11:17 PM To: Boris Ouretskey Cc: Michael Kцlling; discuss@ppig.org Subject: Re: PPIG discuss: Documentation for large systems Michael wrote: > The result, much more often than not in my experience, is a document > that nobody takes responsibility for, that has very weak overall > structure, and random level of detail over various parts. No guarantee > that important information is represented appropriately at all. > > I'd like to know who to kick if the document sucks. for what Boris replied: > You are welcome to visit www.wikipedia.org and convince yourself that is far > away from being myth. Sorry to say, Boris, but your example is mistaken. Wikipedia has millions of editors, and they do it for fun. A normal developer, i.e. who is not forced to write documentation, rarely writes it for fun. She writes code instead. And a software project rarely excess the hundreds in person, so there is no critical mass for the documentation process to be self-sustaining. Should there be a responsible project manager, she puts resources for writing the documentation. If this is the case, it can be wiki, which does have advantages over word documents. - Gergely -- 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/ -- 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
Michael wrote: > The result, much more often than not in my experience, is a document > that nobody takes responsibility for, that has very weak overall > structure, and random level of detail over various parts. No guarantee > that important information is represented appropriately at all. > > I'd like to know who to kick if the document sucks. for what Boris replied: > You are welcome to visit www.wikipedia.org and convince yourself that is far > away from being myth. Sorry to say, Boris, but your example is mistaken. Wikipedia has millions of editors, and they do it for fun. A normal developer, i.e. who is not forced to write documentation, rarely writes it for fun. She writes code instead. And a software project rarely excess the hundreds in person, so there is no critical mass for the documentation process to be self-sustaining. Should there be a responsible project manager, she puts resources for writing the documentation. If this is the case, it can be wiki, which does have advantages over word documents. - Gergely -- 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
I have to agree with you that wiki methodology adoption depends heavily on companies' (organization) culture, but so is anything else. Though the question of "How to document a large system" - is too general to answer , I still see wikis as very powerful method to accumulate and maintain knowledge in any large dynamic organization. I am currently working for company which quite successfully maintains the wiki pages at intranet site. -Original Message- From: Clendon Gibson [mailto:[EMAIL PROTECTED] Sent: Tuesday, November 06, 2007 10:10 PM To: Boris Ouretskey Subject: Re: PPIG discuss: Documentation for large systems Wikipedia and indeed other wikis are successful and useful, but the most successful ones are voluntary. Wikipedia is no exception to this. People are creating Wikipedia articles for there amusement or entertainment. In a development environment the motivation is different. It is very likely that the Wiki will be neglected because the knowledgeable have 'real' work to do. This reminds me of the discussion we had several months ago about using different development methods for open source projects vs. commercial projects. The use of a wiki as a documentation solution has to fit the culture of the users or developers. - Original Message From: Boris Ouretskey <[EMAIL PROTECTED]> To: Michael Kцlling <[EMAIL PROTECTED]>; discuss@ppig.org Sent: Tuesday, November 6, 2007 1:25:31 PM Subject: RE: PPIG discuss: Documentation for large systems You are welcome to visit www.wikipedia.org and convince yourself that is far away from being myth. -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Michael Kцlling Sent: Tuesday, November 06, 2007 9:16 PM To: discuss@ppig.org Subject: Re: PPIG discuss: Documentation for large systems On 6 Nov 2007, at 18:53, Boris Ouretskey wrote: > Anyway to document large system it is obligatory to use wiki pages > (and a lot of time of cause) and give all the company an opportunity > to participate in the process. Wiki? Obligatory?? I don't believe in wikis at all. I know there is (still) a lot of hype around them, but I think it is a complete myth that they work. There is somehow the wishful thinking that the documents (documentation, in this case) write themselves. The hive-mind will fix it. "The community" (or "all the company") will write it. The result, much more often than not in my experience, is a document that nobody takes responsibility for, that has very weak overall structure, and random level of detail over various parts. No guarantee that important information is represented appropriately at all. I'd like to know who to kick if the document sucks. Michael -- 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/ -- 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/ -- 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
In the 90¹s, Ric Holt and a group of others constructed something called the Software Bookshelf to solve precisely this problem it was part of a larger consortium effort with which I was involved. We focused on tkSEE. Here is a link for SB: http://www.swag.uwaterloo.ca/pbs/ Tksee can be read about here: http://www.site.uottawa.ca/~tcl/kbre/options/intro.html Let me know if you have any questions. Janice (singer) NRC Canada On 11/6/07 11:56 AM, "Ruven E Brooks" <[EMAIL PROTECTED]> wrote: > > > [EMAIL PROTECTED] wrote on 11/06/2007 10:21:14 AM: > > >> > Who will be the reader of these documents? >> > >> > If the readers are going to be software developers working on >> > the source do you think the exercise will be cost effective? >> > After all, if there are only going to be a few readers and they >> > are only going to read parts of the source (ie, on an as needed >> > basis) then you documenting all of it may be more costly. > > It takes a minimum of six months and, more typically, a year, before > developers joining this project have positive productivity, e.g. the > value of their efforts exceeds the cost in other people's time to bring > them up to speed. From informal discussions, this length of time is > typical, or, perhaps, on the speedy side for applications of this size. > > If you assume that four or five developers on the team are being replaced per > year, > and that better information could cut the one year learning time down to six > months, then > we have something like 2.5 person years, every year, to invest in getting and > updating > the information. > > The problems with just reading parts of the source, which is what happens now, > are that it's often difficult to know where to start and what to read. A > large part > of the 6-12 month learning period is spend building up enough of understand of > the overall > structure so that know where to focus detailed understanding. > > Ruven -- Janice Singer, PhD NRC Institute for Information Technology | Institut de technologie de l'information du CNRC Tel/Tél: (613) 991-6346 | Facsimile/télécopieur: (613) 952-7151 [EMAIL PROTECTED] http://iit-iti.nrc-cnrc.gc.ca National Research Council Canada | M50, 1200 Montreal Rd., Ottawa, ON K1A 0R6 Conseil national de recherches Canada | M50, 1200 chemin Montréal, Ottawa (Ont) K1A 0R6 Government of Canada | Gouvernement du Canada
RE: PPIG discuss: Documentation for large systems
Ruven, Do you have documentation or citations for any of your claims and figures? It would be helpful for motivating our research program. Thanks, Brad A. Myers Professor Human Computer Interaction Institute School of Computer Science Carnegie Mellon University 5000 Forbes Avenue Pittsburgh, PA 15213-3891 (412) 268-5150 FAX: (412) 268-1266 [EMAIL PROTECTED] http://www.cs.cmu.edu/~bam _ From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Ruven E Brooks Sent: Tuesday, November 06, 2007 11:57 AM To: discuss@ppig.org Subject: Re: PPIG discuss: Documentation for large systems [EMAIL PROTECTED] wrote on 11/06/2007 10:21:14 AM: > Who will be the reader of these documents? > > If the readers are going to be software developers working on > the source do you think the exercise will be cost effective? > After all, if there are only going to be a few readers and they > are only going to read parts of the source (ie, on an as needed > basis) then you documenting all of it may be more costly. It takes a minimum of six months and, more typically, a year, before developers joining this project have positive productivity, e.g. the value of their efforts exceeds the cost in other people's time to bring them up to speed. From informal discussions, this length of time is typical, or, perhaps, on the speedy side for applications of this size. If you assume that four or five developers on the team are being replaced per year, and that better information could cut the one year learning time down to six months, then we have something like 2.5 person years, every year, to invest in getting and updating the information. The problems with just reading parts of the source, which is what happens now, are that it's often difficult to know where to start and what to read. A large part of the 6-12 month learning period is spend building up enough of understand of the overall structure so that know where to focus detailed understanding. Ruven
RE: PPIG discuss: Documentation for large systems
You are welcome to visit www.wikipedia.org and convince yourself that is far away from being myth. -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Michael Kцlling Sent: Tuesday, November 06, 2007 9:16 PM To: discuss@ppig.org Subject: Re: PPIG discuss: Documentation for large systems On 6 Nov 2007, at 18:53, Boris Ouretskey wrote: > Anyway to document large system it is obligatory to use wiki pages > (and a lot of time of cause) and give all the company an opportunity > to participate in the process. Wiki? Obligatory?? I don't believe in wikis at all. I know there is (still) a lot of hype around them, but I think it is a complete myth that they work. There is somehow the wishful thinking that the documents (documentation, in this case) write themselves. The hive-mind will fix it. "The community" (or "all the company") will write it. The result, much more often than not in my experience, is a document that nobody takes responsibility for, that has very weak overall structure, and random level of detail over various parts. No guarantee that important information is represented appropriately at all. I'd like to know who to kick if the document sucks. Michael -- 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/ -- 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
On 6 Nov 2007, at 18:53, Boris Ouretskey wrote: Anyway to document large system it is obligatory to use wiki pages (and a lot of time of cause) and give all the company an opportunity to participate in the process. Wiki? Obligatory?? I don't believe in wikis at all. I know there is (still) a lot of hype around them, but I think it is a complete myth that they work. There is somehow the wishful thinking that the documents (documentation, in this case) write themselves. The hive-mind will fix it. "The community" (or "all the company") will write it. The result, much more often than not in my experience, is a document that nobody takes responsibility for, that has very weak overall structure, and random level of detail over various parts. No guarantee that important information is represented appropriately at all. I'd like to know who to kick if the document sucks. Michael -- 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
For the first document I'd rather have a presentation with notes. They seem to convey high level information more effectively. Anyway to document large system it is obligatory to use wiki pages (and a lot of time of cause) and give all the company an opportunity to participate in the process. -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Ruven E Brooks Sent: Tuesday, November 06, 2007 6:00 PM To: discuss@ppig.org Subject: PPIG discuss: Documentation for large systems 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
Re: PPIG discuss: Documentation for large systems
Ruven,
I'm a man with a hammer, so I'm interested in finding out whether
your problem might be a nail...
From the issue you've described ("it's difficult to know where to
start and what to read"), it sounds like the shortage is not in the
detailed documentation per se, but in an introductory guide to the
purpose and parts of the system -- a textbook for working with the
system.
The hammer that I have is a better system for authors and students to
collaboratively write textbooks. Someone who used to work with SAP
recently suggested to me that because of the particular way it works,
the textbook system could be very useful to programmers and
configurers for large systems. (Who often find the documentation
written by the experts to be too detailed and low-level to navigate
effectively.)
Anyway, I'm interested in finding out how well the technology fits
into that of market (if at all), so I'd love to hear more about the
issues you and your team are facing, if you're willing to chat more
about it.
best regards,
Will Billingsley
Research Associate,
Centre for Applied Research in Educational Technology,
Cambridge University
On 6 Nov 2007, at 16:56, Ruven E Brooks wrote:
[EMAIL PROTECTED] wrote on 11/06/2007 10:21:14 AM:
> Who will be the reader of these documents?
>
> If the readers are going to be software developers working on
> the source do you think the exercise will be cost effective?
> After all, if there are only going to be a few readers and they
> are only going to read parts of the source (ie, on an as needed
> basis) then you documenting all of it may be more costly.
It takes a minimum of six months and, more typically, a year, before
developers joining this project have positive productivity, e.g. the
value of their efforts exceeds the cost in other people's time to
bring
them up to speed. From informal discussions, this length of time is
typical, or, perhaps, on the speedy side for applications of this
size.
If you assume that four or five developers on the team are being
replaced per year,
and that better information could cut the one year learning time
down to six months, then
we have something like 2.5 person years, every year, to invest in
getting and updating
the information.
The problems with just reading parts of the source, which is what
happens now,
are that it's often difficult to know where to start and what to
read. A large part
of the 6-12 month learning period is spend building up enough of
understand of the overall
structure so that know where to focus detailed understanding.
Ruven
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
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/
Re: PPIG discuss: Documentation for large systems
> 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/
Re: PPIG discuss: Documentation for large systems
[EMAIL PROTECTED] wrote on 11/06/2007 10:21:14 AM: > Who will be the reader of these documents? > > If the readers are going to be software developers working on > the source do you think the exercise will be cost effective? > After all, if there are only going to be a few readers and they > are only going to read parts of the source (ie, on an as needed > basis) then you documenting all of it may be more costly. It takes a minimum of six months and, more typically, a year, before developers joining this project have positive productivity, e.g. the value of their efforts exceeds the cost in other people's time to bring them up to speed. From informal discussions, this length of time is typical, or, perhaps, on the speedy side for applications of this size. If you assume that four or five developers on the team are being replaced per year, and that better information could cut the one year learning time down to six months, then we have something like 2.5 person years, every year, to invest in getting and updating the information. The problems with just reading parts of the source, which is what happens now, are that it's often difficult to know where to start and what to read. A large part of the 6-12 month learning period is spend building up enough of understand of the overall structure so that know where to focus detailed understanding. Ruven
Re: PPIG discuss: Documentation for large systems
Ruven, I have just been given the assignment of investigating techniques for documenting a 1.5 million line system. Who will be the reader of these documents? If the readers are going to be software developers working on the source do you think the exercise will be cost effective? After all, if there are only going to be a few readers and they are only going to read parts of the source (ie, on an as needed basis) then you documenting all of it may be more costly. Or perhaps this is a tick-in-the-box exercise (ie, some documentation has to exist). In which case why not run the source through doxygen, the results are not that useful, but it is very cheap. -- Derek M. Jones tel: +44 (0) 1252 520 667 Knowledge Software Ltd mailto:[EMAIL PROTECTED] Applications Standards Conformance Testinghttp://www.knosof.co.uk -- 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/
