Medusa As A Style Concept

[Marc Stiegler <marcs>]

In response to rick's comments on my documentation treatise, 
I have the following comment-comments:

Goodness! Rick, it looks like you've picked up on one of the, 
aaah, older traditional styles of commentary used in Xanadu discussions... 
oh, well :-)

I will resist the temptation to do a point by point response. 
Point-by-point responses to point-by-point responses wind up 
as "fractal discussions", which are completely unreadable until 
we have something like Tapestry (and probably aren't very useful 
even when we do have Tapestry :-)

Anyway, here are my comments on what I see as critical issues:

First, I am going to leap to a meta-level and observe that rick 
and I spent some time looking at different problems. For example, 
rick says,

"These wonderfully strange
and alien tools are going to be delivered as a XanaBase, no? 
 Intertwingled
with the tools are examples, tests, manpages, overview documentation,
and further reading, no?"

Yes, they are. That was my starting assumption. I am interested 
in answering the question beyond this answer: what does intertwingling 
mean? Should there be a link from every paragraph and every subroutine 
to every other paragraph and every other subroutine? Of course 
not. What good ideas can we come up with for what links should 
be included--and which links should not be included? 

I'm particularly interested in the links which should NOT be 
included, because of a traditional blind spot in Xanadu culture: 

Xanadian thought has always focused on making all things possible, 
creating a great diversity of alternatives. However, excellent 
tools are created through a dual process: making diversity possible, 
and then selecting those possibilities  which go together into 
an excellent system. Diversification must be followed by selection.

Xanadian culture institutionalized many techniques for punishing 
people who try to tackle the hard problems of selection. Rewarding 
people who throw stones, no matter how cheap or tacky the stones 
may be, rather than rewarding people who build houses, no matter 
how difficult the house was to erect, was one of the ways this 
was historically achieved. 

The occasional discussions of link types at Xanadu make a good 
example. Xanadian tradition says, "hey, we fulfilled our obligation--we 
made all link types possible. User, it's your problem to figure 
out which ones are useful". Well, yeah. But if there are 20 good 
link types, and 2000 bad ones that look nice, no one will be 
very successful. To the extent that we can, it has always behooved 
us (for the selfish reason of wanting to see our users succeed) 
to offer them guidelines in making selections. 

But at Xanadu, any attempt to propose a good collection of link 
types, or guidelines for helping users choose link types, was 
not met with "hey, better than any other proposal we've heard 
lately", or "well, how about this other proposal instead, which 
has the following advantages?" Rather, it was met with, "Gawd. 
Stupid." 

It is phenomenally more fun being the critic than being the author 
under such circumstances. Is it any surprise then that there 
were plenty of critics, few authors, of link type proposals?

We have exorcised many of these traditional Xanadian punishments 
in the past year. We no longer reward cheap shots, though, as 
is appropriate to a group so fierce about free speech, we tolerate 
them in spite of their unhealthy disincentives to creativity. 
Still, proposing selection concepts is a fool's errand in this 
part of the world.

Well, if someone does not give some thought to the selection 
side of the equation in using hypertext, our  hypermedia documentation 
will wind up as Medusa heads: tangled junk that turns users to 
sleeping stones when they try to look at it. 

Selection is my focus here. That is the purpose of style guidelines: 
selection of when and how to use tools that would be dangerous 
if used at random.

A couple of responses on particular selection issues:

-----
Rick says,

"Cycles and sharing can be powerful
organizing structures."

Yes, but they can also be sources of great disorientation. I 
have seen them
used badly several times; I cannot recall a really beautiful 
use. What we need is a more refined guideline, something which 
explains how and when to use cycles and sharing to promote understanding. 
In the absence of such an insight, if we don't caution authors 
(including ourselves) to avoid cycles, we'll just hurt the users 
with poor designs.

The article on building architecture that ravi just put out is 
a great step in an interesting direction. I observe that realm-control 
was also done very well in Hypercard Help: each Realm used a 
different background. I don't see how to use this insight in 
new and wonderful ways with Tapestry, though we ought to be able 
to do amazing things with Realm recognition in applications created 
with Montage. 

When we get around to Release 2 of Tapestry, we should remember 
to experiment with nestable border patterns to get a similar, 
possibly even better, effect than the Hypercard background control. 


--------
>Basically, we can use bookmarks not only for chunking, but also
>  to extract code templates from examples.

Rick says, 

"Isn't this just hypertext?  What am I missing?"

Yes, it's just hypertext. This is a particular way of using hypertext 
which I suggest is a good way of using it, and should be consciously 
selected as a use of hypertext when we write documentation. This 
may have been so obvious to some of the audience as to be boring. 
My apologies to those people. However, it belongs in our style 
guide.
------------
Rick says,

"The passages are written in a "natural size" and are included
via inclusion lists in some logical ordering.  Why in heaven's 
name
would you want to subdivide a passage written in optimal size?"

I don't want to subdivide a passage written in optimal size. 
I want to define optimal size based on constraints above and 
beyond the first stream-of-consciousness sizing pattern that 
happens to an author. 

"Natural size" is very much configurable by smart authors. Making 
natural size the right size for the situation is a fundamental 
part of good style, whether you are writing electronic material, 
paper, or clay tablets. We must answer the question of what natural 
size should be for hypermedia documents. If we fail to answer 
this question, we will not get more natural sizing--we will get 
poorly chosen natural sizing.

 I want authors to design chunks and passages that fit within 
