We Need a Contributor-Editable Wiki

Posted on
Sun Dec 04, 2016 3:37 pm
Bollar offline
Posts: 528
Joined: Aug 11, 2013

We Need a Contributor-Editable Wiki

We really need a wiki where mere mortals, like myself, can make contributions to Indigo documentation, devices, plug-ins & how-to's.

I have burned hours this week trying to find things that are not documented, are documented incompletely, or are hidden in message threads. I'd love to be able to take what I've found and put it into a shared space for others to use. I'm hopeful others feel the same way and we'd eventually have everything we need to know about x plugin, y device or z method all in one place.

As a second issue, I'd encourage you to open up the official wiki to at least some selected powerusers. I know you don't have time to keep it updated - perhaps others do.

Insteon / Z-Wave / Bryant Evolution Connex /Tesla / Roomba / Elk M1 / SiteSage / Enphase Enlighten / NOAA Alerts

Posted on
Sun Dec 04, 2016 6:30 pm
exos offline
Posts: 57
Joined: Feb 02, 2016

Re: We Need a Contributor-Editable Wiki

Bollar wrote:
We really need a wiki where mere mortals, like myself, can make contributions to Indigo documentation, devices, plug-ins & how-to's.

I have burned hours this week trying to find things that are not documented, are documented incompletely, or are hidden in message threads. I'd love to be able to take what I've found and put it into a shared space for others to use. I'm hopeful others feel the same way and we'd eventually have everything we need to know about x plugin, y device or z method all in one place.

As a second issue, I'd encourage you to open up the official wiki to at least some selected powerusers. I know you don't have time to keep it updated - perhaps others do.



This is a great idea. We need a repository of information that can be editable. I do not own any plugins but I could create the wiki and host.


Sent from my iPhone using Tapatalk

Posted on
Sun Dec 04, 2016 8:18 pm
freshwuzhere offline
Posts: 103
Joined: Apr 05, 2012

Re: We Need a Contributor-Editable Wiki

Seconded! - or Thirded!

These can take a bit of editorial oversight as time goes on they can get rambly and hard to find things - but the idea is a good one!

Posted on
Mon Dec 05, 2016 8:38 am
eme jota ce offline
Posts: 618
Joined: Jul 09, 2009
Location: SW Florida

Re: We Need a Contributor-Editable Wiki

+1

Found myself thinking the same thing while looking at the plugin primer on this website, which was started with a nice introduction, but languished.

They did just post a great how to for the home bridge plugin.

Posted on
Mon Dec 05, 2016 11:26 am
Bollar offline
Posts: 528
Joined: Aug 11, 2013

Re: We Need a Contributor-Editable Wiki

eme jota ce wrote:
They did just post a great how to for the home bridge plugin.

They did? I can't find it, unless it's this one: http://forums.indigodomo.com/viewtopic.php?f=204&t=17405

I would like to make a few tweaks to that. ;)

Insteon / Z-Wave / Bryant Evolution Connex /Tesla / Roomba / Elk M1 / SiteSage / Enphase Enlighten / NOAA Alerts

Posted on
Mon Dec 05, 2016 11:43 am
Colorado4Wheeler offline
User avatar
Posts: 2794
Joined: Jul 20, 2009
Location: Colorado

Re: We Need a Contributor-Editable Wiki

Bollar wrote:
We really need a wiki where mere mortals, like myself, can make contributions to Indigo documentation


I brought that up to Jay and Matt a few months ago during the beta and the raised an extremely valid point that having a free-for-all Wiki can lead to troubles since everyone has their own interpretation. My suggestion would be to allow a group of us permissions to add content, then they can review it for accuracy and decide to publish it.

Bollar wrote:
I would like to make a few tweaks to that.


I wrote the thread you are referring to, as well as the HB Buddy plugin itself. Sorry you find it lacking, I cranked it out in 30 minutes to try to get the plugin out as soon as possible - and I mentioned that directly in the post that the information there as well as the documentation itself is in BETA.

My Modest Contributions to Indigo:

HomeKit Bridge | Device Extensions | Security Manager | LCD Creator | Room-O-Matic | Smart Dimmer | Scene Toggle | Powermiser | Homebridge Buddy

Check Them Out Here

Posted on
Mon Dec 05, 2016 12:18 pm
jay (support) offline
Site Admin
User avatar
Posts: 18185
Joined: Mar 19, 2008
Location: Austin, Texas

Re: We Need a Contributor-Editable Wiki

There are a few users/developers with write permission already. Let me take a couple of days to think through some specifics about it - on our wiki anyway. As C4W mentioned above we have to be quite careful since that wiki is our only source of "official" documentation so I want to make sure that we strike the right balance in terms of who can do what and where.

