Help files - design them for ignorant people.

[jmatienza]

Re: Help files - design them for ignorant people.

Cal,

You've hit the nail on the head with your Tarzan illustration.

That's a bit like dragging Tarzan out of the jungle for the first time and telling him to start the car by putting the key in the ignition and turning it. He might start with "what's a car?" followed by "what's a key?" then "where is the key?" then "what is an 'ignition'?" then "where is the ignition?" and maybe "which end of the key goes in first?"

Well, the Alpha Five Version 8 web site now contains this long-overdue statement:

So.... what is Alpha Five? Alpha Five is software for building desktop and web database applications - applications that include report writing, intelligent email, web connectivity, backend database access, data browsers and security.

At least Tarzan knows what a car is now!

If only the documentation reads as easily as a car manual! The WAS Tutorial in particular makes my head spin. I mean, at what point do I create the tables?

[Peter.Greulich]

Re: Help files - design them for ignorant people.

If only the documentation reads as easily as a car manual! The WAS Tutorial in particular makes my head spin. I mean, at what point do I create the tables?

Don't you know: tables are for babies* (only kidding!) The WAS tutorial is rough, I agree. You can ferret out info there, but as Cal says, it assumes you already understand what's going on. Hopefully, it will be overhauled at some point.


*Which reminds me of a fuuny story. I used to have an employee who complained about some functionality that Alpha didn't have (actually it was the ad-hoc browse, which didn't yet exist at that time). She said, "even Access can do that, and that's a database for babies!" So take that Mr. Bill - Access is for babies! :)

[jkletrovets]

Re: Help files - design them for ignorant people.

I used to have an employee who complained

Peter, this struck me as funny since she is now a FORMER employee. Us folk from the Alpha nation don't take lightly to criticizing our database tool! :):)

[Peter.Greulich]

Re: Help files - design them for ignorant people.

She left on her own volition, Jeff. No pressure from me. I have 7 witnesses - but any further questions on this matter and I'll have to refer you to our legal department.

But it cracked me up that she thought Access is for babies!

[jkletrovets]

Re: Help files - design them for ignorant people.

As an offshoot of Cal�s point here to start the thread. (Maybe I should have started a new thread but it seems appropriate to post it here). What are the thoughts about creating a sort of wikipedia just for Alpha. I have been thinking about this for a few weeks. It would be neat to create it using the WAS. Obviously the wiki metaphor allows for community involvement and tweaking of the data. As powerful as Alpha is it would have the potential to get VERY large which might diminish it�s usability but it could also be a huge tool. I was thinking about having main categories that would have 20-30 topics for each Alpha category.

Below is a VERY abbreviated list of some examples of categories and topics could be:

1. Proper database design in Alpha
A. Naming conventions � why you need them
B. Proper database design when using Alpha � i.e. 10 character limit in field names.etc
C. Layman�s description of designing for LQO (Lightning Query Optimization)

2. Networking Alpha Databases
A. Tips/Tricks for setting up shadow tables
B. Terminal Server and Alpha
C. Maintaining networked databases
D. Do you need to program your own auto-increment function or will the built in functionality work in a networked environment

3. Distributing Your Application
A. Tips/Tricks on how to use Astrum (or other third party installers). Cal posted a great piece of code on this recently.
B. Tips on making registry entries

4. Xbasic tips
A. When to use VAR-> (Selwyn had a recent post on this that was great)
B. Where / Why to use functions

5.Tips/Tricks for the First Time Web Developer

6. Tips/Tricks on setting up and configuring Web Application Server



Obviously these are just some of the categories we could have. It seems to me that given the vastness of the Alpha documentation and the ongoing discussion about being able to find things that a utility like this could prove really useful. If there were 20 or so topics in each category folks would have a starting point to look for their answers. If the wiki didn�t have it then a search of the message board or help files could then be used.

I have dozens of threads printed to PDF for various topics I thought were either a great resource to me now or will be in the future. In thinking about it, if the WAS was used to set this up we could have a url field and the supporting document (either the page in the help file or the thread on the message board could be referenced) so the user could go right to the source information.

A lot of the same questions get answered on the message board and it seems with this wiki idea we could all have a starting point for different areas. For example the thread that Cal started was in reference to using the AlphaDAO. If there was a section on the wiki about setting up and using AlphaDAO Cal probably could have found the info he needed much quicker with practical knowledge from those who had used it.

Well, I hope I explained my concept adequately.

Thoughts?

Regards,

Jeff

[jmatienza]

Re: Help files - design them for ignorant people.

Peter,

I'm a baby. I admit it.:D

I must have flipped (in a manner of speaking) back and forth through the Web Publishing Tutorial about half a dozen times before it finally dawned on me: "The person who wrote this tutorial thinks I already have my tables!"

Isn't a tutorial supposed to guide the user in creating an application from start to finish? Aren't the tables at the start of the application?

Apparently, the Web Publishing Tutorial is intended as a branch-off from the Getting Started with Alpha Five tutorial, which does deal with table creation. But there's no notice to the reader that he must have finished the other tutorial first, or that he must otherwise have his tables ready in order to be able to follow the web tutorial. Putting such a notice on the first page of the Web Publishing Tutorial would be a simple but indispensable help, nay, a courtesy, to future readers.

[jmatienza]

Re: Help files - design them for ignorant people.

Jeff,

I think a wiki manual for Alpha Five is a great idea. I might be able to help "baby-proof" the documentation. ;)

