[Date Prev][Date Next][Thread Prev][Thread Next][Author Index][Date Index][Thread Index]
Medusa As A Style Concept
- To: <xtech>
- Subject: Medusa As A Style Concept
- From: Marc Stiegler <marcs>
- Date: Fri, 9 Mar 90 09:55:51 PST
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,
"These wonderfully strange
and alien tools are going to be delivered as a XanaBase, no?
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.
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:
"Cycles and sharing can be powerful
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
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.
"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
"The passages are written in a "natural size" and are included
via inclusion lists in some logical ordering. Why in heaven's
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
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.
"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
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.
"As I'm cruising along I can
either be in "reading" mode or in "browsing" mode. This is *my*
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.
"What about users' adding to our as-supplied documentation?
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
"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