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

Re: For Review: Frontier Getting Started Guide

Author:Emmanuel M. Décarie
Posted:3/26/1999; 9:30:25 AM
Topic:For Review: Frontier Getting Started Guide
Msg #:4558 (In response to 4528)
Prev/Next:4557 / 4559

First I want to salute this initiative. This is great to have an "entry level" doc to Frontier. Nice ! And I can see that a lot of work when into it. These are my first impressions, and since I didn't have the time to go very deep in this document, they might sound a little bit superficial (or not).

Ok, here I go with my comments.

• Format

I guess that a non-printing version is in the work. I'm sure a lot of people will want to have a quick look to this doc without printing it. So I suggest for this case an other version split in 2 or 3 pages to allow fast loading.

Also, if the purpose of the document is to be printed, why not offering a PDF version with an improved layout ? Not that I find the layout bad, I like it, but I think PDF files are more suited for printing than HTML.

• Introductions or introduction

I think that you have very important information in both introductions to the website tutorial and the scripting tutorial that should be in your general intro. IMO, the intro to each tutorial are giving information that are crucial to the understanding of the purpose, the heuristic and the prerequisites of the whole document.

What you are saying in the WEBSITE tutorial INTRO is;

1/ You don't have to know Frontier to read this tutorial.

2/ You do need to know HTML.

3/ You don't need to know scripting/programming.

4/There is an order to read this tutorial that is linear.

What you are saying in the SCRIPTING TUTORIAL INTRO is;

5/ What is UserTalk.

6/ You need to have read the website tutorial.

7/ What is the purpose of this tutorial.

We can see that points 2, 4 and 6 are part of the general precepts of the whole doc. But even if the other points are more geared to one section in particular, I think they also should figure in the general introduction of this document.

• Is there something missing ?

I'm not sure about this one, but I think that there is a section missing here that will present the most important parts of Frontier UI. But it depend of the purpose of this document. If its the first thing a newbie will read, I think a short general intro to the Frontier UI is important (What you will found in the Frontier folder, the app, the root, the menus, ...). Just the striking features, not the whole sheebang.

But as I said, it really depend of the purpose of this document. If it come first or not. And also, maybe the best way to learn the WSF, is to jump in it without having to read anything before.

• Menus

Also, it could be nice to have some screenshots of the menus. And I'm not sure of your notation to the path for a sub-item in a menu. You don't seems to use a standard or coherent notation throughout the document. Sometimes it goes like this:

From the File Menu, choose New->Database

or

To create a new, empty website, use the New Website… command that's in the Web menu.

I suggest to adhere to a more strict notation.

For example, "Photoshop in a Nutshell" use the colon notation: File:New:Database

The user Manual of Nisus Writer boldifie each item of the menu and have a notation that go like this: Choose Database in the submenu New of the File menu.

So you could either say;

To create a new, empty website : Web: New Website.

or

To create a new empty website choose Website in the Web menu.

• Dialog

The New Website… command first prompts you for the name of your website. For this tutorial, type the name "tutorial."

I must be picky, but I think you have to be more specific. I think its more a custom to say that a dialog zone will open where you can type the name "tutorial". And you can put a screenshot for this too.

• Special words

I see that there is no specified style for expression that are part of the WSF like the directives, macros... Why not use a simple 

pre
or boldtags to help to distinguish them from the surrounding words. I don't know if it make sense if the document is going to be print, but I'm sure it will help the reading in a browser.

• Where is the index ?

The title say it all. Although you have a very nice table of contents, this THE document where an index is crucial.

• Last words

This will be a very important document for Newbies. I like a lot the way the document is articulated. The Appendix is very nice, with important topics like the glossary and the variable names convention (but missing is the omnipotent f and others I guess).

What I find that is really missing is "maybe" a more short and general presentation of Frontier (if this document is going to be the first one to be read by a newbie) and an index.

Good work Brent and UserLand !

Cheers

-Emmanuel





This page was archived on 6/13/2001; 4:49:04 PM.

© Copyright 1998-2001 UserLand Software, Inc.