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.
