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/
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
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
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
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, 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
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, 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
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
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
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/
