Beginner's Guide for Topic Creation

Setup, Configuration and Use Beginners
9

Not at all, it was bed time for the little one so my online time came to an end.

As am I. I still want templates. In the templates, I want links to instructions or at least instructions for how they can answer the questions in the templates. I think we are completely in agreement on this.

What I am arguing against is a template with 3-4 scenarios that requires the new user to read through a bunch of stuff to figure out which scenario applies to them, delete the rest, and then provided the asked for information. Most of the time I expect that most users will just use the first scenario every time, so why not just have one scenario and be done with it. In some cases, they may end up providing more information than we need but that really isn’t a problem as far as I’m concerned.

I think one of the keys will be providing the instructions for where/how to answer the questions inline or through links to the instructions.

I think this is addressed by the fact that when you create a new topic in the Beginner’s area the new topic gets pre-populated with the template and the user fills out the information. By having the template automatically apply they do not have to look anywhere and the mere fact that the template is there will encourage most (never all) to fill out the template as that will be easier than starting from scratch.

There is no solution that will completely solve this problem and I don’t think anyone here expects that this would solve it. But if we can easily provide some guidance to new users to help us help them perhaps we can reduce the amount of back and forth required to extract all the information we need to help the new users.

1 Like
10

Didn’t see this possibility, aggried!

11

After reading other replies, I must say that my idea based on scenarios might not work.
So, as a starting point, I think we should go with your proposed structure! I will try and post a new version today!
Who should implement the template? Any ideas?

12

@ThomDietrich I think is the designated forum guy, though Kai may need to be brought in to make the actual changes. I don’t want to bother Kai yet until we are a bit closer toa template.

13

Hello! I was summoned… reading.

3 Likes
14

Sooo great idea!

Discourse (our forum software) offers two three options I can think of:

  1. the general guidelines: https://community.openhab.org/guidelines
  2. the category “About”, e.g. About the Tutorials & Examples category
  3. the Topic Template

The first two can be modified by moderators, Topic Templates can (I don’t know why) only be modified by the Admin user (Kai).

Regarding the Topic Template: I need to warn everyone that anything added there is heavy weight. In the small text area in the bottom left you can’t see much and the fact that markdown is not interpreted doesn’t help. Look here for a bad example: https://central.owncloud.org/c/server/help

I believe the intention of @george.erhan is to add this content to “Setup, Configuration and Use”?

My suggestion would be to:

  1. In the Topic Template give a clean checklist of things a user should consider prior to posting. The whole template should span not more than 10-15 lines!
  2. Add all additional content, examples and instructions on “how to retrieve X” to the About Category article
  3. Update the guidelines if needed

The Guidelines and the About article should be the first point on the checklist.

Did I miss anything? What do you think?

15

I agree with everything but fear that putting everything in the About Category article will effectively hide that information from new users. At least we should put in the template a line saying to look to this article for instructions about how to find the relevant info.

I may be admitting too much here but I have never read the general guidlines nor the About articles for any of the categories and probably wouldn’t think to do so where I new user.

1 Like
16

like this?

me neither. However… would you read this? https://central.owncloud.org/c/server/help → New Topic

Btw. I’d love to see a short code snippet fences example at the end of template. It’s 3-4 lines and I believe this is one of the most common mistakes of users, resulting in a bad presentation of their problem.

17

Doh, you are ahead of me and I’m clearly not reading things closely today. Maybe it’s time to take a break for an hour or so.

Oh, I agree. We just need to strike a balance between being terse and easy to answer verses too wordy and complex. Either one can put us right back to playing the 20 questions game that the template is trying to solve.

I’m not sure what that balance is. Clearly, we don’t want to to go down the OwnCloud route.

1 Like
18

@george.erhan how’s your opinion about all of this? It would be incredible if you could draft the needed documents here before we can transfer them to the right places…

19

Before posting

  • Please review the Beginner’s Tutorial and User’s Guide for a solution before posting.
  • Have you looked in the forum for similar problems?
  • You should check the logs for errors. The information on how to get logs is found here
  • You should prepare for upload the relevant parts of the conf files (items, rules, sitemap, services) when dealing with textual configuration files. Use screenshots or description when using UI based configurations.
  • You are using Smarthome Designer, or the Visual Studio Code openHAB extension if textual configuration is involved in the issue. - if Smarthome Designer is not installed, you should follow these steps, or download the VS code extension from here. Load your configuration files into SmartHome Designer, to check the syntax of your configurations before posting
  • When posting, please use code fencing for the various configurations you want to post. (At the top of the editor there are the necessary tools).

