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 relation

2. 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:

This page was archived on 6/13/2001; 4:50:45 PM.

© Copyright 1998-2001 UserLand Software, Inc.