Extend HABPanel documentation

[kubawolanin]

This post was a reason to submit this issue.
We need a good documentation for HABPanel functionality.
Right now it's seen as a single page in our docs so I wonder if we can divide it into sections or pages? I've seen some README pages having Table of Content, so maybe this is a way to go.
Pinging @ThomDietrich for awareness :)

I'd see the following sections to be described:

• Introduction
• Dashboards Appearance?
  • Layout
  • Theming
• Widgets
  • Built-in widgets
  • Custom widgets
• Data storage difference between local and permanent storage
• Speech & Audio
  • Spoken feedback
  • Speech recognition
• Examples maybe demo dashboards available to download?

I'm willing to write about Speech and Audio for now! :)
Cheers

[ghys]

Yes, we discussed this last week in another thread, but the documentation should now be brought up to par, I have every intention of doing so in the upcoming weeks.
I like your proposal!

[ThomDietrich]

Just for reference: https://github.com/openhab/openhab-docs/pull/253/files/7f15dbdaac54b469912135edb3a8b4da801c8e08#diff-e7268aed15098f8d1f67447185bcb977

Good luck!! ;)

[ThomDietrich]

@kubawolanin @ghys how would you like to present this content? I think extending one page is a good approach, see sitemaps as a similar example.
However this is of course totally up to you! Do however you feel it fits best into docs.

[ghys]

@ThomDietrich @kubawolanin I think the one page approach is fine, but I have another proposal I'd like to share:

• the current page stays and is extended with an extensive description of the major end user features: concepts, dashboard design, description of the standard widgets and their settings, a functional description of custom widgets, storage, audio, etc.
• another page (perhaps in the Developer Guide section? where though?) centered around the template system for developing new widgets - there's a lot to write about in this area which is probably for more advanced users: it could contain a tutorial (probably a rewrite of this), what's exactly available for use, links to important pages in AngularJS docs, some tips & tricks, a few nice examples gathered from the forum...
  A link to this "develop HABPanel templates" page to this would be provided in the relevant sections (Template widget, custom widgets) of the first page.

On top of that I think a quick walkthrough in the Beginner tutorial would be a good thing (since HABPanel is installed by default with all packages but one, new users are likely to want to learn about it), I would put it below "Creating a sitemap" or maybe "Working with rules" to be consistent with the user story.

What do you think?

[ghys]

demo dashboards available to download?

This demo panel config is now automatically imported and set as default when installing the demo package, and contrary to demo.openhab.org editing is allowed for users to play with.

[kubawolanin]

What do you think?

I think that it all depends on actual content we'll produce :). Two-page approach is more future-proof and leaves us a room for further docs.
But looking at current state of User Interfaces chapter I feel that we should start with putting it on one page with descriptive ToC, as it'd be easier to find all necessary content + more straightforward navigation through the content.

[ghys]

Update on this front!
See #159 and https://github.com/ghys/habpanel/blob/documentation/doc/index.md.
I plan on adding descriptions of the standard widgets configuration settings, and the chapter on developing templates & custom widgets later.

Feedback appreciated 😄

[ghys]

The documentation is being moved to the openhab-docs repo, see openhab/openhab-docs#372 - closing this issue.