[CLOSED] "Introduction" in docs: proposed rewrite

I would agree with both of you, it is not necessary for a beginner to own his own device but I believe most do. My own experience might be considered typical?
Like many new user (I believe, just my opinion) I bought a few smart home devices. I took them home, read the directions and installed some app on my phone and started playing with my new toy. It was the device’s inability to automate to the level of customization I wanted and the ability to interact with other devices (from other manufacturers) that led me to search for a solution which ultimately lead me to openHAB.

The discussion is on the suggested new documentation. As such, the new suggested documentation above states

You don’t ‘need’ to own a device to try openHAB. You probably do, but you don’t ‘need’ to

Better version might include something along the lines of…

you probably already own a device you wish to control, but even if you don’t, you can try out openHAB

4 Likes

On the question of platform:

I strongly suggest no one single platform is suggested. (or emphasized)

Reason being, most people like certain platforms. If you say Windows to a Mac guy, prepare to get screamed at. If you suggest Mac to Windows users, prepare to have things thrown at you. If you suggest Linux to either group, prepare for a blank stare. I’ve been there and bear the scars. People like their platform.

Suggestion:

OpenHAB runs on many popular platforms such as Windows, Mac and Linux)

Don’t create further hurdles. Most, like me, may want to try it out on the platform they are using

2 Likes

First big Thank You to @lipp_markus for starting this thread. I had considered creating forum versions of the individual pages of the documention to work on together as you have done so above. Great work!

Second point: As noted in the PR, I believe this actual doc resides in the ESH repository and as such may need further vetting before being included in the official documentation. (by the ESH team ect. not sure) This can be discussed in the PR thread

Edit to add:
I believe the ‘Introduction’ page is the landing point for many new users and as such is a vital target for improving the documentation for new users

1 Like

Agree. Maybe mention it does not have to be a classic HA device (actuator, sensor, gateway) but can be a Inet enabled TV or similar as well.

Agree, BUT we should give a recommendation how to proceed because otherwise many users feel lost in choices for the first time right away (those without IT affinity/knowledge for sure).
Something like

OpenHAB runs on most popular platforms such as Linux, Windows and MacOS and on almost any
hardware ranging from Raspberry Pis to desktop computers and server PCs.
You can install it on your desktop computer for evaluation purposes but we recommend using a dedicated
system in the long run. So if you feel serious about home automation better start with one right away.
If you already have any of these systems available for use or have a strong bias towards using any of them,
then it's your best choice to go with it.
Anyone undecided we propose to get a Raspi and use openHABian to get things up and running quickly.
2 Likes

excellent suggestions both

OpenHAB runs on most popular platforms such as Linux, Windows and MacOS and on almost any
hardware ranging from Raspberry Pis to desktop computers and server PCs.
You can install openHAB on your desktop computer for evaluation purposes if you already have any of these systems available for use but we recommend using a dedicated system in the long run.
If you have a strong preference towards a particular platform, then that platform is probably your best choice.
If you feel serious about home automation it may be better to start with a dedicated system right away.
For anyone undecided, we suggest a Raspi and using openHABian to get things up and running quickly.

Small change…
You have identified which computer you want to start with. (This may change as you go through the learning curve and your system grow. Make sure to make regulare backups to avoid starting from scratch if changing computer).

Reason - I just realized that the computer I started with (Rpi 3B) does not fulfill my goals.

I would also like to point out that it is very difficult to write a documentation that corresponds to the different skills. A beginner is often overwhelmed because it seems too complicated and overloaded. An advanced or professional just gets bored because he already knows most of it.

You should possibly distinguish between several user groups: absolute beginner, advanced and professional.

You could also start with a small and short questionnaire (for example 3-5 questions). Depending on how the reader answers them, you can steer the further sequence accordingly in the right direction.

Possible questions could be:

Do you already have experience of home automation systems?
Do you already have home automation devices in use?
Do you know better with Windows, Linux or macOS?
Are you ready to invest in new PC?
Would you prefer a graphical user interface or would you rather write texts or small scripts?
Do you like DIY or do you prefer ready-to-use?

@Celaeno1 @mstormi @Andrew_Rowe thanks much!!
My intent has been to keep this simple and an easy read and not to overwhelm the new user too much.


