Ok. What is your opinion of the following:
Adding „Quick Guide“ on top of our documentation tree where I can start writing a new User‘s Quick Guide. This way I could mostly use your existing material and would link to your docs for more detailed information.
Personally, I think, it is „dangerous“ to direct a new and probably unexperienced user to our documentation because of the overwhelming content. But if that Quick Guide would be on top even before „Welcome // Introduction“ that would make it clear that new users should be starting with a Quick Guide first.
Even „Welcome // Introduction“ is too heavy for new users.
The problem is putting something that looks like documentation anywhere but the documentation page.
Also just because there might be some pushback doesn’t mean you can’t ultimately prevail. Most of the maintainers are reasonable and can be convinced to change their minds. But be prepared to make your case and pivot if you fail to convince them.
If it’s too heavy, why not make it less heavy? It seems awkward to have a guide even before the welcome. Note that the welcome page is to level set the users. That’s the first place where we make it clear what OH is and what it’s going to take to get it to work for you.
one step after the other. I really think that a Quick Guide is required which guides a new user from downloading OH to a first rule at ONE place in a very simplified way. I won‘t go into details or offer too many options as this sort of document has already prepared by you.
The guide does not have to be at the top of the menu tree. We‘ll have other options to guide new users there, like changing the „Getting started“ link on our website or have two links on our website or even other options.
The reason for the change is also that it is by far more complex to makes changes to the website than to our docs.
EDIT:
heavy is the wrong word, without explanation. It is not heavy in iteslf. It is a good document and not optimized for new users, because you wrote the doc for existing users desperately needing a detailed description.
It is like with any other software, too, where you have a few docs, each of them aimed at different target people (user guide, admin guide, update guide, …)
Funny, I think there’s different use cases and different solutions even for the same users. What are we aiming for?
When I started openHAB getting into run on a Raspberry PI had a good manual. Most frustrating first step was getting my USB zigbee stick to work using the OH UI (you almost lost me as a user). After that getting a simple button on a web page to turn lights on, also using the OH UI. Than a few buttons in a nice layout. After that same for my smart energy meter and a graph. I would have loved some step by step screenshot instructions to achieve this instead of loads of text describing all options with text configuration where I had no idea what to do with it.
Simple things. Rules, textual.configuration, yaml, widgets where not in my mind. Later yes, and on that point the documentation got more and more useful/important.for me. And now I start with the documentation. So you “evolve” as a user and by doing that your needs change.
Other words for … if the goal is helping a noobs user probably you can focus on just a small part of the openHAB features. And that might be enough, because if you are still around after that … the documentation of the other things becomes clearer and clearer (at least in my case it did).
@Oliver2 I propose just start by making a list of common startup tasks with example configuration so for example a user has knx at home what steps he has to do to have a working setup with dashboard location semantics uom all written in text files with screenshots of ets etc. Since I have some experience. What do you think ? Thing is the items can be imported from text file as I recently discovered and I was like wow. Maybe a simple conversion tool can be done for things as well.
Hi Viorel,
the aim of this guide is to become as quickly and as easy as possible operational with OH. All these great functions like UoM, etc. need to stay outside of the guide. This is what our exisitng docs are perfectly made for.
Given the standard is for Things to be discovered automatically (where possible), that definitely wouldn’t be something aimed at new users.
Being able to textually define those “advanced” things and import them would indeed be a useful tool.
Be careful though as most if not all bindings that have values that can have units, deliver to the Item values with units. These users will have to take a deliberate action by changing the Item from Number:X to just Number in order to simply ignore the units.
Because I already know openHAB.
Marketing is about showing/telling those who dont know and may have an interest. But I doubt its 70 year old Mrs “Something” which is in the segment.
Honestly, that’w what happens anyway. They demand “do better”. We ask “how? We’ve already done the best we can. Do you have anything concrete or even something to contribute?” And they rage quit anyway shouting “that’s not my job!”
It’s happened many times. No one is happy.
Personally, yes, I’d much rather they silently go somewhere else than poop all over the forum on their way out.
I understand where you´re getting at. And I mostly agree.
But sometimes a user cant explain or even come up with suggestion as to how to change things, beside telling what they feel is wrong. They may even be exstremly frustrated at the time, after spending hours/days trying to get something to work.
And even then I have seen (and tried myself) to ask, "wouldn´t it be better if…? ". Just to get told to either “do it yourself”, or “its not possible”, or somekind of third respons, which doesnt really change anything, like “do this insted” whereas “this” is something which is much more complicated.
Or the most typical - “go ahead, make an PR”, to users who dont even know what a PR is, where its suppose to be “made” etc.
Things goes all wrong, when the suggestion is asked, where the author/maintainer dont agree due to not beeing able to see the need of change from a new user/less knowledged user.
This can leave the user with the feeling, that its not welcome to suggest changes. And the frustration will only get worse.
I have felt that myself in a single occasion.
Ofcouse “do better” is not really a constructive critisism. And no one can work from that alone. But sometimes is may be worth turning the issue around and try by the use of simple communication, whats the issue, and maybe how to get around it/fix it/change it together with the author/maintainer/more knowledged. I guess thats what the community is for as well.
Most of the time it doesn’t play out like that though.
An angry user demands that something they cannot or will not inarticulate be done. Immediate we are on the wrong foot because neither I nor anyone else is going to do something just because it’s demanded by someone. Particularly someone whose only contribution back to the OH project is this one demand (note this is definitely not describing you personally, you’ve contributed lots and it’s appreciated).
Even in cases where it’s not so acrimonious, the person making the demand, or identifying something that could be done better are best able to implement it. Short of that, at least they can create an issue.
Almost everyone here on this forum are fully booked with what they are already volunteering to contribute to OH. So the most expedient way to get a change is to go do it yourself. Short of that file an issue and cross your fingers. Anything short of that is just complaining.
I am sympathetic to that but it also leaves the people who do create the Issues and PRs and help on the forum feeling unappreciated, taken advantage of, and demoralized. Why do volunteer all this effort when users are just going to complain it’s not good enough and demand more?
The sense of entitlement I’ve seen on this forum at times have been staggering. I once spent probably about 40 hours helping this one person do some exotic and complicated microcontroler based project only in the end to answer when asked “why don’t you go learn how to do some of this yourself?” with “It’s all too complicated. I just want my gate to close. I shouldn’t have to learn all this stuff to achieve that. That’s your job. The easier to work with stuff is too expensive.” That was years ago now and I’ve not encountered something that bad before (note he got the same response from Arduino and other forums too) but I now know how to head it off and bail if it starts to head that direction.
And just to be clear, there is no one on this thread who fits this description.
Suggestions are always welcome. But ultimately some has to volunteer to do the work. And since no one can force another to volunteer it’s ultimately going to be up to the suggester to do the work or somehow enlist a volunteer to do it for them. Demanding isn’t going to make that happen.
one step after the other. I really think that a Quick Guide is required which guides a new user from downloading OH to a first rule at ONE place in a very simplified way. I won‘t go into details or offer too many options as this sort of document has already prepared by you.
That was years ago now and I’ve not encountered something that bad before (note he got the same response from Arduino and other forums too) but I now know how to head it off and bail if it starts to head that direction.