Did you get #13. It has your submission on Documenting Frameworks. This one went out some time ago. Please let me know if you didn't. I think I've been having some trouble with people not getting it. I've enclosed a copy of #13. Since then I haven't gotten one submission. -Steve -------- Framework Digest Issue #13 Volume #1 Date Oct. 26, 1994 Number of Members: 374 To subscribe to this list send mail to Include the word "Subscribe" in the subject. To contribute ideas send them to You can get the FWList archives by anonymous ftp to st.cs.uiuc.edu in /pub/FWList or by sending e-mail to archive-server@st.cs.uiuc.edu. The files are called v1n1, v1n2, etc. To get v1n2 by e-mail, make the body of your message: send FWList v1n2 ===================== --Table of Contents-- ===================== * Calender of Events * From the Moderator * Framework Ownership * Documenting Frameworks ======================================== --Calender of Framework Related Events-- ======================================== * Designing OO Frameworks Seminar Nov. 14-16 Cupertino, CA ====================== --From the Moderator-- ====================== Hi everyone, Here is the latest FWList, issue #13. It appears that during the time I sent out issue #12 America Online's Internet gateway had a hiccup, and some of you may not have received issue #12. If you didn't please get it from the archives. In the last issue I proposed an idea about having many frameworks share the same interface. Paul Maynard, in this issue (see below), responds with concerns about legal, and ownership problems. I think there are many ideas which could offset this. Here is one possible idea. I think it would be possible for a group of small companies to agree on a standard set of interfaces for a framework, and then each could deliver their own version. The various implementations could compete in areas such as price, performance, and the platforms they are delivered on. The advantage to these companies is that they alone couldn't define a real standard, but together they could be a much larger presence in the market place. In addition potential buyers would feel more comfortable in buying into a framework where if one of the companies went away, their software would still be supported. Any thoughts? Steve Wilson Moderator FWList ************************************** From: paul@pixel.jtec.com.au (Paul Maynard) Subject: Framework Ownership (RE: From the Moderator v1 #12) Hi there, The idea that people could copy a frameworks interface and improve the implementation would be good except for the potential for legal battles. We already have wasted enough time over GUI look and feel wars and frameworks would be just as contentious. The lack of standards is bad enough with the current crop of C++ compilers and their associated class libraries. One might hope that Taligent could promise some leadership in this area given its wider field of view. Paul Maynard. (paul@jtec.com.au) ************************************** From: johnson@cs.uiuc.edu (Ralph E. Johnson) Subj: Documenting Frameworks I've had several messages asking me about how to document frameworks, so I figured it was about time to post something to the FWList about it. First, framework documentation has several types of audiences, and you need to tailor your documentation for each audience. One audience is someone trying to decide which framework to use. Documentation for this audience is more like advertising, it must describe what the framework is good for. The best way to do this is by example, though it is always rewarding to try to define the scope of a framework. This documentation needs to explain the more important features of the framework, but doesn't really have to explain how you use it. However, it can introduce concepts that you will need to understand how to use it or how it works. The second audience is the person who has decided to use the framework. This documentation needs to explain how to use it. It is important to realize that most people don't really like learning lots of technical details. In fact, they don't really want to learn your framework at all. They just want to get their work done. So, you need to provide some sort of cookbook that will let them quickly build their first application. I've always liked the MacApp cookbook as a good example of this. The VisualWorks 2.0 Cookbook is another good example, and will singlehandedly make VisualWorks much easier to use. My OOPSLA'92 paper showed how patterns can be used to provide this kind of documentation. This kind of documentation should avoid class hierarchies and technical discussion, and should focus on what the user of the framework must do. Examples are crucial for this kind of documentation, too. People tend to use examples here as starting points for their own applications, and then they modify them to get what they want. The third audience is the person who wants to go beyond the normal things that the framework can do and build new components, add new features, etc. This usually requires a much deeper understanding of the framework than you need just to get a simple application running. This kind of documentation needs to teach the collaborative model of the framework, the abstract algorithms that drive the framework. Formal methods might be good here, though I never have used them except for sometimes specifying invariants that a set of objects are responsible for maintaining. The ECOOP'94 paper that Kent Beck and I wrote describes the design of a framework in terms of the patterns that the designer followed when it was designed. But most documentation for frameworks is at this level, so in some sense it is not the level that causes problems. Your readers usually have some experience with the framework and are motivated, so it isn't as important to have good documentation. It is funny that the documentation that is least important is often the only kind of documentation that there is! Examples are useful for this third kind of documentation, too. Here, they are used to show the collaborative model of the framework. It is especially useful if you have debugging tools to single-step through a use of the framework. Note that examples are important for each kind of documentation! In my experience, examples drive the design of a framework, and they should drive the documentation, too. I've seen some frameworks with no documentation other than the examples. This is not ideal, of course, but the fact that people can get away with this shows how valuable examples are. You should be very systematic about choosing examples, and should probably have an official list of the examples that you are using. You can use this list in testing the framework as well as documenting it. In general, documentation should focus on the big picture and not the details. Smalltalk programmers can easily find the details using the browser. C++ programmers will need to use something else, I suppose. But generally the code describes the detail well, it just doesn't describe the big picture and it doesn't tell you how to use the details to make your application. So, the documentation needs to tell you what kind of features are available and the kinds of applications you can build with the framework (by example), the things you have to do to make an application, and the general collaborative model of the framework. It doesn't need to go through the whole class hierarchy and give a blow-by-blow description of each class. That kind of documentation just hides the good stuff and misleads the documentor into thinking he is doing something useful. Modularity is just as important in documenting a system as in designing it. People have a hard time learning big systems. So, you have to break it in pieces and teach one piece at a time. This is just as true for frameworks as it is for anything else. One of the nice things about the new Model-View-Controller is that it is built upon other other frameworks. In particular, the fact that Views are VisualComponents means that you can describe the graphics model first, making sure people understand VisualComponents well. Then you can teach dependencies, and show how Models and Views are related. Finally, you can talk about event handling, through in Controllers, and discuss how everything fits together. I find that I often change the design of a framework to make it easier to describe. I usually figure that a framework that is easier to describe is easier to use, too. Thus, the act of documenting a framework often changes it. You shouldn't think of documentation as something you do after the framework is all done, but an important part of the process of designing a framework. Documentation is a crucial part of any reusable software. People have to understand it before they can use it. But it is hard to make good documentation, and most people seem to underestimate the difficulty of it, expecting to hire someone to write in a month or two what they have spent many man-years building. To get good documentation, you have to test it and iterate, just as you do with software. You test documentation by having people read it and then finding whether they learned what you wanted them to learn. When you find weaknesses in the documentation, you fix them. There really isn't any magic in writing documentation, it takes hard work just like anything else that is worthwhile. It helps being a good writer, of course, just like it helps being a good designer to make a framework. You can get the two papers I mentioned by anonymous ftp from st.cs.uiuc.edu in /pub/patterns/papers. There is a mailing list on patterns in software to which you can subscribe by sending e-mail to patterns-request@cs.uiuc.edu. If anyone is trying to document a framework, I'm available for consulting. Ralph Johnson -- University of Illinois -- johnson@cs.uiuc.edu ************************************** End Frameworks Digest