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: GitHub - openhab/openhab-docs: This repository contains the documentation for openHAB.; 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:
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.
Good work. 
Waiting for your PR. 
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.
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
Thanks @Andrew_Rowe
Will create a PR tomorrow, just to give a little more time to others that may want to chime in here too.
Once done, will edit the OP and provide link to PR.
Own a device
In many cases people already own devices we support.
So we could rephrase that, check in our bindings if we support already devices you own.
PR created:
Thanks everyone - especially @lipp_markus - for your work!
Fyi: I just made the necessary changes in the website’s build to pick up this file from openhab-docs (it wasn’t the case before), and it’s now live at: https://www.openhab.org/docs/
(with a minor cosmetic tweak at the top)
I will close the thread now, if there is no objections
maybe you could also move this one to one of the orga sections?