the optimal size constraints imposed by the situation. There 
are 2 such constraints that I can point at easily: constraints 
because of the processing characterics of human brains, and constraints 
because of the low quality of computer screen resolution. Both 
suggest that we keep the size of the browsing chunk small, though 
it obviously needs to vary with the size of the thought being 
presented. 

I didn't even mention the second reason for small chunks in my 
earlier discussion: low screen resolution. But it is compelling 
all by itself. The 4 messages I sent around were too large to 
be good email messages. Everyone agrees about that. Yet if they 
were included in Abelson and Sussman as bold-titled subsections, 
no one would even notice them. Eyestrain is a serious consideration 
in chunk sizing.

--------
>  Good tracking helps the experienced user, but browsing helps
>  the beginner. And it's the beginner who needs the most help--and
>  it's the beginner who makes your product, or breaks it.
>
Rick responds,

"Does this hold true when your users are experienced system builders?
This is the audience I expect for a C/C++ toolkit.  Your arguments
are certainly appropriate for the expected audience for a Montage-like
product, but I'm not so sure when we're talking about Real Programmers(tm)."


I submit it even holds true for experienced system builders. 
Despite their macho opinions of themselves, it took a great many 
of them a great long while to transition to the paradigms needed 
to work with windowing systems. Windowing systems, and the wild 
and woolly way you pass procedures around, qualified as "strange 
and alien" to even Real Programmers, at least to Real Programmers 
outside the world of Object Afficionados (tm). 

If you restrict your definition of Real Programmers to Object 
Afficionados, of course, you're right, just give them a 10,000 
item index and let them suffer, they'll thank you for it (funny, 
how the Puritan ethic "suffering is good for you" pops up in 
the most unlikely places). But the Object Afficionados don't 
write most of the software in the world. They don't even write 
most of the useful software. They may write much of the great 
software...though I could even argue with THAT :-).

How many more programmers would have written more good Mac software 
(and good MS-Windows software) sooner if they'd had a browsable 
Help system to get them over the paradigm hump at the beginning? 
Perhaps you'd say zip;  I would say more; with Xanadu, I don't 
want to take the chance. Since it's not incompatible with having 
an indexing system at the same time, there's not much to disagree 
over.
-----
Rick asks whether we are making a mistake, not building a tool 
specifically for creating/presenting preplanned hyperstructures. 
This is an important question. I've thought about it periodically 
ever since coming to Xanadu. 

I believe our current focus is correct. Preplanned structures 
do not push hypermedia to its limits: the preplanner can work 
around many particular limitations in his tool. Consequently, 
existing hypermedia tools (like Guide, for example) handle preplanned 
stuff fairly well. 

Yes, we can do preplanned documents better than Guide--but Guide 
can't do evolving hyperstructures at all. Montage and Tapestry 
position us where we have the maximum leverage, the clearest 
opportunity to demonstrate our fundamental superiority. We can 
build the great tool for building/presenting preplanned hyperstructures 
using Montage. Indeed, we can probably build it fastest by building 
Montage first, and then building it using the great productivity 
enhancement Montage will offer :-) Meanwhile, I can see Owl and 
Macromind and the Yost Group all grabbing this market firmly 
by the throat for us; we are not even needed there, I believe.

-----
Rick, what do you mean by a permuted index? I suspect I know, 
but would like to make sure. I find flat indices in books almost 
useless in paper, and worse on computer screens.

-------
Rick says,

"As I'm cruising along I can
either be in "reading" mode or in "browsing" mode. This is *my* 
choice as
reader, not *yours* as writer, kemosabe!"

Of course it is your choice, comrade. But by using different 
stylistic approaches, the author can facilitate one or the other--or, 
hopefully, both. And it is important for him to try facilitate both.

Any time the author abdicates his responsibility 
for facilitating the reader's efforts, either by refusing to design
his chunk sizes well, or by refusing to pause for a moment before
taking the cheap shot, you have a communication disaster--the 
mirror image of the disaster you get when the reader abdicates
his responsibility to try to understand in spite of the imperfect
articulation made by the author.

The use of one-ended links as bookmarks does 
not prevent you from using the scroll bar. But I believe it will 
help browsers like hugh. 

And if we cannot facilitate both readers and browsers, then 
we should facilitate 
browsing with the electronic medium. Let the linear readers read 
linearly with paper; paper is superior for this application anyway.

--------
Rick asks,

"What about users' adding to our as-supplied documentation?  
Is it
their responsibility to update the maps?"

To the extent that we use inclusion lists as maps, and to the 
extent that people add new material by adding new sections to 
the inclusion lists, the maps are self maintaining. If a user 
wants to add a new browse-size chunk, and wants to add it in 
such a way that it will be useful to others (rather than just 
to himself), he will want to consider all the devices Tapestry 
has to offer as ways of leading people there: he might add it 
to the list of upcoming subtopics on the local map and/or run 
a link from the local map to the new material. I think we can 
introduce more semi-automated mechanisms with software written 
in Montage.
--------
Rick says,

"Maybe, but Montage will work better than Tapestry.  Nyah, nyah!"

It certainly ought to work better. The potential for building 
wondrous documentation with Montage  is so great it makes me 
giddy. However, if the developers of Montage documentation reject 
all concepts for good style, and choose instead to build Medusas, 
then Montage documentation will merely be fancier, not better, 
not even as good.
---------
---------
I did not particularly plan the sizes of the chunks in this discussion, 
so the sizes of the chunks are "natural size for marcs writing 
critical responses with Architext on a big monitor in 9 point 
type". Rick, do you like the chunk sizes more, or less? How about 
you, hugh?


--marcs