Re: beginners manual

[David Arnold <darnold@northcoast.com>]

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