First, a word on the order of the sections in the docs. It assumes users read them in order, that is, first the concepts, then the installation guide, and when they reach the tutorial section. I’m not so sure about this so I’d suggest to call the tutorial Getting Started or similar and move it to the top. Then the tutorial intro’s first paragraphs could be a quick overview (or recap) of the concepts and the installation options, with links to the other sections (Concepts and Installation Guide) to go deeper.
If a document is short, I think more people are likely to read in order, beginning to end. The longer or more complex a document gets (and that’s just unavoidable depending upon the topic), the less likely people are do this. In an age of hyperlinked documents, I think many people will jump around to what interests them after a certain introductory point.
Also, I’m not the biggest fan of the content on the entry page at https://openhab.org/docs/ , especially the “motivational speak” right at the start (“keep your focus”, “result of hard work” etc.), IMHO that page should go back to describing with a neutral tone how the docs themselves are organized, i.e. what the sections are and what you can find in them. That content could however be a good fit for the introduction of this tutorial/getting started section. The only section I would leave there is the “openHAB community” and maybe the last one about architecture.
I think there may be a good compromise between the two point of views. I too could do without the What You Need to Know Before You Start section. My main objection is that it really doesn’t tell much. From my point of view, the summary is “OpenHAB will take some work to get up and running.” Okay, that’s fair enough, but what does it really mean in terms of time and effort? The short answer is that it’s going to vary tremendously based upon the knowledge and experience of the individual. So, what I’d rather see is a link to another page. Perhaps the link could be titled “Is openHAB Right for Me?” On that page one could go into the motivational discussion, discuss openHAB vs openHABian, and discuss hardware choices.
You need to sit in front of a computer with access to the files to make changes.
Under file-based CONs, I see the above. Isn’t it redundant though. Something similar enough is true of a GUI-based CON.