Archive of UserLand's first discussion group, started October 5, 1998.

I don't need another graduate degree

Author:russ@psyex.com
Posted:7/28/1999; 4:23:21 PM
Topic:The Doctor is In
Msg #:8849 (In response to 8821)
Prev/Next:8848 / 8850

I too am really excited that a Frontier master will be putting serious work into the Frontier documentation. That said, let me piss a few people off . . .

Worries about Matt's writing: Matt has written some really good tutorials, a thorough *reference* book, has personally e-mailed me with helpful tips, and I like him. But there are two reasons why Frontier hasn't taken off the way it should have--bad documentation and no marketing.

"The Book" is not a book with which (almost) anyone but a fairly seasoned programmer would successfully learn Frontier. If "The Book" was written with the goal of serving as a reference manual, so be it. But if Matt wrote it with hopes it serving principally as the best way to learn Frontier, then I am very worried. Writing good learning material requires understanding the basics of how people learn. The Book (as well all know) did not display a mastery of this. If UserLand is in need of help in this area, then one might suggest a company called Information Mapping that teaches almost all of the big silicon valley tech writers how to set up good documentation based upon good cognitive research about how people learn.

So, I'm worried about Matt's writing because his knowledge of Frontier is often put on display in the steel grids of organized details, not in easily-learned prose. And it doesn't have to be difficult material right? Because, after all, Frontier has reasonable, intuitive ways to help you get what you want done. And easily-understandable documentation is what will increase the Frontier base of users.

This isn't rocket science. Imagine that you're considering a new language/development environment to learn. You walk down to Borders book store and browse through a couple of dozen beginning-Perl books and then you browse through ch. 41 of Matt's Book. It's no contest. You choose Perl unless you have an abundance of faith or are in need of a pet research project. We have made the minority choice; we *are* the faithful and the hardy. Yes, there's on-line documentation. Now let me see a show of hands: How many people prefer on-line documentation over a book? That's what I thought, 1 out of 4000. I looked at the on-line documentation for how to set up the discussion groups I need to build. I still don't have much of a clue.

That critical MacWorld review of Frontier's bad documentation wasn't an anomoly. Now, if UserLand is going to address this problem, do it in a way that will create a good, readable, book that will show the strength and utility and usability of Frontier.

Now, I'm sure that as a result of this rant I've decreased the liklihood of getting any help through the mailing lists, but it had to be said. I hate to see such a great product wasting away only because so few know about it (no marketing) and of those that do know about it, only 5% have succeed it making it through the learning curve to do anything with it (lack of accessible documentation).

Russ McBride

There are responses to this message:

This page was archived on 6/13/2001; 4:51:35 PM.

© Copyright 1998-2001 UserLand Software, Inc.