Thanks for the suggestions guys… And time permitting once I get my head around this OH2 / MQTT thing I might see if I can offer a different perspective to understanding it.
When it comes to documentation writing there are several ways to approach it depending on how complex the subject matter is. In a former life I was a licensing specialist at Microsoft, so I know about complexity and permutations, hundreds of products through close to a dozen different marketing channels, and rarely did any of them line up.
The one thing that really jumps out at me as a huge need, is pictures. We all start this journey knowing relatively the same amount of nothing. I used to travel around the country doing licensing presentation to partners, and a few simple PowerPoint slides (and sometimes not so simple slides) really help cement a concept or an idea.
Once I get OH, I expect to look back and think that wasn’t all that hard. Thinking that it just tells me that the problem is in the learning, not in the knowing.
I am a very visual and tactile person, so seeing and touching are the best way for me to learn, endless text is not my preferred way to learn and quite often the more that is said the more inclined I am to be confused.
One of the reasons I never did so well at school is because I answered the wrong question. For me I found most questions lacked enough detail to fully answer the question properly, so often I wound up answering the question best I could based on the information I had, whereas often the question they were asking was on a completely different tangent and in most cases far simpler than the question I was trying to answer.
I have a fairly analytical brain so when I get what appears to be conflicting information, it sends my head into a spin trying to work out in an algorithm style thinking how it is possible for all answers to be correct.
That is why for me a simple and complete working examples are the best way for me to learn. Several simple examples allows me to analyse the differences and see how to make the changes I need based purely upon what I see.
From what I understand of OH how I would approach teaching this is to start with the most basic of basics (think of basic, and nope simpler than that). An image just popped into my head… Imagine I was trying teach you how to build an engine (something I did a lot of way back in my youth) I wouldn’t start off by saying Revs x CI x VE / 3456 is the basis for determining air flow. You have only just heard about this “engine” thing the same way you have just heard about openHAB. So Revs or revolutions mean nothing to you, nor does CI or cubic inches, or VE volumetric efficiency and why would I be dividing it by 3456? Already your head would be swimming lost in terms that you not only don’t know, but have no concept of what they do.
If I was trying to take a fresh off the boat newbie who had just heard of OH, knew they needed it but had no idea what it was, I would launch into teaching them nothing… why nothing? because we’re not ready to start explaining what it is or what it does just yet. Instead I would start of with showing them an exploded picture like this. And be very clear that it is not necessary at this point to understand what you are looking at, I was going to explain what each of the parts are and how they fit together as we go along.
All part make up an engine, but some parts play a greater role than others. For example the crankshaft, rods and pistons are the heart of an internal combustion engine (ICE - note I didn’t use the acronym until I typed it out in full and directly after it, and really during a beginner tutorial is best avoided altogether) but I probably wouldn’t want to start there because trying to explain how this reciprocating mass works would get messy, and besides I would have the drill down on things like bearings which I never mentioned. What I might start with is the engine block, as it is a foundation stone in the engine.
Then I might mention the pistons slide up and down inside the bores inside the block. Next I explain that the piston that goes up and down is connected to a connecting rod, so named because that is its function. The rod and piston both travel up and down in the bore (again just reinforcing and building on the concept that rod and piston work in unison) there’s no need to mention at this point that the rod goes through an array of angles pushing the piston up and down, we are still just taking baby steps. Next we can mention that crankshaft is attached to the other end of the connecting rod and the function of the crankshaft is to turn in a circular motion. Probably time for a slightly more advanced picture or gif showing the crankshaft rotating and now you can mention that because the connecting rod is connected to the crankshaft via the big end of the connecting rod (called the big end because of its size relative to other end of the connecting rod which is called the little end or eye), when the crankshaft goes around the rod moves with it causing the connecting rod to also turn in a circular motion (we have now mentioned the rod angles but no mention of relative rod speed changes).
Even if you had no clue how an engine works just reading these few paragraphs and looking at the pictures (that would be there) you have just learned what is at the heart of most internal combustion engines (without being flustered). Doesn’t matter if it is petrol or diesel the fundamental concepts are the same. The same way the relationship between each of the Items, Things, etc etc would have the same conceptual connection regardless of what the final configuration may be.
I would bet money that if first time users could see and touch (metaphorically) Things, Items etc etc and understood in simple terms their relationship to one another without ever seeing a single line of code, when it comes time to introducing the code most people would get it so much easier and with fewer questions.
