New User documentation

documentation
Tags: #<Tag:0x00007f0147c65f08>

(Andrew Rowe) #1

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


(Andrew Rowe) #2

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


(Andrew Rowe) #3

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.


(Burzin Sumariwalla) #4

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


(Andrew Rowe) #5

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


(namraccr) #6

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?


(David Graeff) #7

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


(Andrew Rowe) #8

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.


(Andrew Rowe) #9

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


(Andrew Rowe) #10

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.


(Andrew Rowe) #11

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


(Andrew Rowe) #12

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


(namraccr) #13

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.


(David Graeff) #14

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.


(Andrew Rowe) #15

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

  1. Install openHAB
  2. navigate to user interface. (sole interface for now, paper UI or whatever)
  3. Click the accessories you want to use (bindings)
  4. Your devices magically appear (discovery), channels are created (simple mode), items are created
  5. simple common rules are already there to choose from or use new gen rules engine to make more complex ones

(David Graeff) #16

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

(Andrew Rowe) #17

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


(namraccr) #18

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.


(namraccr) #19

This I agree with. We should also eliminate anything in the OH1 wiki that is covered in the OH2 docs site.


(Andrew Rowe) #20

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.