It can be tempting to provide examples of what not to do, but the problem is that then the user is resting their eyes on invalid or bad code. In many such cases, a simple DO and DONT list is more clear and less disruptive to the learning process.
Most of the TCL docs are "What to do" not "How to do it".
LV: [SNIP] How about you write a document in the style that you seek?
LH: Well, I have a dream about just this very thing. As a non-programmer, I am often stumped by the examples in books. Generally, the section will discuss a topic, and give a short example. If I "get" the example, fine. If not, well......
My dream is a scripting language framework for someone who (like me) is new to programming. It should be able to teach the language and the concepts of programming at the same time. It should be okay material for someone who chooses scripting as a first language.
For example, in a section you discuss the 'list' command, and give two or three examples. Then you have a workbook section where the reader is given a problem, and then a possible solution with a good explanation.
If this were structured, you could combine three to five sections into a chapter, and have the chapter build some useful larger program that demonstrated programming concepts.
My dream requires different skills. It needs some educational theorists who can design the structure and pace the learning. They would also identify different learning styles and advise on how to accomodate them.
It would take the skill of breaking a concept into small parts, and showing how each part works to someone without the writer's level of skill.
It would take people who can clearly communicate programming theory; both the concepts and experienced-based "best practices".
Make sense?
GPS: That makes a lot of sense. In some ways the book Effective Tcl - Writing Better Programs in Tcl and Tk teaches in this manner, but I don't consider it to be a beginner's book.
LH: Effective Tcl is a good book, but you are right, it does not seem to be a beginner's book. The BOOK Tcl/Tk for Real Programmers is another good book, but again, it is even less for non-real programmers. Ousterhout's Book Tcl and the Tk Toolkit is a good level for newbies, but doesn't build the meta-skills. Welch's Book Practical Programming in Tcl and Tk is good, but again (my copy is the 2nd ed.) leaves new programmers behind.
I think that the wiki has a lot of opportunity in this area. If you have some code and an example, and someone doesn't understand, you can easily add another example. You can also review questions on places like c.l.t. (the comp.lang.tcl newsgroup) and integrate the answers here.
DLB Alan Gauld's online tutorial "Learning to program" IS aimed at non-programmers. While the principle illustration language is Python, he also gives examples in Tcl (included with Python distributions) and Basic. http://www.freenetpages.co.uk/hp/alan.gauld/
LV Alas, while he previously provided alternative examples in Tcl and QBasic, he now provides them in VisualBasic and JavaScript.