I like your cookbook, Skip. Monkey-see-monkey-do, we used to call it. Your "3 principles" are basically sound. They resemble "Minimalism", developed by Jack Carroll at IBM Yorktown Research. There's a huge literature on the topic. E.g. see http://www.hcibib.org/ --of which [task-oriented] documentation was a substantial sub-topic. A hot one in the late 80s, with a wealth of practitioners. But they seem to be getting rarer. The state-of-art is actually going backwards. Was it Mark Twain? ... damned easy reading is damned hard writing. Hard in the sense of "laborious", not "unresearched".
People nowadays just copy an example of manuals they like. But liking is a poor predictor of effectiveness. Ian On Tue, Feb 9, 2010 at 6:06 AM, Skip Cave <s...@caveconsulting.com> wrote: > I recently finished authoring a book that teaches beginners how to > program VUI (voice user interface) applications using a specialized > (and obscure) programming language called Interaction Composer. I wrote > the book, called "The Interaction Composer Cookbook" in a style similar > to the "For Dummies" book series. Doing that gave me some insights as to > what it takes to write for the novice. > > I have been told that my book makes it very easy even for rank beginners > to start developing voice applications with the language. You can > download a copy of the book in PDF format here: > http://www.teledon.info/CVG/IC_Cookbook_v2.pdf > > I didn't use hyperlinks in this book because it was intended to be > published in printed form as well as electronic form. > > This book is written in a linear tutorial style which makes it much > easier to bring a novice along, than a random-access reference tutorial. > I was able to introduce new concepts in a linear sequence that optimizes > the learning curve. The J reference-tutorial will be more difficult to > create, as it needs to deal with readers who can enter the tutorial at > any one of 120 places at random. However, I believe that there are a few > key philosophies that I used when writing the book that are still valid, > even for a random-access reference/tutorial. > > 1) Never introduce any concept before it is needed to explain the > current example that you are working on. Putting lots of "this is > interesting" or "you will eventually need to know this" links in the > text will cause more distraction and confusion than help. > > 2) .Never talk about more of what a function can do than is needed for > the current example. > > 3) Try to introduce only one new concept per example. For that matter, > several examples may be needed to introduce one new concept. Take baby > steps, not leaps of intuition > > I am convinced that a J tutorial can be made useful to both the total > novice and more advanced users. However, people with the skills to write > that way are fairly rare. It doesn't necessarily require a novice to > help write the tutorial, though that can be very useful. However someone > experienced that can remember exactly what problems they had, and what > concepts were difficult to understand, can be just as helpful. > > Skip Cave > > ---------------------------------------------------------------------- > For information about J forums see http://www.jsoftware.com/forums.htm > ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
