How about a release?

[jkwrpc]

Re: How about a release?

I am breaking my own rule, I said I was done commenting but I after reading the thread since my last post a couple of thoughts have come to mind.

- I purchased A5 for a purpose and I hope it meets that goal. I am simply suggesting something that is drilled into every person who writes code, documentation is important.

- I generally know what I want software to do. If we are working in .Net I have a vast deep pool of resources. I for one think the MS model for VS help is pretty good. If I am working in the form class I can find form event, properties and methods pretty quickly. I can find the namespace and sample syntax. It even tells me which versions of framework its applicable.

Now I dont find that same experience when I go into A5 help. As I said earlier those who have invested into A5 (again I am such a person) are dependent on Alpha as the sole source of documentation. When I go to that documentation, even though it literally thousands of pages, it has been tough sledding to find what I need. You can lay the fault of the hard to use documentation at my feet if you want, but there have been enough comments that I hope the documentation gets attention in future releases.

Whether Alpha will see it as a priority I dont know. Until I will carry on learning A5 using the resource I have available.

[Steve Wood]

Re: How about a release?

I think it is obvious from this thread that Alpha is not going to rewrite the documentation, other than perhaps this Wiki idea. Otherwise Richard would have said "I see that documentation is important to all of you Developers, and you don't find the existing documentation or 3rd party sources to be adequate, so we commit to improving the documentation." or something like that.

And to let Alpha off of the hook, I don't think they could write a proper document all by themselves, it takes us Developers to provide the practical experience. I think that is the idea behind the Wiki, to include Developer experience. I happen to think the Wiki is not going to be very useful because they copied in all the stuff we don't like from the legacy documentation and because 'our' input will be uncoordinated, but we will see. Personally I think what Alpha should do is JUST concentrate on properly updating the reference part of the Help document, the part that deals with Functions, Expressions, and so on. We should collectively write the "practical guide". Alpha cannot do that, its not their area of expertise.

Here is an example of why the existing documentation is so hard to use. Look up Dialog Component in the Index, select "Checkbox" because you want to know how to implement a checkbox, perhaps how to use it on the AfterValidate page to extract its value.... Here is the page you get:

http://support.alphasoftware.com/alp...Properties.htm

There is nothing of any programming value on that entire page. That particular page, and many many pages like it, are utterly useless in practical terms.

Another example, again in an AfterValidate event, sometimes you need the phrase ".value" at the end of an expression, like this:

tbl.name = currentform.controls.name.value

and sometimes you don't. We've all had to figure that out on our own, there is nothing in the help about it.

OR IF THERE IS, one cannot find the needle in the haystack.

I have suggested several times that the major problem with the existing help is that it is bloated. Copying it to the new Wiki gives you two bloated Help resources.

It's like my messy garage, (since Richard used a Supermarket example), if it is a little messy, I can clean it. But if it goes too far, I don't know what is important, what is crap; its all mixed together. So the only way to resolve it is to... actually I don't know the answer because my garage is still a mess (but you get my point).

The Help is so big and so long forgotten that it is impossible both to use (by us) and for Alpha to update properly.

Additional ideas:

- break out the entire xDialog help to a separate document. 1 out of 10 Alpha users will ever get in to xDialog.
- Remove or break out all of the references to AlphaSportsWeb 'explained'. The examples are so very old they do not convey modern programming technique.
- Break out xbasic to a seperate document. That is the most important part and it needs to be easy to reference, better indexed.
- recompile the whole thing in some modern Help system so I can easily flag pages as important. This because I heavily use 5% of the content, and never use about 70% of the document.

[drgarytraub]

Re: How about a release?

Hi everyone,

Despite the fact that these are very accurate comments (the help file is HUGE, and that in and of itself, makes it VERY difficult), I personally have used it very frequently. Sure, it could be written better, but between the help and the message board, I personally have found everything (almost) I need.

To me, the missing "documentation" are the third party books, "cliff notes", "...for dummies", written by veteran users of other products.

I think the challenge really is for US as developers to create such thirty party books (for profit of course). Let alpha spend it's resources on creating the AWESOME software that it has. (We all agree it's awesome; that's why we spend so much time on this board, and still use the software.)

[forskare]

Re: How about a release?

I wonder if the reason for the bloated HELP is because the same Help is used for all versions, when the Help should be separate for each version.

I think it's a bit early to pass judgment on what Alpha will do with Help but it's obvious, it MUST be improved.

Does Alpha follow-up purchases with a questionaire? If not, perhaps they should. It sure would provide them with ideas about where the ball is being dropped.

kenn

[mmaisterrena]

Re: How about a release?

Im confident that the Wiki Will Work. Why? Because of alphas community.

Some of the people here that are being so critical about the wiki (not that being critical is a bad thing) are going to be the first contributing to this knowledge base.

But there's a hidden demon in it. Alpha could just let documentation to its community as they sort of done by letting most of the support to this discussion board.

