The documentation for the InsteonPLM binding is getting unwieldy, and I have plans of adding more device specific documentation. How can I structure the monolithic page into smaller ones (e.g. one for Insteon light switches, thermostats, etc) within the existing documentation framework?
One approach would be to merely link from the wiki page to the source XML file for each specific release, so that there is no possible inaccuracy between the wiki page and the specific release that the user is interested in. The current arrangement, where a user may be attempting to use a device that’s not supported by the release they are using would be avoided. For example
Or if you don’t like that view, you could push the raw XML through an XSLT transform using some public service on demand for a pretty HTML table output.
Your answer addresses a somewhat different issue (making the documentation revision dependent) than what I was aiming at (just breaking it up into smaller pages), but maybe your suggestion will ultimately allow for a more structured wiki page as well.
Just to make sure I understand what you are saying: we should put the documentation into the source tree? That means people will have to submit pull requests to update the wiki page. I don’t have a problem with that, but the gatekeepers may.
The second point is: when people click on the links on the wiki page, will the linked content be rendered with mark-down, just like right now? Is that what you are referring to when you talk about an XSLT transform? I wouldn’t know how to set this up.
My idea was a bit more radical: eliminate a hand-edited version of the table of supported devices altogether, since they will be inconsistent with the source and not release specific, by simply linking to the XML file (per release tag) from the wiki page. That way, there is no question about which devices are supported from one openHAB release to the next. The XML file is about as readable as pretty tables in markdown anyway, in my opinion.
By comparison, the Z-Wave Binding wiki page makes no effort to enumerate all supported devices, probably because it would be an ongoing documentation nightmare, and would likely be more often wrong than right. I was just this evening looking to see if the Z-Wave binding supported a particular device, so I dove right into the binding’s database and found the answer straightaway.
Or if you disagree as to readability of the Insteon XML file, you can generate a pretty HTML table by using the raw XML as the source, transformed through an XSLT processor that generates HTML on the fly. There are many tutorials on how to use XSLT to process XML into HTML. But really, that seems like putting too much effort into it. Just give users release-specific links into the XML source, and problem solved.
…problem solved, I like it
Firstly, you two are smarter than me. Secondly, my ideas are simple, but so are most jumping into openHAB for the first time. So let me give you my first impressions of the openHAB InsteonPLM binding documentation…
Yes, it’s looks like it’s busting at the seams, but it’s all good…it addresses some basic questions I have in setting up openHAB for my 100% Insteon home, but also advanced ones…unfortunately for me it was late and going back and forth from shallow to deep info was making me sea-sick!
Ideally what I was looking for was what @watou said can be tedious, I see some value in maintaining specific release files (or at least past two releases) so that some newbie like me can copy/paste from a known working insteonPLM_default_18.items file the devices I own into myhouse.items and change the device names, ids, labels to get openHAB to switch a light bulb on and off an hour after downloading openHAB distribution. With the latter being the goal, that should focus how to organise the documentation alltogether, or maybe just “quick start” path alternative. What do you think? BTW, once I get my sea-legs I’m more than happy to assist in maintaining files and/or documentation.
I think @Bernd_Pfrommer has done a great job so far on this (applause…applause). My vote is for something like insteon_default.* file library in addition to @watou’s thoughts. I’m ready to start today, but first I need help in getting my 20+ devices moved from my HouseLinc.xml file into appropriate openHAB files. Can you point me in the right direction? I just saw mentioned by @watou the “bindings database” so I’m off to see what I can learn there…