Newsgroups: comp.windows.interviews Path: utzoo!utgpu!news-server.csri.toronto.edu!rpi!zaphod.mps.ohio-state.edu!wuarchive!uunet!stanford.edu!LABREA.STANFORD.EDU!adobe!hadar!michael From: adobe!hadar!michael@LABREA.STANFORD.EDU (Michael Young) Subject: (none) Message-ID: <9106040032.AA23987@hadar.fai.com> Sender: news@shelby.stanford.edu (USENET News System) Organization: Internet-USENET Gateway at Stanford University Date: Tue, 4 Jun 1991 00:32:07 GMT Lines: 134 This is LONG, so read only if interested. To the InterViews people at Stanford: After struggling to understand InterViews 3.0, I have come to the conclusion that this is what is needed: ------------------------ InterViews Style Guides: ------------------------ 1) What is the philosophy behind the whole toolkit? (high-level description) - What level of abstraction was desired. (Who should be using this?) - Should the user have to know about the underlying windowing system? (no!) - What is the basic "object" in InterViews? - What does every "object" consist of? (i.e., Glyph should only have a drawing mechanism, but users can add context. (bad style?)) - How do objects communicate? (i.e., relating a scrollbar to an editor) - Who draws on the screen and why? (i.e., show DAG with window Glyph at top, percolating information down or whatever.) 2) What are the abstractions? (lower-level description) - InterViews is currently based on X. Where is X behind this? - How are the "look" and the "actions" separated? (i.e., Glyphs) - Look and feel abstractions. (i.e., the ability to abstract away OpenLook and Motif from an application.) - Explain subclasses, and show examples of use. (good ones!) - Which classes are for the "look"? - Which classes abstract X or Unix or something else? - Which classes are universal? (Glyph, Window, Event, Glue, etc.) - What tasks were in mind when InterViews was written, and which classes deal with these tasks? (StringBrowser, Brush, Rubband, Discretionary, Strut, etc.) - Which classes should I use to arrange objects on my screen? (Lots of confusion over Composition, Page, Layout, Boxes, Deck, Canvas, Scene, Subject, View, Window, World) All these things do roughly the same kinds of things, arrange objects in an X Window. A better abstraction (or at least explanation) should be provided. 3) How are they implemented? (nuts and bolts description) - Which objects "know" about user input (mouse, keyboard, etc.)? - If I'm a character glyph, who tells me to draw myself and what information do I need? - What classes inherit what and why? (graphical explanation needed) 4) How should the programmer implement them? (guide) - Should be fairly self-explanatory if first three things are explained well. - Important philosophical points should be mentioned and shown in examples. (What to do/What not to do.) (A little criticism:) There are many, many more questions, but I just typed this up in an hour. Man pages just don't cut it. I'd also like to point out that current reference manuals/user's guides don't seem to know what audience they target. Some should be clearly "BEGINNER'S GUIDE TO ..." and some should be "ADVANCED ...". All the guides now seem to be middle of the road with abstractions and details all thrown together for the reader to sort. Start out with the general descriptions and then progress into more detailed explanations of the same material. I believe a key to good manuals is to assume a forgetful reader. Remind people what classes do. If a Glyph is explained on page 5 and you then refer to a function of class Glyph on page 50, it should be explained again what the purpose of the function was. Many times, this style is lacking in InterViews documentation. For example, 1) InterViews Reference Manual Version 3.0 (page 6, top of Chapter 2) (Note: I just flipped open the manual to find this page.) "A glyph is an object that draws. Glyphs are the basic unit for building the presentation side of a user interface." - Sounds important. How many pages are devoted to explaining the abstraction? Less than 1/2. - WHY ARE GLYPHS USED? - We were using Interactor before; why the switch? - DOES THE ABOVE MEAN THAT ANYTHING THAT DRAWS IS A Glyph? 2) InterViews Reference Manual Version 3.0 (page 27, Section 3.2) "A canvas is a 2-dimensional area on which to draw." - Draw what, specifically? (What domain do Canvases cover?) - Since a Glyph is the basic unit of drawing, and a Canvas is an area for drawing, I guess a Canvas is derived from a Glyph, right? WRONG!! (Explain why.) 3) InterViews Reference Manual Version 3.0 (page 39, top of Chapter 5) "This chapter describes the InterViews mechanisms for processing user input." - How about explaining some policies as well? - This is SO important, but less than two pages of text are devoted to input handling. - Where are the Glyphs or other drawing objects in this? When abd where do they see the user input? (By the way, I'm not just criticizing the Reference Manual only, it just happens to be the first thing I picked up. And I understand that the manual is not complete, so please take my criticisms as some direction for the finished product.) Don't assume I've read any other manuals, or at least mention that "the reader should be familiar with ... or read ... in ...". Prepare a master list of manuals to be read by beginners. A good way is to write the four manuals I've detailed above, and instruct the reader that the four manuals should be read in order. Although the style guide (the fourth manual) should probably be broken up. (Basically, prepare an on-line course for InterViews. If you were to teach a class, what would you do? Be prepared for people who are just learning C++ as well.) Please, treat me like an idiot when writing manuals. Repeat yourself. Don't assume I can think and understand implied details or abstractions. Nothing is too basic to explain. When you learn something new, usually, you are very unsure. A manual that is vague only makes for uncertainty and frustration. Clarity is absolutely key. I believe you can cut the average learning time down to maybe two or three weeks at most. The abstractions are pretty good. The explanations are not so good. It would be nice not to have to dig through the header and source files so much to learn this stuff. Thanks. Michael Young michael@hadar.fai.com p.s. You should remind yourself of how our educational system works. Lower division courses in college are very general. Upper division is more detailed, and graduate classes are even more detailed. Start in general terms, then add more detail. Don't throw everything together. And as you explain things in more detail, refer back to the old material often. p.p.s. Perhaps you can use ibuild to create help programs. That shouldn't be too hard.