[xkronix]

Re: Help files - design them for ignorant people.

I think the Pace training manuals are good in this respect. They seem to (i ihave only read one so far, the next is on it's way) provide a good tutorial that follows throughout the book, from table creation onwards. It takes you through it at an easier pace.

The first book didn't teach me much but it was worth getting because it helped clear up alot of points that the help files confused me on.

I think a wiki manual for Alpha Five is a great idea. I might be able to help "baby-proof" the documentation

what a brill idea! :)

[davej]

Re: Help files - design them for ignorant people.

This is an interesting thread and it makes some very goods points, first of which is that no one knows everything and even if two or more people are knowledgeable about a specific issue, they very well might understand it from differing points of view.

Something as simple as the definition of the term 'database' has changed from the days of A4 (the good old DOS days) to the A5 world (our loving friend Windows). Transitioning from DOS to Windows causes (forces?) a computer user to have to relearn and redefine all kinds of terms. Just think about directories/subdirectories and folders/subfolders.

I knew a developer back in the dBase days who, if a client asked for written documentation, would double his project cost because he know the time and work involved in writing the documentation so t hat it was understand by the majority of users.

Back in my college teaching days, I always had to remain sensitive to the wide differences in knowledge and experience students brought into my classroom. The hardest trick is to express what you are saying so that you do not loose someone. Making a statement that can be equally understood by a room of twenty-five students is difficult enough. Now let's extend that to the 'world' of Alpha users and hopefully you can appreciate the almost impossible task facing anyone writing (or attempting to write) documentation. It is difficult attempting this for users of the application you wrote; now think about the virtually impossible task of doing this for new users who have never used any database development tool, users coming to Alpha from something else, users/developers with some number of years experience and finally end-users who honestly think of themselves as programmers because they have been 'programming' (their term) patient records into the computer at Hospital X.

I haven't even mentioned those users who, for whatever reason, do not / will not read the provided documentation.

Anyone who writes documentation at any level is to be commended and should be given a lifetime supply of aspirin and frustration-avoidance pills.

Dave

[jkletrovets]

Re: Help files - design them for ignorant people.

Dave

I agree with everything you said. Your point was well written and conveyed quite eloquently.

That's one reason I thought a user maintained "Getting Started" guide might help all of us. It is important to note that "Getting Started" does not have to mean simple things. For example, I think it is widely known that Cal is one of the more knowledgeable folks on the board yet even he could have used some help in learning AlphaDAO. Plus, with having the "different viewpoints" the data presented for each topic has the chance to be more dynamic (and maybe more complete) than perhaps the help file for those categories in the wiki.

Regards,

Jeff

[davej]

Re: Help files - design them for ignorant people.

Jeff,

Thanks for you kind words.

I think we would have great difficulty even agreeing on the basic terms to be included in the documentation, forget about the definition of those terms! We probably couldn't even reach consensus on the definition of the term 'basic terms'.

Dave

[B Philip Gerber]

Re: Help files - design them for ignorant people.

Cal,
I used to work for a mainframe software company and my manager who was a salesman used to say. The only thing developers want to do is something technically challenging or user confusing. If you think about this, that is probably why the help files are not too helpful. Unless you know what you want to find, then why look in help files for it, If you know what you want.

Have fun.
Philip

[Mike Wilson]

Re: Help files - design them for ignorant people.

Cal,
I used to work for a mainframe software company and my manager who was a salesman used to say. The only thing developers want to do is something technically challenging or user confusing. If you think about this, that is probably why the help files are not too helpful. Unless you know what you want to find, then why look in help files for it, If you know what you want.

Great thread, so I have to participate.

Philip,
My first thought is 'the dictionary'. It's the standard place we are sent to learn to spell the word, but you have to know how to spell it to find it. Same dilemma (2- M's, I looked in the dictionary). But it has worked for centuries and I'm thinking the same 'philosophy and rational' applies.

My second thought is that the Help files are not fabulous, and sometimes I want to fix them and add things to them after the time I take working through the learning curve on a particular subject, function, strategy. And gotten direction/clarification from good folks on the Board. The 'comment' at the bottom of each page is there for that very purpose. But your suggestions are 'considered', 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. Maybe add personal keywords so the Search can find things you spent hours finding before. Right now I keep an A5 database that references many topics pulled from this board, but if I could integrate with the Help Files... that would be good.

[Esio Trot]

Re: Help files - design them for ignorant people.

As an offshoot of Cal�s point here to start the thread.
1. Proper database design in Alpha
A. Naming conventions � why you need them
B. Proper database design when using Alpha � i.e. 10 character limit in field names.etc
C. Layman�s description of designing for LQO (Lightning Query Optimization)

<snip>

Fantastic Idea!!!

I could and still do need this sort of knowledge as my early attempts with projects are now hampered by wrong, and, yes, ignorant decisions. I suspect many users of A5 are drawn to it as it does reduce significantly key areas of heartache - it is possible to get a basic workable relational database up and running - especially if it can be based on examples provided.

Maybe in the past I should have bought something like "databases for dummies" - but then I don't know if this type of book has this strategic planning as an essential part.

[csda1]

Re: Help files - design them for ignorant people.

Jeff et al,

C. Layman�s description of designing for LQO (Lightning Query Optimization)

Some threads that I have commented on and described LQO

Thread 1
Thread 2
Thread 3


Of course, your LQO mileage may vary!:D