First of all thank you @namraccr for participating in this thread. I would like to remind you that this is all very blue sky thinking. I’m a designer by day and we call this spit balling, throwing stuff against the wall and seeing what sticks. Yes maybe some of these ideas are dumb, but maybe a dumb idea will spark a new good idea. But frankly if attracting new users and broadening the adoption of openHAB is the goal, RTFM is not going to cut it.
Is what has been suggested here really that dumbed down?
I look at the docs as they are today. I think about what it felt like when I first started a few months ago. I think about what can be realistically done in the short term to streamline the new user documentation and the whole installation and set up process still seems horribly complex for the average user.
It would be great to have some continuity in all the changes that have been made to the docs in the last couple of month.
I do a lot of linking to the official docs in my forum answers and those links are mostly dead because of all the changes.
Things I could find easy through the search function cannot be found anymore. The contents section on the left changes frequently. Bad idea.
I have to spend more time searching the docs to get a link to copy it to a forum answer than to answer the actual question.
The eclipse developer documentation will also be merged at some point, as new technologies are only described there. I expect one more navigation change.
Is it possible to link to a doc search result instead where the user would need to pick the first link?
Thank you @Andrew_Rowe for starting this topic!
I also felt in the last weeks that there are more and more new users having problems with the docs and how to get started. So I had a look on this introduction and getting started pages I haven’t visited for some years. Trying to imagine to know nothing about openHAB I can understand that it can be hard to get an idea what OH is, how it works and what’s the best way to get started. Although I think this is hard task for the docs.
So, here are some of my ideas. Happy to discuss them with you all.
What I find confusing is the mix of mentioning the let’s call it abstraction layers (Things, Channels, Items) with openHAB add-on types (bindings). In my opinion these are to different things.
Proposal: We should have two sections (or 2 different pages)
- First to explain what OH is
- A framework to build your individual home automation solution
- to do so it provides some core functionality that can be extended with hundreds of add-ons
- explain the different add-on types (what is a binding, what is data persistence, …)
- Explain the abstraction layers
- Things → e.g. a hue lamp
- maybe also Bridge as special Thing → e.g. the hue hub
- Channels → e.g. the color channel of this hue lamp
- Items → the layer that OH uses to work with
- Links → association of a Things channel with an Item
Personally I would prefer this to be written down as a table without too much of text to stay clear and a picture that illustrates it.
One more thing that just comes into my mind (I think it was discussed in some other thread, can’t remember which one). Not sure if this is really important for the new user documentation but I feel will help to get a better orientation regarding the add-ons.
The add-ons reference we have is a great start. But what I would like to see are tags for all the add-ons that are also searchable. Maybe something like Docker has on Dockerhub.
As of today we just have the v2 or v1 tag. What about extending this:
- version: since 2.1
- status: maintenance status of an add-on, e.g.
- beta = still in development, use at your own risk
- legacy = still there but no longer supported and no further development
- active = for productive use, actively maintained
- official = supported by the OEM, e.g from Philips for Hue (do we have something like this?)
- …
- type: add-on type + some sub classification, e.g.
- binding home automation standard (e.g. zwave, knx, …)
- binding home automation vendor specific (e.g. Philips hue, Homematic, …)
- binding multimedia (e.g. Sonos, Kodi, …)
- binding information provider (e.g. OpenWeatherMap, Tankerkönig, …)
- …
- binding generic (e.g. http, bluetooth, …)
This tags could be not just shown in the docs but also in PaperUI.
I’m not sure if the openHAB documentation is the right place to teach people how to set up a Linux system. I assume someone who wants to run openHAB on Linux has already his distro of choice running. The docs should state what you have to do to install openHAB on that kind of distro (deb, rpm, …)
First thing I don’t like here is the section “Interfaces and Ecosystem” in the current docs. I would propose to split this up in 2 sections → UI’s and “Ecosystem” (not sure of this is the best fitting term, maybe Tools fits better?)
The UI section should start with an overview table (just my understanding of the different UIs):
- Administration UIs
- Paper UI = Standard UI for administration
- HABmin = optional admin UI, especially when using Zwave bindiong
- Sitemap based UIs
- BasicUI = standard UI for using openHAB in any kind of browser
- ClassicUI = alternative to BasicUI, different look and feel, was standard in openHAB 1.x
- Native apps for mobile devices: Android App, iOS App, Windows 10 app
- Non-Sitemap based UIs
- HABPanel = Interface to set up individual dashboards, especially useful when having a wall-mounted screen
- HABot = not sure if this is really a UI or should be mentioned in the Ecosystem section
Recommendation for new users can also be added to this table/list.
Here I disagree. I think it makes absolutely sense to have the admin functions separated from the UI a “normal user” uses. A lot of tools do it this way. Imagine your kids or parents or guest hitting theset up tab accidentally and are deleting some things not knowing what they are doing. To have this functionality separated on a different (admin) UI is one solution to prevent this. Another one would be to have a fully qualified user and role management
Agree. I think HABPanel is not the UI to start with when you’re new to openHAB as you have to set up each and every element on your own. The problem with sitemaps is that this is one part of openHAB that still comes form the 1.x days and has no 2.x equivalent. The standard UI should show you all items you have set up without the need to edit a textual config file. But I also agree with @David_Graeff that this should not be part of PaperUI.
There is some work going on for a new sitemap concept at ESH but I have no idea how the timeline looks like. For now this doesn’t help. Isn’t it possible to have an automatically created sitemap with all items? How does the control tab of PaperUI work?
I think we should highlight something like this in big red letters on the very first page of the new user documentation. In my opinion it is mission critical to make clear that OH is not a software like e.g Word. Just install it and start using it for writing letters.
It is a framework. After installing it, the journey begins. You have to think about how to organize your items, for which of them do you need historic values, which automation functions do you wanna realize, how should all these things be presented to the different users, …
This can also be seen as some kind of warning. If you are not willing to set up your own custom made home automation system openHAB is not your software of choice. If you just want to switch your hue lights with your phone stick with the hue app.
But I think this is fair. People starting with openHAB should know about that. They should know what OH is and what it is not.
So far my 2ct.
Greetings
Sebastian
Sitemaps are not necessarily anymore with widget based UIs available in my opinion. Paperui just shows all things and channels (that have a linked item) sorted by “location”. We could do that as a first-time use control UI, before someone has setup his widgets.
Hi all,
I would like to join the discussion and give my opinion on some special points i have recognized already.
First the general part
Thanks for bringing up this discussion @Andrew_Rowe.
There is already a huge amount of valuable content and aspects to think about.
Being objecitve
I would like to throw in something which everyone should pay attention too for the documentation.
Most of us are using openHAB and so we have a running environment and preferences on how to use/edit/configure stuff.
So sometimes we write something down and it simply isn’t written from an objective perspective/view.
This isn’t even on purpose, it’s just the way that has worked for me or you or someone lese the best in the last time.
I recognize this often, when i am explaining something and i am asking myself “how would i solve this task now”.
But maybe my approach or yours isn’t the best for the documentation and maybe we have one approach which simply can be described better.
So i would like to encourage everyone to actively go out if his/her bubble sometimes and think about approaches from a different point.
Legacy Stuff
This is based mainly on the following quotes:
Basically i would agree with both of you, that we have to simplify the entry point.
We should give advice for the recommended approach in OH2.
From my point of view this would be Paper UI for administration and configuration.
On some point of a tuturial/introduction page we can mention that “there is more available, but it’s not meant to be used for a newbie”.
But we have to take care of some side effects we would create with this.
There is no real documentation for the new rules engine yet and this will need some work and time, evene tough Rich has started with some threads here.
So we would hide a big docs area without a real replacement.
Same goes for Sitemaps.
Sorry, but i have a completely different opinion.
Without Sitemap, most native apps are unusable.
Yes its OH1, but there is no valuable replacement available yet.
And just because HabPanel is used by many Persons, this cant be “the soulution” for everything and everyone.
Personal opinion here
I am not interested in mounting a Tablet somewhere or place it in the living room, to have some widgets available.
I want automation and a small and clean interface which i can use in the browser or on the native app.
HabPanel doesn’t provide that too me, or i would have to invest much time and effort.
I can do that with a small Sitemap in a faster time.
So what i want to say is:
Yes we should simplify the start and maybe do some choices for the user.
Like a little Poll/Question round on startup like suggested above.
If one doesn’t want to use OH1 Addons, why bother him/her with textual confugarion on the first run?
Theres no need to do so.
But we have to find a good mix between easy entry and showing the possibilities of OH, which are way more than Paper UI and Habpanel.
Continuity
Alltough i can understand the problem, it will be difficult to simplify and improve the docs without breaking anything or breaking the anchors.
My advice for long term reliability would be to link whole articles and not specific headline anchors.
I don’t think that page links will change that often and you can name the page area you want to refer to, so it will still be findable even if the anchor changes or the article is reworked a bit.
Unfortunately not.
I have asked that already for the search funvtion in our vscode extension.
Algolia seems not to support direct search links currently.
Misc
I am not sure about everythign discussed on the concepts parts, but don’t want to join the discussion for that subtopic without thinking about it for more than 2 minutes, so i wlll comment about that at a later point.
Anyways thanks to al involved for the constructive discussion till now.
I think we can make some good progress here.
I would hide the DSL rules sections only, there is scripting nowadays instead (Javascript, Jython, all other languages).
From a developer standpoint: DSL rules make about 1/5 of the entire eclipse smarthome code base if I had to estimate and pulls in the huge xtend dependency and often fails during the build process for first time users. If that could be moved to the OH1 legacy repository, that would be a blessing.
This is correct. Apps should gain the ability to just present Things/Channels like Paper UI does, with the user being able to hide elements he doesn’t want to see. And rearrange other elements. So basically more feature rich that what we currently offer with static sitemaps.
For two reasons, 1) there’s “admin” (PaperUI, habmin, .things/.items files) and “user” (HABpanel, BasicUI, sitemaps, .rules files, nextgen rule engine) interfaces and 2) for historic reasons, there’s multiple ways to do the same thing in textual and UI form, and there’s multiple alternative UIs.
I guess maintainers don’t want to drop any of these options as they’re all in use, sometimes the only right tool for a very specific task, and no contributor’s work deserves to be thrown out.
I have been wondering how to emphasize at least that distinction between “admin” and “user”. Maybe we should introduce the concept of an “integrator” or “smart electrician” (other suggestions welcome) to the docs.
That is what people know from their (non-smart) house technology, it’s the guy to install and maintain the heating and electrical systems of their houses. He’s installing all the stuff, he’s only involved in the beginning, for major extensions and for maintenance, he’s using a different interface than the house owner does, unlike the user, he has access to everything but he also brings the knowledge it takes to fulfill that job.
[in an idealized world at least, no stories of stupid craftsmen please, we all know more than enough of them].
Then, at some central paragraph, we need to state that the home owner is the integrator, too, but that he always has to remember the duality when working on the system.
Did you read Configuration | openHAB
I recently added that to the docs. Eventually it would make sense to forward-reference there.
I have seen that recently and like the overview. But I saw this as a TODO for developers actually to condense to a few apps only. My plan is to make Paper UI the perfect admin tool with a check tick on every of your rows (and habmin would be the “Setup & Maintenance Pro” app).
Oh dear, no please!
We’re talking about making the docs more user-centric, so please forget about your developer’s perspective for the moment. A proposal like that is the opposite of user-centrism.
Effectively, almost everybody is using DSL to run their house, and this will continue to be the state of the nation for quite some time. Those few to use ERE or JSR223 don’t make up for a countable fraction.
Don’t start telling users it’s legacy what they do and that they need to move elsewhere now that they just learned it !
I’m sorry I was a bit off, I was talking about the code, but this thread is about the documentation. Of course.
But the documentation should target first-time users, so explain all the current/newest technology, only linking to older alternatives. The documentation will feel a lot stream lined that way.
Developers can only support that amount of legacy code. And OH is full of old/new ways. Just look at the startup problems with many DSL rules. A hypothetical OH3 with only exact one (but powerful) way of doing things would be so much performing better. So users somehow need to be taught to migrate at some point or stick to an older version (as this is possible with OH1, too).
Actually, having recently glanced back through parts of the documentation I hadn’t visited since first starting to use openHAB, I do remember seeing that but didn’t realize it was new. Maybe I thought I missed it first time but anyhow, I really like it now that I’ve looked at it and consider it a big improvement in the direction the new user documentation should evolve. To my eyes, this is a great step toward
I think the chart is a great improvemnet, visual aids help people understand complex ideas!
Something else I saw just below the chart
openHAB is a system installed and executed by you, running independently from any online services or proprietary technologies. You as the end-user have the full control over every aspect of your smart home.
This should be on the Introduction page! These two sentences really express what openHAB is and why it is superior to every proprietary system out there. Great job Markus!
Agreed
The sections of the documentation introduction and concepts basically are primarily only read by new users. Those two section can literally ‘make or break’ the new user experience.
I think this is a worthy idea and obtainable goal in the short term.
strongly agree
I’ve heard some talk of roles or accounts where one user logs in, perhaps provide password, then is given access to functionalities normal users are not allowed (set up, configuration and maintenance tasks)
Excellent point and very important
Agree.
In addition when we’re talking about the basic introduction pages of the docs for new users maybe it makes sense not just to concentrate on newest technologies but also to stick with the basic information needed to get up and running. More advanced information (e.g. the pros and cons of different Java platforms on the install page) as well as the reference to alternative ways of doing something can be hidden under an “advanced/expert paragraph” that is collapsed by default or separated with some colored boxes etc. I see this in some docs and think it makes sense to distinguish which information targets which kind of reader
Strongly agree
or a small section at the bottom labeled ‘learn more…’ with links to more advanced topics
A worthy and actionable short term goal IMHO
simplify the process for new users
This is an intriguing idea and one I have thought about. The idea is in the documentation or even during set up, a routine runs, perhaps pops up a dialog box. Asks simple questions which can then slightly alter the options which are installed or simply forwards the reader to a document which explains the step by step installation based on the results of the little poll/question round
perhaps a slightly longer term but worthy project
Edit to add:
I see the initial page that loads on first start up, the one where the user chooses which interface to use, as being sort of the above idea, or a gateway to a admin interface or a user interface. But it isn’t presented like that currently. Here… pick a user interface.
What… I’m a first time user. I want ‘the’ interface. I want to see the application I just installed.
Excellent suggestion
Or to take this idea one step further, split documentation of advanced topics to a separate portion of the documentation labeled ‘Advance’ as in read this later when you get things running and get comfortable.
OK, just to clarify
I would consider the ‘entry point’ to be the introduction section, the concept section and the installation portion including initial set up.
In the short term, attempting to streamline these three areas sounds like a good start which requires only changing the documentation and no coding changes to the application. Already though, this discussion has drawn strong opinions representing several some what opposing views on the direction openHAB should take in the future which could have some bearing in how different people believe a new version of the above named sections of the documentation should be crafted.
This discussion has been useful so far in focusing on goals and considering varying views.
Perhaps a way forward is to look more closely at these three section individually and try to draw some consensus on improving them without having to recreate openHAB or decide the future direction openHAB should take
From my point of view the task of improving the three sections varies in difficulty. Installation for instance would require expertise in several operating systems and require much collaboration
Edit to add:
upon further review and link below to new user tutorial as also being very important to the new user portion of the documentation
There is a tutorial: First-time setup of openHAB
https://www.openhab.org/docs/tutorial/1sttimesetup.html
There is a phrase: “For starters, we recommend the “Standard” package.”
I rather would recommend the “demo” package. That’s how I started, years ago.
A new user can see “running” examples… and how they work. After this “first look” the user can decide if OH is fitting his expectations.