Suggestions

Explore ideas for improving the docs here

Moderators: FourthWorld, heatherlaine, Klaus, kevinmiller, robinmiller

Post Reply
Ontarget
Posts: 3
Joined: Sat Jun 22, 2013 7:52 pm

Suggestions

Post by Ontarget » Mon May 12, 2014 4:04 pm

Although I've only been using LiveCode for about a year, I have found that the documentation has some major issues:

The following comments are not meet to be critical of LiveCode but are constructive suggestions. At the risk of sounding like I am trying to beat my own drum, I what to explain that I have roots as far back as the beginning of computing. I have been an active member of several development teams building application that cost over 1 million $USD to produce. I was also the Logistics Manager for a large team of developers of very advanced technical curriculum. That being said, I am going to try to explain my experience with learning LiveCode and the issues I have noted about the developer documentation.

1. The issues with LiveCode as a new user:
The site map on the RunRev site is not useful in that it is incomplete. When you are a new user of LC the site map is critical for locating the knowledge elements required to master LiveCode. On this point LC needs to review the site map to determine if they have all of the knowledge objectives organized in a logical and useful manner.
There are many valuable items on the RunRev site, and then many that are not on the site. The approach to the organization of learning materials is absent on the site.
There many external LC related learning materials either published by developers or companies that are not working in conjunction with LiveCode management. One of the best is Scott McDonald's SuperSite where he attempted to organize the learning materials in one web site. (Well Done Scott).
2. Where does a new user begin?
LiveCode is the Swiss Army Knife of IDE's where the new user can set off in any direction desired to design just about any kind of software product.
My experience is that the documentation (dictionary and support site) does not have an adequate index of capabilities that can be used to accomplish defined tasks. For example; THE ONLINE HELP most software products include a subject / keyword searchable help system. LiveCode has a dictionary that attempts to have developers add their scripting at the bottom of the dictionary screen. This should be obvious that it is not being used. The narrative that is in the dictionary is incomplete in that it really lacks in content where the new user can determine how to use the keyword, or script snippet to accomplish the needed task. There are limited reference materials to support the keyword usage. Note: the RunRev support provides a small number of examples of which many are out of date, or do not work with the current scripting language. *** This is one of my real objections about the documentation approach (most software products provide the necessary documentation to use the product) they don't charge high prices for basic training or classes and leave voids in the documentation where the developer must pay to learn.
3. Where do new users find help?
It is the same for all new users, they browse the LiveCode site looking for a starting point, they read the examples, and try to use the lessons provided. They look at the examples and resource stacks. They want to understand what is possible to do with LiveCode? Then the realization begins to arrive that the examples and lessons, sample stacks and resources are so general that there is no ability to determine the possibilities that may be available in LiveCode.
Getting Technical:
Any product that has a technical knowledge factor related to learning objectives requires excellent documentation to able to survive in the market. If the documentation fails to deliver the technical media to use the product, it will fail as a product.
Can you say that LiveCode provides organized learning objectives?
Would you say that the support is task oriented, or user self supported? User self supported where the user needs to glean information from the available documentation and seek it from the forum or the How to email site. Can you say that you can find a structured learning path that lists documents and sources of learning materials? Of the current learning materials like the User Guide for LiveCode do you feel that it is a adequate learning tool? Do you have a detail training index of materials to research that will provide the basic knowledge required to learn LiveCode.
4. Unscrambling the code:
LiveCode being a Swiss Army Knife has many devices available for the user to use.
In the past year I have spent 3 hours or more for every 1 hour of coding. Why would it take so much time to learn LiveCode? Well it is because the documentation is all over the place! There is no guide for the documentation. If I were to do a "Instructional Design Analysis" I would need to determine the candidate audience knowledge requirements, then use the analysis to define the learning objectives. The analysis would need to gather all of the current knowledge of the subject to be successful doing the instruction. Because there are wholes in the body of knowledge there are wholes in the available documentation. When the user needs to search through the available knowledge base to get answers, then the documentation does not provide those topics, or answers the user frustration will impede the ability to produce meaningful results.
5. Meaningful results:
If the documentation is not available to allow a new user to learn LiveCode then that user will move on to another product!
If you want the documentation to improve, then a full instructional technical analysis needs to be done.
The existing body of knowledge needs to be defined.
The learning objectives need to be defined based on the student learning entry level.
The documentation can be divided into entry levels where beginner, Intermediate, and advanced users can locate their training tracks.
A clearly defines set of learning objectives needs to be formulated.
The learning materials need to be evaluated for the desired learning outcome. If they are not up to the quality required they need to be updated.
Testing is required of the learning materials by users to identify any issues with learning the defined task objectives.

I am writing this reply for the documentation team that was discussed on the How to site because it is critical to understand what is at stake. I have been so frustrated with the documentation that I have repeatedly wanted to move on to a different IDE or just go back to my world of doing database apps.

jacque
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 7210
Joined: Sat Apr 08, 2006 8:31 pm
Location: Minneapolis MN
Contact:

Re: Suggestions

Post by jacque » Mon May 12, 2014 10:25 pm

Thanks for writing this up, it's excellent and I agree with all of it. You seem uniquely qualified to assess the problem, and your suggestions should be taken seriously. They're good ones. Of course, the next problem is who is available to actually write all this stuff. Writing documentation is a specialty skill, and I suspect that those who are qualified may not have the time. But it's a good start to have this laid out as a reference.
Jacqueline Landman Gay | jacque at hyperactivesw dot com
HyperActive Software | http://www.hyperactivesw.com

Post Reply

Return to “Brainstorms”