Hmm, I think I'm qualified to answer this one.

[...throws away long answer no one will read...]

OK, to try and move this along,please list the chapter headings expected in this 'How to' book. I think that might shed better light on what people are after. In my experience (10+ years of this) everyone wants something different, but I'm always open to being wrong...  

@Hugh, thanks for the list, though as it covers everything, I'm not much clearer. "on how to use them" is very subjective. My experience here is many people don't want a general description but one much closer to their (intended) use, and with generalist tool like Tinderbox that's hard as they all tend to a different view.

The article by Steve Z is a nice one, though it describe TB in the context of an outliner. Thus there's a lot of redundant description of features that are common to several views. If each is described in chapters designed to stand alone there's lots of redundancy and, my my eye, potential first-reading overload. Strip it out and I sense push back of not enough detail.

My experience from helping people is that we tend to quickly get deep into a narrow area, the difficulty at start is trying to figure out which area that is. Often its a matter of suppressing assumptions about how things 'should' work to allow space for learning how they actually work in TB.

It's pertinent here to ask what's missing from the v6 'getting started' PDF?

How I learned TB, after reading all the material available was to set myself a task (that at outset I didn't know how to do). That forced me to try things and to ask questions when I got stuck. Other people's finshed models, so kindly shared, nonetheless were less helpful because of the issue of being just far enough from my task at hand. I've tried writing detailed worked examples, complete with finished per-stage example files (to help those who only want to read and not actual do the work) but all appearances are that despite being asked for, few actually do the exercises; that's frustrating as they take time and care to craft.

I also think the first two posts of this thread are pertinent.

One way to go might be to start a Tinderbox doc for yourself on "how to use Tinderbox." One set of notes would be to list the various sources of information on it including in the manual, Mark B's "Tinderbox Way," Mark A's sites, and so on.

I did that a couple of ways over the years, one in my "big Tinderbox" document and I finally created my own "Tinderbox manual." The main thing I find useful in the latter is an in-box approach where when I have a question or solve a problem, I make notes about it, complete with screen shots at times.

It helped after that to start to basically write an outline of the book that I think "should exist" on using Tinderbox. (I like to imagine David Pogue writing the "missing manual" as my imaginary muse guide here.)

That by no means implies I feel like I know all that much about it. I get stumped on some simple things fairly often, and so part of my "manual" ends up being my list of annoying features, usually based on my own habits of going trial and error instead of looking stuff up. (One problem for me has been remembering that there ARE several useful resources...I start just hunting and trying things and unlike with some software, that often just makes things more confusing.)

There is an old adage that you should "write the book you wish you could read," and I think that's really often the very best way to learn any complicated subject. Gradually, it's helped me to have my "A Better Tinderbox Manual" (for me) document in my dock, for quick note-making and references.

@Mark A: Your did it better. We much appreciate it.

@Will Duquette - I agree that having these in one place might help. Though there are a lot of bits and fragments of these kinds of things scattered about out there, likes parts of the scarecrow in the Wizard of Oz. These are both in this forum, in Mark B's book and writings, in some of the examples of things in the Eastgate website. There are some old workshop or web based tapes, people do stuff on some websites (e.g., Welcome to Sherwood, and Dominique Reynaud has a few nice examples and even a book, which, while in French, has helpful demo videos in it as it's an Apple iBook).

In my years of notes on Tinderbox, there are a bunch of little notes where I had problems with something using the syntax to getting an agent to work. (It is decidedly an "unfriendly" system for most normal non-programmers to have to write "syntax" to get software to do something in this day and age, but raising that point seldom gets one anywhere.) Anyway, speaking to your example of case studies or examples, I was just thinking that these case examples can become pretty specific and detailed, more than a generic book of examples might cover. For instance, I have notes of back and forth discussions by email with Stacy Mason when she was at Eastgate on how to structure a query for an agent.

I guess my point is that Tinderbox is a sort of "ecosystem" which, due to its complexity, one has to approach somewhat like learning a new language -- there is no single, one size fits all book for learning French. You do best with an evolving organization of your own learning tools, from books to audio lessons to mainly, just using it and trying to compile your lessons however you can, ordering food, getting a French friend or two to help. You can do a ton of great stuff with a little knowledge, sort of like using a basic phrasebook to order a croissant in Paris. But fluency will tend to ask a lot from one. Hence, for me at least, my geeky love-hate relationship with the thing.

@Will Duquette - Thanks. I'm a psychologist so "human factors" tends to be the place I get more annoyed. And so I do not like syntax.

I read once that the original "Murphy's Law" was named after a chief NASA engineer who made up a rule after a test rocket sled crashed. Turned out, they'd designed a part that it was possible to install on the sled backwards (so it would not work.) Murphy's new rule, after the crash, was if there is a correct way and an incorrect way to install a part, it must be assumed that sooner or later somebody would install it incorrectly. So the rule was to never build a part that could be put on the wrong way.  

There are about a thousand ways to write a line of syntax that don't make your agent collect the notes you want, and you have to get it, as a rule, exactly right. If you are NOT a software engineer but an "ordinary joe," that can become a pretty huge obstacle to using Tinderbox. At least with Excel, which is not something I love but is one of my daily workhorse tools, I know that if I hit a certain button on a toolbar, it will always, inevitably, do what it is supposed to do. I don't have to recall the proper way to hit it. That's, to me, the big "human factor" problem in learning this TBX ecosystem and its many jungle rules.

But like I said, "love-hate." "Tinderbox, I can't quit cha."  

Quote:


@Greg Korgeski: I actually disagree with your outlook towards the task. First, your assumption that learning a language like French has not principled and systematic ways of approaches to it, doesn't seem right. I am a linguist myself. I know for sure, some systematics approaches of teaching language for sure work much better than haphazard, disorganized methods; at least to the large majority of the language learners. Second, your representation of TBX as an "ecosystem" therefore, hard to teach (present) it in a constrained and systematic way is more of an attitude than a fact. We for sure know more complex tools than TBX, such as Emacs, Latex, C++ and the like...still, there are great, effective and comprehensive guides to these tools. A determined author can lucidly explain the most intricate scientific concept and programming languages...let alone  a fairly well-programmed tool like TBX.
TBX is a tool. It has limited number of features and commands. It is possible to take control of  (understand, teach) each of commands in a principled and systematic ways...and show these commands in practice (with good examples).  

It could be hard to decide which of the approaches to take to accomplish a certain task. yes, and the smart to approach is not to mention plethora ways of what TBX  "can do". Rather, take a smart decision on how to do the task  and move on showing how it could be effectively accomplished in that  preferred way (alternative approaches can be linked or footnoted).