Is this a bad or good thing? well.. that's a hole new discussion, but the Wiki Will Work.

[Richard Rabins]

Re: How about a release?

Can you recommend a program other then Alpha Five that a beginner could take to market faster? I haven't found one.



Very good point. Not knowing how to create a web application in Alpha Five where customers can log in online and only see their records (i.e: by customer id), and assign users who in turn only see their records, has stopped me from going any further with a web application.

Are you aware of the training courses on building web apps that Alpha Five has been offering that were created by Steve Working?

for more info please email me at [email protected]

(there is a video course on building web apps from scratch and a video course on building desktop apps from scratch. Each course is about 4 hours and is broken into chapters and lessons within each chapter)

This course will be updated for v10

[martinwcole]

Re: How about a release?

I think a question that needs asking is this - does Alpha agree that the help files are out of date, etc.

Richard, have your PR guys create a simple poll - announce it and make it available from both the board and in your mass emailings. Wait maybe 30 days, and then post the results.

In my humble opinon, it is not realistic that people can post to a 'wiki' descriptions for the use of functions, etc., that they don't know exist, and for which there is no documentation.

[RossAllen]

Re: How about a release?

Are you aware of the training courses on building web apps that Alpha Five has been offering that were created by Steve Working?

Thank You!! Found it here: section_09/06_filter_arguments

What a relief.

[forskare]

Re: How about a release?

[QUOTE=mmaisterrena;507695]Im confident that the Wiki Will Work. Why? Because of alphas community.

But there's a hidden demon in it. Alpha could just let documentation to its community as they sort of done by letting most of the support to this discussion board. QUOTE]


On the 1st page of this thread, Richard said, The way this will work is that if any member of the Alpha Community wants to post content to the Wiki - they can, after it has gone through an edit/approval step.

kenn

[mmaisterrena]

Re: How about a release?

Yes I read that part but either way the source of the material in that case would be an Alpha 5 User not Alpha Software (and that's the spirit of wikis).

[Richard Rabins]

Re: How about a release?

I just wanted to comment on a remark Steve Wood Made

I think it is obvious from this thread that Alpha is not going to rewrite the documentation, other than perhaps this Wiki idea. Otherwise Richard would have said "I see that documentation is important to all of you Developers, and you don't find the existing documentation or 3rd party sources to be adequate, so we commit to improving the documentation." or something like that.

And to let Alpha off of the hook, I don't think they could write a proper document all by themselves, it takes us Developers to provide the practical experience. I think that is the idea behind the Wiki, to include Developer experience.

I think the opposite is in fact true. We are in fact VERY interested in responding to customer requests in terms of documentation/training. Think about it, we have spent millions of dollars building Alpha Five v10, why would we want to ignore or fail to understand the importance of documentation and training?

I do also agree with Steve that part of the "body" of documentation should also include the real world experience of people using Alpha Five to build applications.

We have about 600,000 email and physical addresses of customers, and are very interested in partnering with people who have created educational materials around the use of Alpha Five. Please contact me at [email protected]

[martinwcole]

Re: How about a release?

well, hopefully, all our griping will be an inspration to improve the documentation.

[Steve Wood]

Re: How about a release?

What are people's Top 10 "How to.." questions? Good questions for a practical reference book on programming with Alpha. Or is some other kind of reference of more interest?

[trackmanpete]

Re: How about a release?

Richard answered at 11:41 pm on a SUNDAY night. Hope should not be the operative word, don't you think. They are moving so quickly with all the new things Alpha can do, there just hasn't been the manpower available, from what I could see, to also do the documentation on a timely basis. Not that my observations mean much, but I was extremely impressed with the drive and determination of the main core of Alpha personnel at the gathering a few weeks ago. For a small company that sells a product for far less than any custom product any of the developers are creating with Alpha, I really think patience is needed for this group to first get the new version out to the marketplace and then spend the time catching up with the documentation. Besides, as we know engineers aren't always the best authors...:), but boy can these people write code.

[MikeC]

Re: How about a release?

Some of the people here that are being so critical about the wiki (not that being critical is a bad thing) are going to be the first contributing to this knowledge base.

I do not know about other contributors to the messageboard but I, for one, could not possibly find the time to monitor and give to another such forum...I currently am an active member here, the new IADN forum, and a Quickbooks forum that I monitor whenever possible (and have not of late due to time constraints!). But if the other members here have that amount of "extra" time then I agree that the Wiki most likely will succeed and become a new way to search for Alpha solutions.

:) This thread really has gotten a bit off topic I see...guess that's alright so long as the originator doesn't mind......??


LATER EDIT: Quite a few posts since I wrote this I see now!! I do have to agree that Alpha does respond to us when, in fact, they could be like many other companies that just watch and then give a formal, generalized, and often dictated report to its users....something that I do always try to keep in my mind when being critical of Alpha.