Suggested improvement to Help & Documentaion

Discussion of MicroSurvey CAD related issues and questions.

Moderators: Brian Sloman, Jason Poitras, James Johnston

Post Reply
Alex Leonard
Posts: 42
Joined: Sat May 13, 2006 7:47 pm
Location: Kona, Hawaii

Suggested improvement to Help & Documentaion

Post by Alex Leonard » Sat Jun 10, 2006 2:26 pm

This message is prompted by Cathy's last post and reflects my experience as 2-month-new user of both MS-Cad2005 and Field Genius2006.
My qualifications for making the comments below: I am not new to 3D-CAD, and I have nearly 30 years experience with computers as both developer and end-user.
I have very recently made a career change into the world of surveying, and overall I am very happy with my choice to buy and use the MS products. But this post is about how to document a complex computer application - its got nothing to do with surveying or surveying applications per se.

My oservation is this: MS-CAD/IntelliCad is essentially command-line driven. All menu selections, tool-bars, wizards and so forth are proxies for the underlying command line. To really use the program effectively you have to at least know (very well) the command line. This is fine. Except that the MSCad Help files are insufficient to get you there.

Like Cathy (the last poster to this bulletin borad), I too spent DAYS struggling to get rid of those pesky point numbers so I could see what I was doing on-screen (sure they are also really useful in some situations) - did I know that they are IPN's? No. How would I do a help search to find the IPN toolbar button unless I knew that that is what they are called (searching "point number" doesn't work - try it). It took a call to the (very helpful and good-natured) support team to answer this simplest of questions. But those calls should be reserved for the tough questions and bug-reports - not the little stuff.

Yes, the movies are GREAT! Without them I'd still be struggling. But they only get you started. There are so many functions, variables and proceedures to learn and know that they could not effectively be transmitted by the movies. Nor the classroom either. There simply is no substitute for COMPREHENSIVE and well organized documentation.

Obvously the printed manual is merely a "Getting Started" introduction - and one that is not as effective as the movies.

The MSCad help files are cluttered and confusing.
As an example do a helpfile "Search" for "LTSCALE" - the entry the user needs is 13th on the list and is not identified by the command-name. This is OK if you are experienced and know what you are looking for, but then that's not really who the help files are created for... Step back now and ask the question - how would a new user know to search for LTSCALE? Just try to find the relevant information without using the command-name itself.

The fact of "layering" the MS-Help topics on top of the "IntelliCAD" help files (as opposed to "integrating") is part of the problem - multiple similar (but not necessarily identical) entries. The fact that the Developer reference is mixed in with all of that only makes it more cluttered - and hence less useful.

What I belive is needed is:
1. alphabetical listings of all MSCad Commands, Functions, Aliases and Variables - much like the existing IntelliCad Command Reference and Variable Reference.

2. Unification of both the ICad and MSCad sets of references into one searchable list that could be filtered for commands vs. variables, or ICad vs MSCad.

3. an index or summary page for the listing - again, much like the current IntelliCad Command Reference index page (but not like the existing ICad Variable index which lacks summary descriptions). The index would identify each entry as either IntelliCad or MSCad and give a brief description and a hot-link to the full description of the command or variable. The brief description is important: the user hould be able to scan the full list to find what they are looking for, but will also be exposed to other commands that they may not know about (for "future reference").

4. A pdf file (printable) of the complete unified command and variable reference.

5. The existing help files should have duplicate entries removed - keep either the ICad description or the MSCad description for a command but not both. The help files could then be divided into two main sub-sections: HOW-TO and Command Reference. In many cases, new users don't know whether what they want to do is ICad or MSCad related, so the HOW-TO's should be unified in the same way as the Command and Variable References.

6. The developer reference should be in its own section, and the help file search command should allow the option to including/excluding those entries from the results.

I hope Microsurvey take this post in the spirit in which it is intended - a positive suggestion to improve a good product and make it more accessible to new and migrating users.

Thanks for taking the time to read this overly long posting...

Glen Cameron
Posts: 1395
Joined: Fri Nov 08, 2002 12:18 pm
Location: Corbeil, Ontario, Canada

Post by Glen Cameron » Mon Jun 12, 2006 5:31 am

You do have some very good points and they will be looked at in the future.

Documentation is always the very last thing done for any program that is written and typically it is put together as quickly as possible so as to not delay the release of the product. We try to put all relevant information into the documentation but unfortunately it is not structured as you have suggested.

Part of the problem is that the people putting the documentation together are too smart, or know the product too well, and because of this the documents are often too technical or simply not verbose enough and in a simple wording so everyone can follow everything without prompting or assistance.

To assist users, included in the program help, we do have the movies, which show the more common commands but simply can't cover everything or every situation. There are also a few tutorials to help people get a feel of how to work through a simple example or two.

On our web-site, we have the Frequently Asked Question (FAQ) area where many of the common questions asked by users, have been answered. There are about 17 questions from users in this 1 document alone. pick here

We also have technical documents under User Tips, written to help clarify topics where questions have arisen. pick here

And finally, this user forum, where people can ask anything about the products and get answers in relatively short time. The extra bonus is that you can review questions and answers previously posted by your fellow users, to get answers to common questions.

I agree that our documentation can use some improvements, and we will strive to do what we can, as time goes on.

Thank you for your valuable input

Glen W. Cameron, C.E.T.
City of North Bay, Ontario

Post Reply