Help files - design them for ignorant people.

[jkletrovets]

Re: Help files - design them for ignorant people.

Hi Ira

Thanks for the post. I remember reading some of those posts. Your explanations are always very complete and well written.

The thing I was trying to point out / accomplish with the idea of a wiki is that we could aggregate some of this great information that is already on the board (that folks seem to have trouble finding) into a central repository of information that would be an easy way for all of us to have (in essence) a FAQ for each major category of A5 development that might be on the wiki.

The saying "You don't know what you don't know" comes to mind here. For instance, take the naming conventions topic. A new user to Alpha would have no idea that he/she should try and follow a naming convention. I don't think the Alpha documentation addresses this. But, if a new user were to come to a page that said "Practical Tips for Getting Started in A5" and there was a topic on naming conventions it might be a way to give someone good advice right from the beginning. As I said before, and I think Cal has pointed out. Everyone is ignorant about something. For instance in my case, I will be finishing the main portion of my desktop app soon and then there is a web portion of the app that needs written. As of right now I have no real idea of how to proceed with the web side of things. Some good practical tips would really help me. I am going to take Jerry Brightbill's 2 day course at the Alpha Conference on this but you get the idea. I will be in attendance at your sessions as well.:D


Regards,

Jeff

[CALocklin]

Re: Help files - design them for ignorant people.

... and certainly returning to help file topic tomorrow or next month, your explanations, realizations, corrections, clarifications in the note you sent in the "comment" aren't going to be there. And I am constantly returning to Help topics (poor memory). SOOOOOO...... What I would like to have, frankly, is a Help File system similar to my Microsoft Word Dictionary where I can add (document) things I learn and discover about a particular topic right into my personal copy of the help files, so when I reference it again, I can reference my own work and explanation, too. ...

This was one of the good things about the old fashioned .HLP Help files. Most people didn't know it but there was an option to Edit/Annotate each topic. When a topic was annotated, a small paper clip icon appeared in the upper left corner and clicking that paper clip opened the existing notes.

Now, in case you haven't heard before, there is a free "A5v5" Xbasic Help file on my website that includes a number of A5v6/7/8 commands (even though the web page hasn't been updated to reflect that) and the number of those commands continues to increase as I run into commands that are difficult to find in the official A5 help file or that I feel need additional description. Since it is a .HLP type file, you can add your own notes. Sorry, it is not a tutorial - only a list of xbasic commands - which means it's mostly for those who are writing their own xbasic or in-line xbasic routines and don't have every available command committed to memory.

[dpawley]

Re: Help files - design them for ignorant people.

Cal, Thanks for the free Help file. And yes I knew of the annotate option of the old help files and used it often... and miss that in today version.

[mronck]

Re: Help files - design them for ignorant people.

This is a good thread however it starts two become a two-headed dragon.
Both heads though are equally interesting.

First pitfall is indeed the word ASSUME as Cal pointed out.
I always respond to sentences where this word "assume" pops-up with the frase that "assume" is a combination of words and characters that could also be used with some spaces in it: ASS U ME
Indeed, after that you read that "assume" makes an Ass out of You and Me.
And that's what it is. Don't assume anything at anytime.

Another pitfall is, that creating a helpfile is not a Developers function.
Creating manuals or helpfiles has to do with instructing people, that is a quite a different ballgame then developing an application.
Nevertheless we think it is something for the developer to do.
We would however look strange if the waiter would take our order and walk to the kitchen to also actually prepare it, return to our table and serve it.
Of course, almost everything is possible, and there will be developers who are equally good (or bad....) helpfile editors, but it is my opinion that this would be the famous "lucky shot" more then by definition.

Point is most of us Alpha Five developers are in the SOHO market, where money or other resources are not available to make a proper difference between developing and edditing the helpfiles.
It is something we can live with, but we should be aware of the limits this creates.

This said, of course it doesn't mean we can not optimize the helpfile editing results to the level possible.

Kind regards,

[jmatienza]

Wanted: "Alpha Five for Dummies"

most of us Alpha Five developers are in the SOHO market, where money or other resources are not available to make a proper difference between developing and edditing the helpfiles.

That's a good point, Marcel. But developers aside, Alpha Software itself is not just in the SOHO market. It literally wants to be all things to all people. Its market includes, not just enterprises, SOHO's, and professional developers, but people attempting their first database solution. Its for this last group that we need friendlier documentation, an "Alpha Five for Dummies" if you will.

Sure, I've learned and continue to learn a lot from the current documentation. But I for one wish it was written in a more linear fashion.

[Paul H]

Re: Help files - design them for ignorant people.

