My idea to address this was that we would have a demo config which included a collection of bindings, mainly non-hardware based bindings, and the tutorial/user manual would reference that demo where examples are needed. This ties both the demo together with manual, provides a means for documenting the demo config, and gives the user a concrete working example to play with as they go through the guide.
In fact, one of my ideas was the user’s guide would walk the user through creating the demo config from scratch so if they followed everything they would have the same thing as the downloaded demo config.
It would be best not to tie the demo to any hardware specific binding though which raises a bit of a problem as I don’t think we can completely ignore the hardware based bindings in the User Guide. That is why we are all here after all.
I vote for yes. At best the Raspberry Pi specific info should be a subsection or chapter in the Linux article. Raspbian IS Linux so everything there should apply. We don’t want to have to document it twice. I question the need to have a separate Pi page in the first place, unless we are truly starting from the point of writing the Image to the SD card forward. In which case as soon as the article gets to the apt-get install stage it should point at the Linux article.
One thing that kai is very adamant about is DRY (Don’t Repeat Yourself) in the docs.
I remember signing up for the catchy name but not the reorg.
I’ll have to read everything that has been written so far and go from there. I wonder if it makes more sense just to get the To Do articles populated before worrying too much about structure. I foresee conflicts galore with people writing an article only to find that page has moved or been combined with another page. But if everyone things we should start on the reorg I’ll do that instead of taking some article off the list that can be written without too much actual OH2 experience (I’ve still not switched over so my practical knowledge is still pretty low).
Given that maybe I’d be better used by doing structural and organizational edits and changes. Thoughts?
As for the section name, my brain is refusing the be creative. I’ve got nothing that isn’t as equally as lame as “Working with openHAB”.
- openHAB in Practice
- Building the Home Automation
- Constructing the Automation
- Behaviors and User Interface
The problem I’m having is that there are really two to three levels of configuration. You have base openHAB configuration which would include things like the reverse proxy tutorial, installation, Designer installation, SAMBA config, logging, and all that type of stuff.
Then you have the configuration of the interface/interaction of openHAB with the outside world (Things, Items, and Bindings).
Then you have the “configuration” which is actually the user’s constructing their custom home automation system (rules, persistence, sitemap). Persistence is kind of in both this and the interface/interaction area so could be put in either place.
NOTE: I notice that there are a lot of capitalized "OpenHAB"s in the documents. I think it was decided in one of these documentation threads that openHAB should have an uncapitalized “o” in all cases, even when starting a sentence. It’s a nit but being consistent is important.
I’m having difficulty finding descriptive names for all three categories that makes sense.
But of course that’s up to you
