Beginner's Guide for Topic Creation

Setup, Configuration and Use Beginners
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.

29

Alternatively the VS plugin…

Alternatively ip:9091 frontend

30

Agreed!
@ThomDietrich, I will do it this evening! Thanks!

31

Screenshot_7

32

image
Indent preformatted text by 4 spaces

No syntax highlighting

Hover over the icon and it will tell you what the icon represents. Below is the icon, what the hover text says, and what it drops into your posting. If you just type in the “what it drops into posting” you do not need to use the icons.

image
openHAB *.items code fences

```csv
your items code goes here
```

image
openHAB *.rules code fences

```php
your rules code goes here
```

image
openHAB *.sitemap code fences

```php
your sitemap code goes here
```

image
JavaScript code fences

```javascript
your javascript code goes here
```

image
generic code fences

```   
your generic code goes here
```
1 Like
33

Done. I added ONLY what is beneath the header “Topic Template” on that post - I hope this is what you expected?

1 Like