This is a great thread which addresses issues many of have.

From my point of view as a seasoned A4 user for many years but a total A5 newbie trying to change direction, the help file is really very useful (by far the best of any software I have ever used) but I feel it would benefit from one extra feature - a "Why?" field.

In other words, it's great to read what a function does and how to use correct syntax etc., and the example(s) given do show how to use the function in real life. That's very good, but newbies need to know WHY they would want to use that function in the first place. And if the "Why" field was searchable, wow that would be soooo helpful. I have often trawled through functions in order to better my knowledge (yes, I need to get out more...), and found a golden nugget I could use somewhere but didn't know it existed.
(I can't be the only one who has the help file as night time reading, can I?)

I know the help file has an excellent "How To..." section, but it's not the same as seeing *why* each listed function should be used. I know this mammoth task will not be carried out due to the immense time it would require, but maybe Mr Wayne would consider going some way towards this in his next book? ;)

Just my two UK pennies worth, whilst I still have some money in my pocket. It'll all be gone when the govt has finished spending �9,300,000,000 (yes!) on the Olympics...

Paul

[jbooth]

Re: Help files - design them for ignorant people.

Cal, your posting has clearly pushed quite a few buttons! This thread has been very valuable, and raises central issues of a very important topic.

One of the central areas of good SW development (read: SW tools and their end products) lies in the effective consideration of the user�s mental model of the application. Someone in this thread mentioned the issue of one being �visual� when it came to understanding things. This is a good point, and shows that that person is onto his learning style. (As a note: learning styles is a big area in education! Cf. the following site if you want to check out what learning style you prefer: http://www.engr.ncsu.edu/learningstyles/ilsweb.html)

With a product such as Alpha, being able to do powerful and complicated number crunching is important. I mean, the whole game is focused on relational database operations. However, developers (Alpha ones, as well as persons using Alpha to develop applications) should know that if the user of a program can�t understand how the GUI (and, of course, overall system) works, and cannot develop a so-called mental model of what it is that the application does, conflicts and dissatisfaction on both sides (here: developer, user) are inevitable.

The importance of the user�s mental model of a system cannot be overemphasized. It is just as important as the functionality built into the application. And the implications for the market impact of a product are just as meaningful. Just one example: the Internet wasn�t really popular with the general public�even when general-public gateways to the system opened up in the beginning of the 90�s. The problem was that the Internet was not really user friendly. The general public just didn�t have a handle on the concept.

Most of us having experience with the Internet in those days remember the command-line input that was needed to get things done. (In fact, some may remember the old days of green monitors�I�ve worked with �orange� ones, too!--where word processing, such as underlining, was a real hassle (remember how some programs required /u+/ and /u-/ for formatting of underlining? And remember what you said when you found out that you had 555-paged Z-fold printouts�all underlined because you forgot to use the close command for the underlining!)

It has been suggested by many that what caused the phenonomenal growth of the Internet was the introduction of the graphical browser, such as Netscape Navigator. From the moment graphical interfaces were introduced, and the desk-top metaphor was used in conjunction with the personal computer, Internet use skyrocketed.

What I�m trying to say here is that users were finally able to get a mental model of the Internet as an application because the system met their need to develop an idea of (or mental model of) the application (the application here, being the Internet per se, and the browser being used as a portal, so to speak, to the Internet.)

Same thing with documentation for Alpha (and, of course any software product�whether for SW development or application development): to be optimal, it must allow for a better user mental model approach. To do this requires, however, an understanding of various user audiences.

To keep things as short as possible here, suffice it to say that one has here a combination of various users who need documentation to enable their development of a mental model of the product. For example, there are novice vs. expert users of database applications. The beginner has different information needs than the experienced user. Then, there are novice vs. expert users of Alpha�the old hands (read: versions 4+) have grown with the product. Newbies purchasing version 8 may feel they have tackled a beast. Nest just those two types of populations into a model (database experience and Alpha experience), and you can see the bandwidth of difficulties experienced by the various users, and the difficulty in developing a documentation system meeting the needs of all these audiences.

I think it was Pete Schuder who mentioned the issue of one�s having a liberal arts background�rather than an IT one�and how this can impact on a person�s understanding and use of SW documentation. That makes sense to me. And it�s an important aspect of where the user is coming from (in that instance), and in its way, reflects on the validity of the concept that there are different user models respective to an understanding of documentation about a product.

I�ve been thinking of what it would take to make Alpha documentation more user friendly. I believe a focus on various user audiences would be a good first step. The documentation isn�t, in this respect, user friendly at the moment. For example, beginning users can lose sight of the forest for all the trees. As an example, I believe Alpha Sports is a wrong first step in learning the system. It�s a good demo of what Alpha is capable of doing, but it�s like throwing an Avtomat Kalashnikov AK-47 on the table, when the customer has only had experience with sling shots.

Maybe what one needs, as an example, would be a type of �Hello World� application�where one builds gradually upon that simple concept. I.e., learning by doing, and in digestible steps. I have some ideas on this, and I�d be willing to work out a concept with anybody or any group interested in such. (And I don�t think any person can do this alone.)

To be clear: I�m not criticizing the product per se. However, improved documentation could be a force multiplier in product placement and user/developer satisfaction with the product. I have enough experience in working with software system quality control (respective to GUI design) to know that very often, documentation is a vital part of initial purchase decisions and�in the long term, customer satisfaction with the product.

I believe the various postings of this thread have shown a common story: there is a wealth of information available in the current help documentation of Alpha. There needs to be some way, however, of taming its unwieldy nature (read: amount, and structure), and allowing a tapping of its potential, and getting it to be more user-audience focused.

-- John

[Peter.Greulich]

Re: Help files - design them for ignorant people.

Not to disagree w. anyone in this thread (all things being equal, I don't), but given that Alpha's help file is at least as good as pretty much any other software out there, I don't think this is necessarily a help file issue. What other major software has, and Alpha does not, are third party books that address the issues raised here (PKW being the one stellar exception). What we need is Alpha Five for Dummies (for beginners) and other "how to" books that walk users and developers through the development process. I think the ideas here are good, but go beyond the normal help files provided by a software vendor.

[smrogers]

Re: Help files - design them for ignorant people.

Peter,

You said what I said just about a year ago when I was just starting out with Alpha -- I was told by several how terrific the help files are (and they are) compared to industry standards, but my complaint/comment still stood unanswered: Why aren't there more third party books available (like there are for FileMaker)? I think manuals need to fall into one of three categories (and usually for software I use regularly I buy one of each): What it can do, How you can do it, and The Reference (I'm simplifying but you obviously get the idea). Does Alpha agressively look for other's to do this kind of doccumentation? I see it as another form of advertising the product as well...

Anyway, my 2 cents...

[jmatienza]

Re: Help files - design them for ignorant people.

Alpha Five is powerful enough to develop industrial strength applications. But it also aims to be easy enough for the person who is attempting to make a database for the first time. You have to admit that is quite an ambitious range. But given the success stories that I've heard around here, I believe it's a realistic one. And that's the reason I refuse to give up on Alpha Five.

Given the dearth of both in-house and third party books for the dummy (yes, Viriginia, there is such a thing as a Dummy), I think Alpha Software itself should do something about it, for their own sake. Better instructions = more happy users. As JBooth suggests, it might do wonders for Alpha's market reach.

Other than that, having a wiki manual might be an even better idea. It might take a dummy (or a former dummy) to write for a dummy. All Alpha needs to do is provide the infrastructure. From what I've seen on this message board, there are lots of qualified contributors and editors to volunteer.

[Peter.Greulich]

Re: Help files - design them for ignorant people.

The other exception I forgot to mention is Susan Bush. She has written several very nice books for beginners and perhaps intermediate users.

[smrogers]

Re: Help files - design them for ignorant people.

I have all of Susan's books, as well as all of the Pace manuals AND as many Dr. Peter Wayne's books as I could find... but I challenege you to find something at a place like Barnes & Noble... There's a great book store (used to be in Burlington MA now it's in Waltham, I think) called Softpro, and you can usually find the most obscure books on any computer subject there... but they don't have anything on Alpha... Maybe with V8 something will happen...

Hey Alpha, just thought of an add for you (although this goes against the whole grain of this documentation thread!) --

Show some cartoony guy purchasing "Access" or "FileMaker", sitting down with one or two manuals, next frame more, next frame all you can see is a tuft of hair sticking out above the piles of books in front of him, then again at a bookstore contemplating which book NEXT to buy, when he glances at the cover of a really thin book called "All you need to know about Alpha V8", and he wacks himself in the head and says, "I could have had a V8!"

(Corny enough for you? Hey - I'm not in advertising but I could see it!) :p

[braveulysses]

Re: Help files - design them for ignorant people.

Oh thank heavens...
Cal, I'm glad you're lost too. And all you other gurus as well. I thought I was the only n00b Loser in the patch. (c:

Trouble is, I can't even figure out where to put basic scripting for this assemblage of code I'm using, let alone how to actually write it, so mebbe I am an nL after all...

Rob.