Harold Posted July 23, 2013 Posted July 23, 2013 I am in the 70 years plus category. An electrical engineer and computer science/designer. When I started this it was wiring panels and punch cards (do a historical search to enjoy the implications). It has been 20 or 30 years since I have had involvement with detail levels of programming, hardware design, or fiddling with operating systems (I did OS/360 at one time at the assembler level). I never actually came across any live biologic dinosaurs, but there were a number of electronic ones. Why do I share this information? I am not completely inept, I have some idea about what is going on, I know how a whole bunch of this stuff works. I am probably more informed than "Joe sixpack" but certainly less than any current serious techie. So if I don't understand, Joe is going to have problems. The ISY is a seriously cool device (remember, I am old). It is not real easy to use. My brother has an Insteon system and is unable to actually make it work effectively. There is no way he could do anything with an ISY. I have been using the assorted documentation and tutorials to try to get things the way I want them to be. I would like to point out a couple of areas which could be helpful to non-technical owners. When writing about things, be cognizant of the readers ability to understand the words you use. They may glide off your metaphorical tongue like warm butter, but do they necessarily mean anything to the reader. The reader may well be completely unknowledgeable about the terminology of the various parts of the system. The most egregious mistake is to assume "well everyone knows how/what/why to do that". I understand that it is a pain in the butt to take this into consideration, but it would seriously enhance the lives of new users and potential users. One area that I think should get significantly more attention is instructions for doing tasks that interact with external processes (OS,Java, browser, etc). Microsoft has an incredibly annoying habit of moving things around; apparently just for the Hell of it. When a series of instructions are written, there should be a clear disclosure of what versions of other software (e.g., Win 7, Win 8, etc.) is being used to accomplish what ever you are trying to explain. The menus, names, and parameters can be completely different between versions. I realize that many of the how-to articles here are submitted by volunteers. They can not be held responsible for maintaining the currancy of the contents. And it is not a question of rewriting each article; just updating things that change. and that should not eliminate the information for previous releases of whatever; but be an addition. There are still a lot of Win XP users. My suggestion is for UD to take responsibility for a specific area of the forums. The tutorial section would be reasonable. Either through UD resources, or the dedicated users that contribute, review the "understandability" of tutorials and periodically review them for current applicability. I realize this is a burden, but I think it would of real value. How many people buy a UD product and then simply give up. There could be a section of tutorials etc. that are maintained by UD (or its' civilian helpers) and a section for raw submissions where you "put down your money and you takes your choice". Articles can migrate between groups. One specific area that I would suggest some good documentation is how all of the various parts and pieces of the system work. These are dependent on releases of internal and external processes. For example, how to do something with Java when the Java menus change. Or the fully qualified name of something you are supposed to use. A few diagrams showing the interactions and appropriate control points of an installed system. Where are the parts of the system located and how can they be modified. How does it all work/tie together. I just find myself bouncing around between different places and posts trying to resolve issues that are probably not real obscure. But the contents are out of date and the instructions will not work. The Wiki should probably be the repository, but it needs to ingest more of the tutorials and helpful hints. What are the correct parameters for Java for the current system environment. Where is information stored. Things like that. Particularly from the host operating system standpoint. I just find myself spending a lot of time bouncing about in the forums to find answers and many times finding solutions that do not work with current environments. And not knowing where pieces are stored. There is a huge body of knowledge accumulated here. But it can be quite difficult to parse.
oberkc Posted July 23, 2013 Posted July 23, 2013 I find this an interesting request. On one hand, I have been quite happy with my success using the ISY. On the other hand, I know (nor care about) anything Java or external processes. Do you believe such knowledge is required to get an ISY-based insteon system to work? Certainly, I don't.
Michel Kohanim Posted July 23, 2013 Posted July 23, 2013 Hi Harold, first of all, thanks so very much for the feedback. It's quite helpful. Please find my comments below. When writing about things, be cognizant of the readers ability to understand the words you use. They may glide off your metaphorical tongue like warm butter, but do they necessarily mean anything to the reader. The reader may well be completely unknowledgeable about the terminology of the various parts of the system. The most egregious mistake is to assume "well everyone knows how/what/why to do that". I understand that it is a pain in the butt to take this into consideration, but it would seriously enhance the lives of new users and potential users. Have you checked out our recent version of the User Guide ( http://www.universal-devices.com/docs/p ... 0%20a2.pdf )? We did in fact spend considerable amount of resources on quite a professional tech writer/editor to whom I am very grateful. Does the user guide need more refinement? If so, more details of where would be quite appreciated. Furthermore we did create a few short Video tutorial: http://wiki.universal-devices.com One area that I think should get significantly more attention is instructions for doing tasks that interact with external processes (OS,Java, browser, etc). Microsoft has an incredibly annoying habit of moving things around; apparently just for the Hell of it. When a series of instructions are written, there should be a clear disclosure of what versions of other software (e.g., Win 7, Win 8, etc.) is being used to accomplish what ever you are trying to explain. The menus, names, and parameters can be completely different between versions. This I agree with and we shall work on it. Heck, I have more problems with my MAC/Java than I have ever had with any Windows version. As such, yes, it's needed. My suggestion is for UD to take responsibility for a specific area of the forums. The tutorial section would be reasonable. Forums or Wiki? Either through UD resources, or the dedicated users that contribute, review the "understandability" of tutorials and periodically review them for current applicability. I realize this is a burden, but I think it would of real value. How many people buy a UD product and then simply give up. There could be a section of tutorials etc. that are maintained by UD (or its' civilian helpers) and a section for raw submissions where you "put down your money and you takes your choice". Articles can migrate between groups. This is more than a burden. This is basically not possible based on our resources and that's why we do make EVERY effort to make the User Guide to be the complete guide you need for your specific version. Wiki is organic and it grows that way. User Guide is the most important document and then augmented by our support team, Wiki, and forums. One specific area that I would suggest some good documentation is how all of the various parts and pieces of the system work. These are dependent on releases of internal and external processes. For example, how to do something with Java when the Java menus change. Or the fully qualified name of something you are supposed to use. A few diagrams showing the interactions and appropriate control points of an installed system. Where are the parts of the system located and how can they be modified. How does it all work/tie together. I am not sure I agree with the Java part since, basically, you should NOT know anything about Java. As far as diagrams, yes, I agree. I just find myself bouncing around between different places and posts trying to resolve issues that are probably not real obscure. But the contents are out of date and the instructions will not work. The Wiki should probably be the repository, but it needs to ingest more of the tutorials and helpful hints. Again, a) User Guide Contact Support c) and d) use Forum/Wiki to augment What are the correct parameters for Java for the current system environment. Where is information stored. Things like that. Particularly from the host operating system standpoint. I just find myself spending a lot of time bouncing about in the forums to find answers and many times finding solutions that do not work with current environments. And not knowing where pieces are stored. There is a huge body of knowledge accumulated here. But it can be quite difficult to parse. None. I do not set any of those parameters myself! With kind regards, Michel
Recommended Posts