Improved documentation

[blartyo]

Hi,

 

I recently got my 99i and I feel the documentation could be improved.

 

It is quite challenging to figure out how to use the ISY unit using the User Guide. The User Guide is primarily laid out by menu. This is not as intuitive as laying out the guide by objective, scenario or 'how to'. E.g. "How to create scenes", "how to create programs to automate your lighting", etc. Using the menu approach, the manual talks about the program summary tab before it even explains what a program is!

 

It would be very helpful to have a list of all the programming commands with full descriptions of exactly what they do. Looks like this is in progress in the Wiki.

 

I also find that the User Guide is not so clearly written or comprehensive in its scope. There are so many additional things I'm learning about the ISY's function in the forums that really should be covered in the User Guide. For example, how the From/To command functions is not very well described in the User Guide. I would prefer to use the forums as a place to hone my programming skills and figure out creative methods of using the device rather than to simply figure out what a command actually does.

 

Perhaps the Wiki will one day be the answer. But, even though it is improving rapidly, as of this writing it is still incomplete.

 

I think that improved documentation will make the product experience much better for new users and could also help lower the barrier to entry for the product. Right now, I think one must be a little bit of a geek at heart and be willing to dedicate a lot of time to learning the ins and outs of the ISY world.

 

I really do mean this as an area for product improvement, not as a complaint.

 

One area I do not think needs to be improved is the absolutely great support provided and the amazing community of users that are there to help guide newcomers along the path to 'enlightenment'.

 

Regards.

[Mark Sanctuary]

Wiki is the documentation! Michel started the Wiki because he knew it would be tough to keep up with the changes so let the users help out! I (a user myself) work a bunch on it, a couple other users work on it, plus all users are welcome to join and help.

 

Here is the Program Command that has been in the works today by Rand and me.

 

The "How Tos" are coming and yes there is already one for creating scenes. You will find about 10 of them so far, just look down the page toward the bottom in the User Guide.

 

Lots of work to be done join the Wiki and help other users. I don't work for ISY, I just love my ISY!

[Michel Kohanim]

blartyo,

 

Point well taken and we are aware of it. We are very thankful to those who spend their time improving it.

 

Mark, Rand, Mike, Frank, Steve ... THANK YOU!

 

With kind regards,

Michel

[blartyo]

Thanks everyone. As I mentioned the support and the community are truly great. Hopefully I'll get to the point where I can contribute to the Wiki as well.

 

Speaking of the Wiki, how does one register to be able to add to the Wiki? I clicked on Log in/Create Account, but no info is provided as to how to create an account.

 

 

Regards.

[Mark Sanctuary]

The Program Commands list is coming along, I hope this is more what you where looking for.

[Michel Kohanim]

blartyo,

 

Thanks so very much for the offer. Please send an email to support@universal-devices.com and it shall be taken care of.

 

Mark, thanks so very much.

 

With kind regards,

Michel

 

Thanks everyone. As I mentioned the support and the community are truly great. Hopefully I'll get to the point where I can contribute to the Wiki as well.

 

Speaking of the Wiki, how does one register to be able to add to the Wiki? I clicked on Log in/Create Account, but no info is provided as to how to create an account.

 

 

Regards.

[Mark Sanctuary]

Michel,

 

I tried to add this to the Log in/create account page but looks like I don't have the privileges. Could you copy and paste this Wiki formated text on that page for future users?

 

----cut-here----

 

==Join The UDI Wiki Team==

 

This collaborative Wiki is intended to be continually developed by [http] and its user base. In order for this guide to improve it needs user support. The best way to help is by contributing your own information, experiences, tips, and examples. So if you’re interested in developing this guide, please request a login ID by dropping us a note on our [mailto] email address.

 

 

If you're joining the UDI Wiki editing team please see our [[Help]] section which can also always be found in the navigation box on the left of every Wiki page. Also if your wondering who is working on this Wiki you can check our [[special]].

 

----cut-here----

[Mark Sanctuary]

blartyo,

Your in a good position to really benefit the Wiki. You’re in the early stages of learning about the ISY, so you will come across things that use old timers could miss. If you document along your learning path it may benefit other new users, so I suggest as you learn something write it up an put it on the Wiki. If you have any Wiki questions please feel free to ask me, I have Wiki editing experience and enjoy helping others. Welcome in advance to the Wiki!

 

Speaking of the Wiki, how does one register to be able to add to the Wiki? I clicked on Log in/Create Account, but no info is provided as to how to create an account.

