search

openhab / website

This repository contains the final artifacts from which the project website is served.
https://www.openhab.org/
20 stars 47 forks source link

[RFC] Add New User Guide to Homepage #422

Open egoist6 opened 9 months ago

egoist6 commented 9 months ago

One of the outcomes of 2 very intense discussions here and here is the lack of guidance for new user who either have limited technical knowledge or do not want to study several sections in our documentation and will need a lot of time to read through all important pages. I’d like to add a new section on our homepage (text, graphics) and link to the guide. By intention I do not want to use our documentation for this guide as we do not want to confront new (unexperienced) users with our rich and detailed documentation. This guide will cover all steps from downloading to creating a first easy rule in a very easy and compressed way with the aim to show how easy it is to get up and running with openHAB.

This opening PR is a RFC where I want to get in contact with you and discuss this before I start putting work in this. Maybe you also have some tips for me how to do the changes here as I am not familiar with Vuepress and editing md files. I will do my best but you probably need to do some layouting stuff to make it look good. Thanks, Oliver

kaikreuzer commented 5 months ago

I am fine with adding a "quick start" guide to the website, although it will be more difficult to maintain than on the documentation website and we also won't have versioning of it. Wrt technical question on vue.js, I guess @ghys is the best to comment.

ghys commented 5 months ago

I see where you're going from but we'll need to define that properly i.e. if you want some interactive thing to get up and started with openHAB on the homepage, that's great but there's already a Getting Started Tutorial (written mostly by @rkoshak) so what do you see it solving that the tutorial doesn't? I think you and @rkoshak could work together to figure out what's missing. If you could give some examples (similar projects' websites) of what you want to achieve then we could see how we could do it.

As for the technical side, I think we ought to upgrade VuePress eventually (or migrate to VitePress), and even overhaul the home page (at least) in the process, so maybe it would be wise to settle on this before we endeavor anything else with the current website.

I'll add that openHAB.org is one of the few websites where you can "test the product" right on the home page:

image

rkoshak commented 5 months ago

This is what the Getting Started Guide is supposed to do so whatever is being proposed here is essentially a replacement/reworking of Getting Started.

I'm not against a complete overhaul of Getting Started by any means but I am not in favor of yet another guide. That would be more confusing than helpful.

Also don't forget the new help tutorials and such added to the developer sidebar.

Ultimately, the challenge is forever going to be presenting enough detail to actually use OH without presenting too much. Maybe Getting Started presents too much, but it's hard to draw a line.

stefan-hoehn commented 4 months ago

What is the current state of the discussion?

egoist6 commented 4 months ago

Hi Stefan, 80% of the work was done (incl. feedback from Rich), when changes to the MainUI setup wizard came up plus the latest change of Suggestion Finder. I need to redo most of the user guide which will take some time. But I am still on it.