Hans, Taco, et al,
It's time for me to wax philosophic on the beginner's manual. I've
read a few posts to this list, and tried to think back to my
experience, and looked at my troubles now, but I haven't reread the
beginner's manual as yet. That I will do in the upcoming weeks.
My first thought is this: In my opinion, the beginner's manual
remains one of very best sources for Context.
My second thought is the fact that this is a beginner's manual in
every sense of the word. That is, you need to be very careful with
what goes into the manual. Truly, a guiding principle should be: What
does a beginner need to see? Think of a user who is beginning with a
blank slate, or alternatively, think of a user who's been gone for a
while (I've qualified for this category on several occasions and
revisiting the beginner's manual has always been helpful). What does
this user need to see? And what does this user need to be protected
from?
First and foremost, you've got to make sure that users on different
platforms have a good install of Context. This could be a set of
appendices: Appendix A -- Installation on Windows, Appendix B --
Installation on Linux, Appendix C -- Installation on Mac OS. Again,
users could be very helpful in testing these instructions. This is a
"beginner's manual," so it would be helpful if these instructions
were of the "Quick Start" variety, as involved instructions will only
serve to frustrate the beginner. Of course, these instructions should
include a "Hello, World!" example in order to test for a valid
installation.
Whenever I teach a new concept in mathematics, I'm faced with a
choice of two directions. I can start with the concept, then give
examples. Or I can do some examples, then discuss the abstraction at
a higher level. I am constantly forgetting that the second method is
usually a better choice for my students. For example, suppose that I
want to show that any multiple of an eigenvector is again an
eigenvector of a given matrix. I can first prove it in the abstract (A
(cx)=c(Ax)=c(lx)=l(cx)), then give examples. Alternatively, I can put
a little 2x2 matrix on the board, find the eigenvectors, then
demonstrate that multiples of the eigenvectors are again
eigenvectors. Once the students have the idea, then I can put up the
abstraction of the general proof. A reference manual is an example of
the first method, a beginner's manual should follow the second
method. It's easier, in my opinion, to learn by example, to learn by
doing.
Topics should be included or excluded based on a guiding principle:
What does a beginner need to know to get started? It will be tempting
to include using a different font, or talk about interactive
documents, etc, but these are advanced topics, which belong in
separate manuals where space and time will do them justice. Indeed,
what is truly needed is a separate beginner's manual on interactive
documents.
Layout really threw me for a loss the first time (and times
thereafter) I went through the beginner's manual. I was confronted
with terms (cutspace, backspace) that might be familiar to
typographers, but I had no clue what they meant. I can remember
spending countless hours tweaking layout parameters, printing, then
measuring with a ruler, only to scratch my head when I did not get
predicted results. To this day, I am still not completely sure what I
am doing in this area. I think what is needed in the beginner's
manual is an image similar to Patrick's \ShowLayout result from his t-
layout module. Secondly, it would be time well spent to build an
improved \showframe command. Perhaps this even exists, but I am not
aware of it. It needs to provide accurate measurements, even when
printed and the rulers come out. Perhaps if a user included the
\showframe command, a trigger of some sort could change the size of
the paper that the document is typeset on, with an outline of the
actual paper size, and the edges, margins, headers, etc, all framed
and in view, even if they lie outside the actual paper outline.
List users can help to make sure that the manual is free of errors.
If something doesn't work, this is much more upsetting to a beginner
than a seasoned user. A seasoned user might say "oh, that's just a
typo, do this," but a beginner has an entirely different reaction on
an entirely different emotional level.
Troubleshooting should get some time in the beginner's manual. People
coming from a Word environment are not going to understand what is
going on when a compilation halts. Seasoned TeX users know about
typing h, x, s, e, etc, but people who've never seen TeX before are
going to freak out. So, some time should be spent on troubleshooting.
Or, a conscious decision has to be made: Will we assume that all
beginners in Context have TeX experience?
So, I advise, stick to the basics. Get the user started. Ask yourself
what a user needs to write a good paper: Title page, abstract, toc,
index, bibliography, section headers, headers and footers, footnotes,
labels and references, mathematics (somewhat weak in the current
manual), tables, figures (including the idea of floats which bothers
users coming from Word no end), lists, layout, alignment, quotations,
formating text (bold, italic, slant, verbatim, etc), defining new
environments for examples, definitions, theorems, etc., and some
small macro capability.
Finally, you should certainly provide pointers to advanced documents
where users can continue their growth.
I hope this helps.
David
_______________________________________________
ntg-context mailing list
ntg-context@ntg.nl
http://www.ntg.nl/mailman/listinfo/ntg-context