For 3rd party plugins that are hosted on Github, however, I'd recommend that you use the wiki feature for each plugin's repo. That keeps all the documentation, discussion and source for an open source plugin in a single place.

Jay (Indigo Support)
Twitter | Facebook | LinkedIn

Posted on
Mon Dec 05, 2016 1:24 pm
Bollar offline
Posts: 528
Joined: Aug 11, 2013

Re: We Need a Contributor-Editable Wiki

Colorado4Wheeler wrote:
Bollar wrote:
We really need a wiki where mere mortals, like myself, can make contributions to Indigo documentation


I brought that up to Jay and Matt a few months ago during the beta and the raised an extremely valid point that having a free-for-all Wiki can lead to troubles since everyone has their own interpretation. My suggestion would be to allow a group of us permissions to add content, then they can review it for accuracy and decide to publish it.


You truncated my quote, which ended: , devices, plug-ins & how-to's.. I think Matt & Jay are over-protective of their documentation, which would benefit from developer expertise, but that's a separate matter from all of the little things that a user really needs to know to best use all of the things that go along with Indigo. Things like, if you're going to buy an Insteon Leak Sensor, you really need Cynical Behaviors, or you'll have a heck of a time knowing if they are actually working, or if you buy the Aeotec siren, here are the raw Z-Wave commands you'll need to change the alarm tone and on and on. it's a perfect application for a wiki. I would advocate for a wiki that covers that content to be open to all Indigo license holders.

Colorado4Wheeler wrote:
Bollar wrote:
I would like to make a few tweaks to that.


I wrote the thread you are referring to, as well as the HB Buddy plugin itself. Sorry you find it lacking, I cranked it out in 30 minutes to try to get the plugin out as soon as possible - and I mentioned that directly in the post that the information there as well as the documentation itself is in BETA.

I would encourage you not to be offended by my comment and take my offer to contribute for what it is - I'd like to tweak (or more) every set of instructions I've ever seen. A developer could spend hundreds of hours on documentation and someone who hasn't tried to use the plugin before will most certainly come across something that presumes some prior knowledge that the end user doesn't have.

As it is now, what I learn and try to share has to be posted in a thread that may or may not be incorporated in the author's instructions. It's inefficient for me as well as those who follow.

Insteon / Z-Wave / Bryant Evolution Connex /Tesla / Roomba / Elk M1 / SiteSage / Enphase Enlighten / NOAA Alerts

Posted on
Mon Dec 05, 2016 1:39 pm
Bollar offline
Posts: 528
Joined: Aug 11, 2013

Re: We Need a Contributor-Editable Wiki

jay (support) wrote:
There are a few users/developers with write permission already. Let me take a couple of days to think through some specifics about it - on our wiki anyway. As C4W mentioned above we have to be quite careful since that wiki is our only source of "official" documentation so I want to make sure that we strike the right balance in terms of who can do what and where.

For 3rd party plugins that are hosted on Github, however, I'd recommend that you use the wiki feature for each plugin's repo. That keeps all the documentation, discussion and source for an open source plugin in a single place.

For your documentation, I get your concern, but I don't think it's as big a deal as you do - presumably you and your trusted editors would quickly revert anything that is incorrect.

As for all of the other things, I checked several of the GitHub pages I use and have not yet found one that has Wikis enabled. Anyway, IMO, it would be ideal if all of this was in one place, so everything I need to know about using x device with y plugin is in one place.

Insteon / Z-Wave / Bryant Evolution Connex /Tesla / Roomba / Elk M1 / SiteSage / Enphase Enlighten / NOAA Alerts

Posted on
Mon Dec 05, 2016 1:44 pm
Colorado4Wheeler offline
User avatar
Posts: 2794
Joined: Jul 20, 2009
Location: Colorado

Re: We Need a Contributor-Editable Wiki

Bollar wrote:
I'd like to tweak (or more) every set of instructions I've ever seen.


That is why opening the Wiki could be really dangerous. If every set of instructions you have ever seen seem to be poorly written in your view yet thousands of other users find it helpful then wouldn't that be tailoring the documentation to your own standards at the expense of the other users that like it how it is? If you were free to do as you wished with the docs then that could cause the actual developers of those applications (or, also, in this case plugins) more headaches.

I'm not being confrontational, just saying that you might write an amazing set of instructions for my plugin but then again, you might not :).

My Modest Contributions to Indigo:

HomeKit Bridge | Device Extensions | Security Manager | LCD Creator | Room-O-Matic | Smart Dimmer | Scene Toggle | Powermiser | Homebridge Buddy