Post template

  • Platform information:
    • Hardware: CPUArchitecture/RAM/storage
    • OS: what OS is used and which version
    • Java Runtime Environment: which java platform is used and what version
    • openHAB version:
  • Issue of the topic: please be detailed explaining your issue
  • Please post configurations (if applicable):
    • Items configuration related to the issue
    • Sitemap configuration related to the issue
    • Rules code related to the issue
    • Services configuration related to the issue
  • If logs where generated please post these here using code fences:
3 Likes
20

This looks good, especially if the pop-up is possible. I think that will all depend on whether Discourse supports that.

I’ve mainly some word choice comments that can be accepted or ignored as the main concept and over all structure looks good to me.

Many of the problems you have can probably have a solution here.

Please review the Beginner’s Tutorial and User’s Guide for a solution before posting

Have you looked in the forum for similar problems?

Move this to be the second bullet point.

You should prepare for upload the relevant parts of the conf files (items, rules, sitemap, services) when dealing with textual configuration files.

Identify and gather relevant parts of configuration files for posting. Use screenshots or description when using UI based configurations.

You are using Smarthome Designer if textual configuration is involved in the issue. - if Smarthome Designer is not installed, you should follow these steps.

If you are seeing parsing errors or “not found” errors in your logs load your configuration files into SmartHome Designer to check the syntax of your configurations before posting

If possible it would be great to include a screenshot of the buttons. Also, it is worth noting that these buttons do not appear when posting from the mobile version of the forum.

Hardware: CPU/RAM/storage

I would strike the CPU/RAMP/storage part. It is really sufficient if they just say "Raspberry Pi 3, VM on ESXi, old laptop, etc.). I can’t think of the last time knowing what the GHz of the CPU help me solve a user’s problem.

Java platform used: which java platform is used and what version

I think we should use the proper term here: Jave Runtime Environment

One other problem we may run into is for new users they have a character limit for new posts. If we start to run into problems where what we are asking for causes new users to break that limit regularly we may have to cut back on the amount of information requested.

21

Agreed!

Agreed!

I will add this to the existing text.

I think only this should be added, not because you are wrong, but it might become too lengthy.

I agree, but let’s first find out from @ThomDietrich if the popup thing is in any way possible (if it accepts images, I would go for it). The mobile version shows only some of the buttons. I wonder if a new user would use the mobile version when dealing with items files, screenshots, etc.

I meant CPU architecture, not clock speed! Is the term architecture acceptable for our goal?

Agreed!

This is indeed a problem, let’s wait for Thom’s answer!
LATER EDIT: I edited according to our discussion! Thank you for you observations!

22

Yes, that’s perfect. When I see CPU I think speed, not arch.

Great work. I hope we can get this set up soon.

1 Like
23

Hey guys!
Thanks @george.erhan and @rlkoshak for the lists, they both look quite good!
I checked with discourse but I couldn’t find any indication that showing something in the preview area is possible. I wonder if that should be feature-requested.
Anyhow, we can only copy this list into the “About category” article or we have to combine both of the lists into a single template, which is as we discussed not a good idea… I would vote for the first solution. Wdyt?

24

I agree, the first solution would be better.

25

Hi,

I also looked in to Discourse and I think for now it’s hard (not impossible) and time consuming to setup the preview to display the information we want. So yes, the first solution should be a go for now.
Thanks for the support!

26

@ThomDietrich
Reviving this topic after seeing this:
Starting openHAB as a Service
I am sure we will not avoid ALL the cases, but at least may be a start!

1 Like
27

Sorry for the delay. The last thing that’s needed is: We need to turn the first part of Beginner’s Guide for Topic Creation into a single posting, with a few headlines or such. Would you please do so? See as an example: About the Tutorials & Examples category

28

@george.erhan ping :slight_smile:

The rest of the task needs to be done by @Kai: Please add the post template from here as the template for the Setup, Configuration and Use category.