I have recently been reviewing the documentation for openHAB with a keen eye toward how it might be perceived by a new user. I would like to use this thread as an open discussion for how we might improve the documentation to be more understandable for someone who knows nothing about openHAB. I welcome any and all comments, suggestions or ideas from long time users, developers and newbies (like myself)
My quest is (initially) going to be looking at the documents which I feel are the places most new users land when they first begin to try to find out what openHAB is. I would consider those to be the introduction section, the concepts section and the installation section.
I plan to add posts to this thread with various ideas, observations and comments and welcome others to do the same. If a certain topic starts to muddle the thead, it can be split off to a new thread. Let consider this thread a chat
In my initial scan of the documents it also occurs to me that there may be vastly opposing view on what is a good idea and what isnât. Please try to remain civil
First subject:
The Concepts page
TL DR: The concepts page seems a little disjointed.
I recently read a comment from a new user that the concept page should be extremely easy to understand for someone who knows nothing about openHAB. If I remember correctly they also stated that openHABâs concept page starts out simple but then gets way to complex way to quickly. I remember reading it the first time myself.
I would like to introduce an idea which I will call the âyou lost me pointâ. Iâve read a lot of documentation in my life and often Iâve reach this point while reading. The âyou lost me pointâ is the place in the documentation where I began to get lost and gave up. I lost interest.
Sometimes the âyou lost me pointâ happens in the first three sentences. Other times its a few paragraphs in. It all depended on how bad I wanted to try to use the software how far I persisted. I believe our job is to try to move the âyou lost me pointâ as far as we can so to speak, without boring a person with average intelligence.
The first paragraph in the concepts oveview page states
it may be helpful to bear in mind that there are two ways of thinking about or viewing your system; the physical view and the functional view
The writer seems to be setting up a metaphor. The paragraph continues
you can think of the physical view as being a view of the âreal worldâ, and the functional view being a view of the âsoftware worldâ
In the next section describing things states
Things are entities that can be physically added to a system.
But at the end of the paragraph states
Things do not have to be physical devices
Can anybody see where a new user might find this hugely confusing?
I think what the author intended was not that things are entities that can be physically added to the system but more the metaphor of âThingsâ are items that exist in the metaphorical âreal worldâ. The whole section Things, Channels, Bindings, Items and Links just is to convoluted, to fast, to many new ideas. First time thru, you blew right by the âyou lost me pointâ by the end of the second paragraph.
When I read new user documentation, I expect to be introduced to some new nomenclature. Things are such an example of new nomenclature. Understanding Things is important to understanding openHAB or is it?
This is just an example. I also realize fixing this page could be an incredible task as it covers so much material. It also seems to be hosted on Eclipse Smart Home repo so may need to be reviewed and merge by different standards then openHAB docs
Next Subject
Documentation is a little Pi centric
Now I realize that the little Razberry Pi is a very popular platform for openHAB, but the documentation for Linux installation does very little to help folks who wish to install Linux on a PC using there favorite distro.
Hi Andrew,
Can you point to specific areas that you feel are too Raspberry Pi centric? Iâm just guessing, but thereâs probably more written for the Raspberry PI because itâs one of the more popular Linux platforms. I also have a hunch that if you managed to get Linux up and running somewhere else, you are somewhat conversant with Linux and can translate whatâs available for other platforms.
Just my 2 cents.
Regards,
Burzin
Next Subject
Why so many user interfaces?
TL DR: What the heck is Paper UI
I actually realize the benefits of so many choices for user interfaces and love it but for a new user all the user interfaces may be very confusing. The choice of which user interface the new user wants to use also comes very fast in the process of setting up openHAB.
After some months of using openHAB, Iâve heard it stated that Paper UI is for administration and set up only over and over again. Well, why is it not called administration user interface or set up user interface. I donât know the history of the name but it is a completely abstract name from my point of view.
Why isnât Habpanel called the phone interface? Why is home builder listed with the other interfaces when it is not really an interface but a tool to create sitemaps?
One solution for this issue may be to present the new user with only one interface initially or at least explain the choices a little better
HABPanel is a customizable UI that can be used for anything a user wants. There is nothing in its documentation about phones. Where does this question even come from?
Good question. In linux desktop environments developers finally start to call their apps according to its function. Instead of KControl, Amarok, Banshee, whatever you know have "System Settings, âMusic Playerâ etc.
I thing Paper UI (letâs call it âSetup and Maintenanceâ) should get much more love as it is the public face of OH. And it causes so many questions here in the community. It should be much more self explaining.
Thatâs why Iâm working on a design study at the moment (Donât click here, really).
I just started a few days ago, but at some point I want everyone to participate to make it easy and self-explanatory with context related help, or at the right time a link to a matching documentation page.
Maybe you could also help with ideas, sketch something out, think of context help texts.
The new UI would not have any control functionality anymore (except right at an item or channel maybe for test purposes) and complements HABPanel.
Cheers, David
sorry, the comment was some what tongue in cheek (I was joking⊠apparently badly) I think HABPanel is a great interface, it just appears to be designed with a smaller screen in mind such as a phone or tablet.
the public face of OH⊠very well put indeed. And you are absolutely right, it is the public face of openHAB. And why not? Paper UI is beautiful and already really very functional. Why must it be consigned to maintenance and administrative duties? The control tab actually makes a dandy interface, I use it all the time. Give me the ability to move stuff around to my liking and add some styles and done! Iâll take it.
And gosh it does get a ton of questions asked about it. Just seems mysterious to most, so polished and yet so seemly useless. When the functionality is explain its a game changer. More self explaining would be great even if it does ever make it to the UI big league
Agreed.
But I also think set up and maintenance tasks donât need their own âuser interfaceâ (and I think you agree with me David) Set up and maintenance should be a tab on a user interface. or somewhere you go when you click >> go to set up button
The whole concept of multiple interfaces is really very ânew user unfriendlyâ. At the very least, I believe the set up should preempt the choice by asking how your are going to use openHAB and suggesting an interface. Or better explain why there are multiple interfaces. When someone sets up openHAB, they are going to have to open a browser on some device and look at an interface. Paper UI works good on a phone or small screen right? (I look at it on a full size monitor in a regular web browser) Why not make Paper UI the default interface?
@David_Graeff your design study looks really great and I look forward to collaborating on it.
Yes I know, and it is truly beautiful and I donât mean to beat up on HABPanel but it is also completely non-functional when it is first opened up. The same goes for the basic UI, completely non functional until the user builds a sitemap. This discussion is about new user documentation and the idea of offering a completely non functioning user interface to a brand new user seems absolutely ludicrous.
To get a new user to use openHAB, we have to explain what it is and why you would want to use it. We have to explain what is required for it to run (install JAVA) We have to explain how to download it and install it. Once it is installed, not giving consideration to which user interface is used, we need to explain how to install binding, explain how to discover new things, find the channels and create items. If the new user makes it that far, and they have Paper UI, they can at least see thier new light bulb or whatever and turn it on and off.
I think no other further complication needs to be added to the above written process. This process should be made as stupid simple as possible if gaining new users or wider spread adoption is a goal. We are not done yet, openHAB still does not do anything automated. Hopefully the new rules engine can make creating rules easy enough.
Habmin could also serve as an excellent first time user interface
I have a hunch you are right. But should we just assume that is the case and ignore these folks? Linux is universally touted as the best platform for openHAB. (native even) Razberry Pis are often vilified in the forum for being unreliable. I have a lot of previous experience with Linux setting up multiple email servers and file servers running Red Hat, CentOS and fedora. I set up lots of desk tops with Mint and Ubuntu. Guess what, I struggled a little with getting openHAB loaded on my new dedicated PC
Everything useful is non-functional when first opened up. (Ok, maybe not everything, but many things)
OH is not a product. It is a system; a DIY kit for enabling the doing of useful things.
When you buy a new train set, you donât open the box, go âOh, how useless, itâs completely non-functionalâ, and then throw it away. It requires setup.
This is like claiming your new toy train is broken because you havenât put batteries in it. The UIs are fully functional. But they require other things to be configured before theyâll do much.
Have you helped people here in the community? Questions are often of the same nature.
The idea is with a better first time UI and better documentation to reduce questions to an absolute minimum.
Ideally people are just coming by to present their working system and bring in some new ideas.
Next Subject:
To many ways to do one thing
TL DR: There are multiple ways of doing one thing
Now I know this flies in the face of everything openHAB is. We picked openHAB for itâs versatility.
Years ago I made a living teaching users to use a popular vector drawing program still in use today. I distinctly remember users asking what the ârightâ way to do something. Options confuse new users
My proposed solution is to present new users with a single easy method of using openHAB and leave the other methods for another day. Tell new users there are numerous ways to use openHAB but present one single unified method to first time users.
Example
- Install openHAB
- navigate to user interface. (sole interface for now, paper UI or whatever)
- Click the accessories you want to use (bindings)
- Your devices magically appear (discovery), channels are created (simple mode), items are created
- simple common rules are already there to choose from or use new gen rules engine to make more complex ones
The current documentation explains both options (there are usually two options, an old OH1 way and a new way). I vote for removing all old technology pages and hide them under a âLegacy wayâ link. This includes
- DSL rules
- Sitemaps
- ClassicUI
This is silly. I thought you said OH is not a product. When you buy a car, does it come with a set of wrenches or a user manual? When you buy a hamburger does it come with a barbeque grill or a napkin
Because so few bother to RTFM before bleating a query to the world at large.
I agree good documentation is needed. But I do not like the idea of dumbing it down to the level weâre currently talking about.
This I agree with. We should also eliminate anything in the OH1 wiki that is covered in the OH2 docs site.
Agreed
Put your best foot forward. The new gen rules engine is almost ready for prime time. It may not be able to handle complex use cases yet but it can make simple rules right? Items can be made from Paper UI, channels, items and links can all live in the DB, no text files or manual configuration at all! Donât take away the users ability to customize or use scripts, custom UIs or OH1 methods, just hid them initially from new users.