Check Them Out Here

Posted on
Mon Dec 05, 2016 2:03 pm
Bollar offline
Posts: 528
Joined: Aug 11, 2013

Re: We Need a Contributor-Editable Wiki

Colorado4Wheeler wrote:
Bollar wrote:
I'd like to tweak (or more) every set of instructions I've ever seen.


That is why opening the Wiki could be really dangerous. If every set of instructions you have ever seen seem to be poorly written in your view yet thousands of other users find it helpful then wouldn't that be tailoring the documentation to your own standards at the expense of the other users that like it how it is? If you were free to do as you wished with the docs then that could cause the actual developers of those applications (or, also, in this case plugins) more headaches.

I'm not being confrontational, just saying that you might write an amazing set of instructions for my plugin but then again, you might not :).

I didn't say "poorly written" and you shouldn't assume that's what I meant (please don't make me define 'tweak'). If something would benefit from clarification, a tip or a how-to, I'd like to be able to easily contribute that. As another wiki editor, you are free to revert my changes, edit them to your liking or agree with them. As a community, we wind up with great documentation that none of us would be able to do on our own.

Insteon / Z-Wave / Bryant Evolution Connex /Tesla / Roomba / Elk M1 / SiteSage / Enphase Enlighten / NOAA Alerts

Posted on
Mon Dec 05, 2016 2:05 pm
Colorado4Wheeler offline
User avatar
Posts: 2794
Joined: Jul 20, 2009
Location: Colorado

Re: We Need a Contributor-Editable Wiki

Bollar wrote:
I didn't say "poorly written" and you shouldn't assume that's what I meant


Noted.

Well, I do know that PHPBB is the foundation platform for this forum and the wiki, and if you have ever worked with it before you'll know that it's a fairly large task to open it up, especially with the "community input to accept or revert" type of functionality that some big documentation wikis have.

My Modest Contributions to Indigo:

HomeKit Bridge | Device Extensions | Security Manager | LCD Creator | Room-O-Matic | Smart Dimmer | Scene Toggle | Powermiser | Homebridge Buddy

Check Them Out Here

Posted on
Mon Dec 05, 2016 6:18 pm
Bollar offline
Posts: 528
Joined: Aug 11, 2013

Re: We Need a Contributor-Editable Wiki

Colorado4Wheeler wrote:
Well, I do know that PHPBB is the foundation platform for this forum and the wiki, and if you have ever worked with it before you'll know that it's a fairly large task to open it up, especially with the "community input to accept or revert" type of functionality that some big documentation wikis have.

Yes. I don't think it's ideal to have a Wiki in phpBB, but perhaps a contributor wiki could be hosted on something like http://www.wikispaces.com. If it's easy enough for Jay & Matt to add licensed users to it, I think we can be trusted to keep it up to date and valuable.

Insteon / Z-Wave / Bryant Evolution Connex /Tesla / Roomba / Elk M1 / SiteSage / Enphase Enlighten / NOAA Alerts

Posted on
Mon Dec 05, 2016 10:54 pm
srkinard offline
Posts: 319
Joined: Apr 10, 2016
Location: Austin, Texas

Re: We Need a Contributor-Editable Wiki

jay (support) wrote:
There are a few users/developers with write permission already. Let me take a couple of days to think through some specifics about it - on our wiki anyway. As C4W mentioned above we have to be quite careful since that wiki is our only source of "official" documentation so I want to make sure that we strike the right balance in terms of who can do what and where..


Hey Jay...you gonna grant durosity full edit capabilities? :lol:

Posted on
Tue Dec 06, 2016 6:19 am
durosity offline
User avatar
Posts: 4319
Joined: May 10, 2012
Location: Newcastle Upon Tyne, Ye Ol' England.

Re: We Need a Contributor-Editable Wiki

srkinard wrote:
jay (support) wrote:
There are a few users/developers with write permission already. Let me take a couple of days to think through some specifics about it - on our wiki anyway. As C4W mentioned above we have to be quite careful since that wiki is our only source of "official" documentation so I want to make sure that we strike the right balance in terms of who can do what and where..


Hey Jay...you gonna grant durosity full edit capabilities? :lol:


Jay's already granted me full admin access... well.. kinda.. he shouldn't have left his little black book of passwords sitting where anyone can get it. I mean leaving it in a safebox with a novice lock on it is just asking for it to be broken into. #skyrimsneakthief

From a sensiblility point of view though i don't feel that everyone should be able to modify. I'd suggest it should be a privilage given to established plugin devs and possibly people of special abilities.. not plebs like myself :)

Computer says no.

Who is online

Users browsing this forum: No registered users and 3 guests