Re: [zzdev] a version of the user's guide

[Katariina Ervasti <cat@xxxxxxxxx>]

Hiya.

> As a beginning, it looks good!
> 
> (In the long run, though, 
> ... it should be organized in multiple, different structures, as I said
> later.

I agree, but, as you write, that's in the long run.

> > (I don't know how long it will take 'till we get the WML
> > issue settled so --- That's why it's there at the moment.)
> 
> Why don't you simply let AJ convert it to WML? Your discussion was
> interesting to witness, but I really don't see any reason not to take

We're ... kind of ... agreed on the WML issue. A-J will convert it
to WML.

> > The doc doesn't look very beautiful, I just put the tags there in
> > a hurry.
> 
> One thing: could you (as an intermediate) make a page which has all the
> figures on it? That would make downloading them all easier.

Yesterdau evening I was reading Dilbert and there was one strip
dealing with this issue. Dilbert is having a discussion with himself
which goes like this:
- I calculated the total time that humans have waited for
Web pages to load ...
- It cancels out all the productivity gains of the information age.
- Sometimes I think the Web is a big plot to keep people like
me away from the society.
 
:-)))) Dilbert is a great philosopher.

Anyway, I just though that putting all the images on the same
page would make the doc too slow to load. (At the moment there 
are about 30 .pngs and the amount of images is increasing all
the time.)
 
In the future, we can make a full-lenght version of the doc 
AND a version that is cut into parts.

> I feel it should also be organized in different structures, like, making
> trails out of it showing how certain structures are build. (That, again,

Hmh, yes. In the current version I've only described how the linking
of the addressbook-familytree was made, but it would probably be
a good idea to introduce some other example structures as well.

On the other hand, according to some writers interested in 
techinical communication (which is a growing field of research)
a good user's guide follows the principle of minimalism. 
Minimalists believe that people don't really have time to
read user's guides, the smallest possible amount of information
(which makes the reader understand) should be given. This
means that the writer thinks that the user can find out creative 
ways to use the product without a great amount of examples.  

Nevertheless, GZigZag is a rather complicated thing and 
we can link the examples so that you don't have to read
every example, if you don't want to.

> > It will be a HUGE document since we want it to cover every
> > aspect of the use of GZigZag.
> 
> I suppose you do accept submissions -- is there anything where help is
> needed? (Like the cell views -- I'm familiar with them?)

Hmh, you have been coding GZigZag, are you sure that you can
take the perspective of the user? ;-) 

Seriously, according to some writers an ideal writer of a user's
guide sure knows how to use of the product, and does NOT have
deep understanding of the techinical implementation. If the
writer knows too much about the technical stuff, there's a danger
that this information will end up in the user's guide (even
though the users are generally NOT interest in that kind of
information).

No, I know a good one for you. Tuomas would like to have a guide
explaining how you can code a specific view for a certain 
structure (e.g the DayView used in the Cybertext article). 
According to his opinion I should do this, but I'm not sure 
whether I want to learn Java. (Well, I know some Java but I 
don't think programming is fascinating. So learning how to
make a view with Java sounds like a borig task to me.) Would 
you possibly like to write that?

If somebody else reading this is interested in the
documentation of GZigZag, feel free to express your interest.
There ARE things to do.
 
> By the way, I noticed you say 'colour' -- are you using British English,
> some other English, or just some random mix? Not because I'd mind

At the moment it's a random mix. It's English of a Finn mainly
influenced by a New Zealander and some British people. Yeah, 
you're right, we should stick to one way of using English but I'm 
not sure whether I can write like an American. (I'm not worrying
about that at the moment too much. Like I wrote before, the 
language of the doc is still under construction).

> Are you interested in networking on how to explain GZigZag? I really

Sure. An ideal situation would be that everyone interested in
GZigZag would also be interested in talking about the language
we're using. But that's an ideal situation. I know that most
people who like programming prefer programming from talking
about the language they use. ;-)

We need to develop a better glossary (there's one made by Tuomas
on the Web) which will cover EVERY strange term somehow connect
to GZigZag.

> agree with your earlier comment that gzz has developed a lot of own
> language which sounds like buzzwords ("relcells?"), a practice which I
> basically resist -- not limited to computer science, I just hate these

Specialists in every field have a language of their own.

cat