Path: utzoo!utgpu!news-server.csri.toronto.edu!cs.utexas.edu!uunet!convex!convex!connolly
From: connolly@convex.convex.COM (Dan Connolly)
Newsgroups: comp.windows.interviews
Subject: Re: Interviews documentation
Keywords: Examples
Message-ID: <1991Jun04.041701.21620@convex.com>
Date: 4 Jun 91 04:17:01 GMT
References: <9106040032.AA23987@hadar.fai.com>
Sender: connolly@convex (Dan Connolly)
Organization: CONVEX Computer Corporation
Lines: 43
Nntp-Posting-Host: pixel.convex.com

In article <9106040032.AA23987@hadar.fai.com>, adobe!hadar!michael@LABREA.STANFORD.EDU (Michael Young) writes:
|> 
|> 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:
|> ------------------------
etc...

I too have just spent several days porting an poring over interviews 3.0.

First: Nifty! I like it.
Second: What I need is examples.

Good doc is hard to write. It's hard to keep accurate and up to date. I think
that for an experienced InterViews programmer, 
the time it takes to write a page of example code is much less than the time to
write a page of quality doc, and folks learn abstract concepts monkey-see-
monkey-do much easier than trying to understand prose descriptions.

For every class, or every closely related group of classes, I'd like to see
a one- or two-page example demonstrating its use. This would help clear up
my confusion over what classes implement the 2.6 (interactors) style and
which ones do the 3.0 (glyphs) style and which ones do both.
Plus, to see if example code is up to date, all I've got to do is compile
it and see if it works. I can trust it much easier than a man page.


I'd REALLY like to see more work on iclass:
* if I'm browsing something like:
class A{
  public:
	bcd(int x, int y);
}
	I'd like to be able to click on bcd() and see:
	* the code that implements it (the REAL doc :)
	* the man page that explains it.