[sfhutchi]

One point that I also took from this post is that we should look at some minor organization changes to the wiki. For example, the 'How To' stuff is embedded under the ISY-26 (even though it also pertains to the 99) and the links actually go back to the forum.

 

I agree that simple 'how to' step by step with pictures is how many people learn. The 'How to Create a Scene' is a great example. If we as the user community could start listing some of the desired 'how to's' and then start documenting them in the wiki.... I know that this will help many newcomers as it would have been a big help to me.

 

Concerning the structure, I don't want to change too much of this without UDI's involvement. My suggestion would be to move much of the functional stuff up towards the front and where it relates only to the 99 for example, add a note.

 

Eventually, I think that many of the Examples could be converted to How-To's and put on the wiki. My opinion is that the forum can be a good 'think tank' for the examples, but the good ones should be documented with pictures in the wiki. The extra replies and posts and difficulty adding pictures in the forum (it appears that you must host the pictures yourself) makes this a little less clean than the wiki for a 'how to' manual. (in my humble opinion )

 

I am ready to get back into things here... so maybe we should start a thread with desired 'how-to's' and those of us that are willing and able to work on the wiki can assign ourselves to certain ones to start. Others can then help and contribute after they are put out there???

[MikeB]

My time is fairly limited, but I'd like to help wherever I can.

[Michel Kohanim]

Mark,

 

I don't have access either! So, maybe we can put it right on the first page?

 

 

With kind regards,

Michel

 

Michel,

 

I tried to add this to the Log in/create account page but looks like I don't have the privileges. Could you copy and paste this Wiki formated text on that page for future users?

 

----cut-here----

 

==Join The UDI Wiki Team==

 

This collaborative Wiki is intended to be continually developed by [http] and its user base. In order for this guide to improve it needs user support. The best way to help is by contributing your own information, experiences, tips, and examples. So if you’re interested in developing this guide, please request a login ID by dropping us a note on our [mailto] email address.

 

 

If you're joining the UDI Wiki editing team please see our [[Help]] section which can also always be found in the navigation box on the left of every Wiki page. Also if your wondering who is working on this Wiki you can check our [[special]].

 

----cut-here----

[Mark Sanctuary]

The ISY-99i will be mostly the same docs as the ISY-26 except for the IR stuff.

 

I did the last rearrangement of the Wiki and I don't mind working on it again. I think the pages that are shared may just stay with the “ISY-26 Insteon†category. The ones that are ISY-99i pages could be in a new “ISY-99i Insteon†category of their own. If we do want to move them maybe a category of “ISY Insteon†should be used instead for them. And if these pages do get moved the INSTEON will be done in caps.

 

I do want to point out though that there are about 80 pages in the “ISY-26 Insteon†category that would need moving and re-linking about 200 plus links spread out though the Wiki. Last time I did this it took three days total.

 

1. [*:1perdrrg]â€How Tos†move to their own page which can be linked both ISY-99i and ISY-26.
   [*:1perdrrg]Each “How To†should have a link on the bottom of the page which points to its discussion forum.
   [*:1perdrrg]Add new “How To†links for new ideas, let different owners take them on.

Since I have been doing most of the “How Tos†so far let me share my process. What I do is watch the forum for what new questions are asked, remember back how often it has been asked, then add the ones I have recall have been asked before.

 

The “How Tosâ€, I like the idea that someone grabs one and does the initial write-up. Then others can fine tune the work after that. That sounds good. I do suggest for edit discussions we might use the Wiki discussion tab for each page and save the linked forum for the user to discuss configuration issues for that “How Toâ€.

 

Also I have done a bunch of study on Wiki formating and will try to help make sure all the writings maintain that Wiki style. I hope that helps all so they don't really have to worry so much about style but focus more on doing a good write-up.

[Mark Sanctuary]

There is already a note there. Let me see if I can make it stand out a bit more so it gets noticed.

 

Mark,

 

I don't have access either! So, maybe we can put it right on the first page?

 

 

With kind regards,

Michel

 

Michel,

 

I tried to add this to the Log in/create account page but looks like I don't have the privileges. Could you copy and paste this Wiki formated text on that page for future users?

 

----cut-here----

 

==Join The UDI Wiki Team==

 

This collaborative Wiki is intended to be continually developed by [http] and its user base. In order for this guide to improve it needs user support. The best way to help is by contributing your own information, experiences, tips, and examples. So if you’re interested in developing this guide, please request a login ID by dropping us a note on our [mailto] email address.

 

 

