@rlkoshak I think I may articulate what my problem is. Please consider that it’s only my subjective impression that may be wrong, partially or fully.
My problem with OH docs is that it is still very much oriented to textual configuration that are kind of surplus from pre-MainUI era and while it’s still technically relevant it appears almost useless for a beginner like me if one wants to stick to MainUI to build the smart home. Beside Getting Started tutorial that only touches the surface (and you would end up with day duration in seconds and other ugliness like this) there is no sane docs on details (I still speak of MainUI-based configuration). Lots of undocumented (undocumented in the MainUI context I mean) options that only confuse the beginner. For example see the initial post of this topic. I found out that I may use regexp profile, I filled the appropriate field following the prompt… and nothing happened. Even worse, nothing happened silently. What am I doing wrong? How could I realize that metadata should be used this way if its beyond the scope of the beginner’s docs? While I’m pretty sure that it is documented somewhere, but understanding it and then mapping to MainUI use case doubles the complexity. As a result, using MainUI does not simplify the development, but makes it more difficult instead.
Please don’t take me wrong, I’m not complaining but rather feel that very important part is missing here. I’m constantly learn something (also to postpone the Alzheimer’s visit TBH) but learning OH is arguably the toughest task I faced within last two or even three decades, and it shouldn’t be so. I’m pretty sure I’ll eventually make it, but I feel it should not be this difficult. Because there is a huge gap between the knowledge I gained after reading the beginner’s tutorial and the knowledge I need to make something practically usable and there is no docs to easily fill this gap. I simply don’t know what I’m missing and what to read! And when I try to read advanced docs sections I simply can not understand them because it’s oriented to text-based configuration (which I’m not familiar with) and contains a lot of notions and details that were not explained in the beginners’ sections. As a result I feel I’m reading relativistic theory in Mandarin dialect. For instance, notions like “Temperature [%1f %unit%]”. When I told to use this I’ve no idea how! Where to put it. Lately I’ve read a lot of threads on the forum but can not say I understood much.
I would propose to think about creating another section in the docs filling the gap I described. The docs said somewhere in the beginning that one should choose between text-based configuration and configuring via MainUI and not to mix them. At this point the user should be directed to one part of the docs (existing) or the another, MainUI-oriented with explanations of details and probably some examples and howtos. Good start for this are forum threads with questions answered. BTW, very good example of such approach is your post on deeper dive into semantic model. To my opinion it is well balanced between accuracy and comprehensibility and should be in the docs but not lost into forum threads. The existing docs tries to be accurate, but this makes it harder to understand.
I realize it’s a lot of work, but in a short while I expect less elementary questions on the forum. At least from myself. And bigger user base.
What I think is missing (short list in no particular order).
- Explanations of data flow (not complex brain-blowing diagrams but practical aspects). How to transform values, data aggregation, etc. How to, say, transform the value a Channel returns to needed form not to get sunrise time with the date and day duration in seconds.
- Persistence. When I set up clean system, I got red alerts about persistence services not configured. (BTW maybe some sane initial configuration would be helpful). There may be suggestions like “if you plan to use weather forecast, set up inmemory this way, if you plan to explore history, set up rrd4j this way” and so on. Concrete howtos instead of being fully accurate but pointless.
- Explanation of fields in the MainUI forms the beginner may use to achieve some practical goals (profiles, metadata, etc.). There was a gotcha to me that metadata may be used to transform values, for instance. (That’s very important. Personally I don’t understand the purpose of good half of the fields, and searching through the docs often doesn’t help much. For example, when creating Item from Channel one may choose to create new Item or to use existing one. I could not find any explanation of the latter option. When to choose it, when in may be helpful and so on).
- Tips and Tricks section. I know there is a section named this way but it’s not really tips and tricks at all, but just a developer sidebar description (please consider to rename it BTW). OH is very complicated system, and many things may be done in different way. It’s totally unclear for the beginner what to choose. Imagine the beginner who read the tutorial and is able to do some very simple things and stuck at this point. Lots of options, no clear vision.
- Howtos. And more howtos. The forum is good source of this kind of information, it just needs to be structured.
Without this I’d say the MainUI fails to achieve its goal to help beginners and make learning curve not so steep. When I was choosing between OH and HA and googled “OH vs. HA” most resources I found were “how I migrated from OH to HA and never looked back”. It is not fair, is it? Now I understand their reasons while I personally still prefer OH over HA. But OH definitely needs some more love to become friendlier to the user.
Thanks!