I don’t think the latter two will read much of the introduction anyway. I attempted to write it in a way, that advanced and professionals can just glance through it and get in a second that they will not learn anything. So, I would suggest to keep it rather simple and easy, without many choices to make as this can easily overwhelm the novice and the more advanced groups will not learn anything new anyway.

For me, this would add complications as all questions would require more definitions to be meaningful. For example: does experience of linking a Hue system to Alexa qualify as “experience with home automation?”
Would it help much to know that the user has a TADFRI system in use?
Personally, knowing that a RPI sets me back only $50 or less, would make a difference when asked if I am ready to invest this amount. But then, is a RPi a PC or not? And what if I have a supported NAS?
etc.


adding it above, thank you both


Much agree. Most users will desire to influence actuators. Adding this to the text above.


Indeed, the docs live here: https://github.com/openhab/openhab-docs; Ultimately, a PR will need to be raised, but I was advised in earlier revisions that it might be best to discuss any major additions first in the forum to gather broad input. On github will be a second round of comments.
Part of this proposed revision, however, will also affect the “Concepts” section, which seems to be pulled straight out of the ESH doc repo. At a later point we will need to have to figure this one out.


I understand completely, however, these are the OH docs and in particular this is an intro for new users. This behoves and I believe mandates us to make a recommendations for all brand new newbies. I would want to believe that the text above is worded mildly enough so that even the strong believers will see their favorite choice mentioned. BUT I also believe that we need to make a statement/recommendations to those that do not follow pre-ordained routes. OpenHABian is definitely the easiest choice for all non computer experts, at least just reading the forum, this seems to be the recommendation frequently given.

Agree strongly
I believe the introduction is an important section of the documentation for new users and as such is a good place to start with in regard to improving the documentation for new users.

For me, this would already be a slightly advanced user!

It is not just about the minimum cost, but the question of whether I have to assemble something, install the OS itself, there is already pre-installed everything, so ready-to-use! Do I really need that to start? If you have the impression that you absolutely need it, but you are shy of learning something new, then you would not even start with it!

Agree
If I know zip diddly about OpenHAB, I’m supposed to go buy a Pi?
If I can’t figure out what platform I want to give openHAB a test drive, I probably don’t even know what a Razberry PI is (I didn’t and I’m a kind of geeky guy)

@lipp_markus please join in separate discussion about recommended platform here:
https://community.openhab.org/t/new-docs-discussion-should-we-recommend-a-platform/62822/2

Great work @lipp_markus ! Good introduction where you take an interested reader through the step-by-step process, learning them some basics along the way.
I would not complicate it as per Alex’s suggestions, it needs to stay an introduction.
Thanks.

1 Like

Good work. :slightly_smiling_face:

Waiting for your PR. :+1:

1 Like

OK, after replying to a million other posts, I would like to offer MY suggestion:
this first sentence:

The open H ome A utomation B us (openHAB, pronounced ˈəʊpənˈhæb ) is an open source, technology agnostic home automation platform which runs as the center of your smart home!

should remain
reason?
This sentence… whether grammatically correct or the perfect opening statement or whatever… is plastered all over the internet in links (new and old) and quotes and what not as to become almost synonymous with openHAB.

1 Like

OK, one more little suggestion
list reasons why openHAB is so cool… sell the idea a little first
example:

With openHAB you can…

make your home automation system work exactly how you want

your home automation system is completely under your control

set up a home automation system that does not need to connect to the internet to function

use it with all your devices or create your own
(and I say ‘all’ because if you are crafty enough, nothing is off the table)

run on any platform

save money on utilities

ect ect ect
feel free to add more

technology agnostic

I just love the term:
technology agnostic

when I read that, I imagine people running to google ‘agnostic’ and by the time they have figured out what ‘technology agnostic’ means… they are sold!

Good point, haven’t spend much time on the About section, but this sentence is perfect there, will add.


Happy to add some points, but would prefer the list to be rather short, so would suggest we focus on three to four items max. will add something

good thought, yes yes agreed
keep it short
bullet points

OK, in the interest of not completely reinventing the wheel but rather massaging the current documentation to make it better, I believe we have the text for a good PR
@lipp_markus great job and we can discuss any small issues in PR thread
does this already have PR? suggest link if not in first post because reading comprehension owns me