Archive of UserLand's first discussion group, started October 5, 1998.
Re: critic on bad documentation
Author: Oliver Wrede Posted: 6/13/1999; 11:38:14 AM Topic: critic on bad documentation Msg #: 7297 (In response to 7295) Prev/Next: 7296 / 7298
Ok....it's key to understanding the concepts
I know. I think people need some sort of preparation, before they see the pieces founding the concept.
In Frontier 5 it was relativly hard to understand how it works. Much of the things happening were just hidden. It was a new way, how results were reached - nut much of the premier knowledge (from the usual CGI things) was applicable. It took me months to understand what happens where, and where I have to put what. After I understood, how the scripts work, it seems I had some sort of a blueprint of how Frontier works for me (and so creating ideas how to script it). I was able to operate in a relativly profitable trial-and-error mode then.
In Frontier 6, things seem to be more complicated by a magnitude. On the one side I am told "We wanted a single responder that did everything, so we could get the details out of the way" on the other hand I have to learn a huge amount of new things, and I cannot distinguish which information is important and which is not. If I want to do something, it seems I have do tweak many more things until I'm set up (of course this is subjective).
Inspired by this I sometimes find out, that things in Frontier 6 are often much more easier to do, than I initially thought (thus I was programming with a lot of overhead in my scripts).
So here is my suggestion:
1. Do a "blueprint" of Frontiers framework
This could be a diagram which shows all parts and their relation2. Make easier examples
...not complete applications as examples. A possibility would be to tell little stories like "Lifecycle of a HTTP request" or a "Step by step: from idea to a website" or "What is different in Frontier compared to ..."You are using a lot of vocabulary, which is not self-explanatory. I would suggest to help beginners with a real glossary, where they can lookup a meaning while reading a text. Words in this glossary are no chapters in the site.
I am sure answers to questions can be found anywhere in your website - but they are scattered in pieces or hidden in examples. The Frontier website was obviously written by people who know about Frontier. I did not have the feeling that I am taken from where I was -- I had to move toward Frontier to get it (meaning I had to tolerate a fair amount of frustration until I understood something work).
What is hard to understand is, that Frontier 6 gets a new level of abstraction into the main tasks. This implies a greater distance between what the scripts are doing in detail and how they should be used.
But a more concrete example I will put in another message...
There are responses to this message:
- Re: critic on bad documentation, Dave Winer, 6/13/1999; 11:46:34 AM
This page was archived on 6/13/2001; 4:50:45 PM.
© Copyright 1998-2001 UserLand Software, Inc.