If you're joining the UDI Wiki editing team please see our [[Help]] section which can also always be found in the navigation box on the left of every Wiki page. Also if your wondering who is working on this Wiki you can check our [[special]].

 

----cut-here----

[Michel Kohanim]

Mark,

 

Thank you so very much for your efforts. We all really do appreciate it so very much ...

 

With kind regards,

Michel

 

There is already a note there. Let me see if I can make it stand out a bit more so it gets noticed.

[blartyo]

Hi Mark,

 

Thanks and I'll try to take you up on your offer of documenting my learnings from a newcomer's perspective.

 

Regards.

[Mark Sanctuary]

I did some work on the ISY-99i Series page which I think will help with your suggestion.

 

Concerning the structure ........ move much of the functional stuff up towards the front and where it relates only to the 99 for example, add a note.

[sfhutchi]

1. [*:2vy858pl]â€How Tos†move to their own page which can be linked both ISY-99i and ISY-26.
   [*:2vy858pl]Each “How To†should have a link on the bottom of the page which points to its discussion forum.
   [*:2vy858pl]Add new “How To†links for new ideas, let different owners take them on.

Since I have been doing most of the “How Tos†so far let me share my process. What I do is watch the forum for what new questions are asked, remember back how often it has been asked, then add the ones I have recall have been asked before.

 

Sounds like a plan. I will look out for this in the wiki.

[blartyo]

Thanks for (re)organizing the Wiki Mark.

 

As you mentioned it makes it much easier for other users to add content. I've gone in and added some How-To's. I've tried to use straightforward language (as if I were the intended audience!).

[Mark Sanctuary]

blartyo thanks for adding the content. It looks great. I will test it soon. Did you want to do the screen captures or should I?

[blartyo]

Oh, I didn't think of screen captures. You can add some if you get a chance. If I'm not busy later this week, I'll check back on the wiki and try to add some as well.

 

I must admit, the screen captures do help.

[sfhutchi]

There may be some better screen capture programs out there.. but I use a free one call ScreenHunter. You just pick a key to trigger it, like F2, and simply press 'F2', then select the area you want and it can either put it in your Clipboard, save to a file, or both. Great for documenting stuff like this.

[Mark Sanctuary]

Yardman and all,

 

I would like discussing the origination of the Wiki. Yardman and others in the past expressed it was too confusing and wanted to change it, so I would like to get some ideas. When the ideas are finalized I don't mind spending the time reorganizing it for all. Might I suggest that we discuss in outline format like below which would make the implementation much easier later. Michel I want your feedback too, after all you’re the top guy.

 

Main

__ Products

_____ ISY-26

_____ ISY-99i

__ Support Section

_____ Troubleshooting

_____ Known Issues

__ etc.

[Algorithm]

Eventually, I think that many of the Examples could be converted to How-To's and put on the wiki. My opinion is that the forum can be a good 'think tank' for the examples, but the good ones should be documented with pictures in the wiki. The extra replies and posts and difficulty adding pictures in the forum (it appears that you must host the pictures yourself) makes this a little less clean than the wiki for a 'how to' manual. (in my humble opinion )

Emphasis added; remainder quoted for context.

 

Yes, this is a bit of a problem, especially for those who are not able to host pictures. And if a user does host a picture, if he moves his hosting to a different site then we have a broken link.

 

Michel and I chatted a bit about this some time ago, and wondered whether there may be some free picture hosting service which could be used. Does anyone know of such?

 

Of course, that could still be susceptible to broken links should the service happen to go away. The best way may be to host them on the UDI site itself, where they will never go away. How are the Wiki pictures hosted?

[Mark Sanctuary]

The 3.0 version of phpBB supports attachments which are stored on the same server as it is installed and configured. Also each user that uploads attachments can manage their own files in the User Control Panel. Right now the UDI forum is running the 2.0 version of phpBB.

 

Yes, this is a bit of a problem, especially for those who are not able to host pictures. And if a user does host a picture, if he moves his hosting to a different site then we have a broken link.

When a user uploads a file to the Wiki, the image files are hosted on the same Wiki server.

 

How are the Wiki pictures hosted?

Of course with either of these tools the admin can reconfigure them to put the files anywhere to his liking, but this is what I understand for each one.

[Algorithm]

Thanks Mark, that is helpful.