added recommendations which interfaces to use (#757)

* added recommendations which interfaces to use 

Signed-off-by: Markus Storm markus.storm@gmx.net (github: mstormi)

* Beautification

Signed-off-by: Markus Storm markus.storm@gmx.net (github: mstormi)

* Confectrician's review

* linebreak removed

* addons link corrected

* typo

* Reworked recommendations table

* minor recommendation table change

* VS code extensions for syntax checking of items and sitemaps

* addons link corrected

* minor wording changes

* clarify recommendations

incorporated 5iver's comments
added recommendation column
wording changed to clarify conflict files vs. UI

* simplified comments in table

* typo

* changed recommendation on addons

* improved column naming

* beautification

* fixed links

* removed include directive

* typo

* most OH1 bindings require config in *.cfg

* Added homebuilder to comparison

* small enhancement on Homebuilder

* Update index.md

configuration/index.md

@@ -3,8 +3,6 @@ layout: documentation
 title: Configuration
 ---
 
-{% include base.html %}
-
 # Configuration of your Smart Home
 
 openHAB is the center of your home automation.
@@ -14,7 +12,7 @@ openHAB is a system installed and executed by you, **running independently** fro
 You as the end-user have the **full control** over every aspect of your smart home.
 
 Every device connected to openHAB is functionally and logically different.
-In order to represent all of these, openHAB defines the following few base components:
+In order to represent all of these, openHAB defines the following base components:
 
 - [Add-ons](addons.html) - The numerous Add-ons to communicate with your devices
 - [Things](things.html) - Your devices represented in openHAB
@@ -24,17 +22,18 @@ In order to represent all of these, openHAB defines the following few base compo
 - [Transformations](transform.html) - Helper functions to transform your data
 - [Persistence](persistence.html) - Services to store data over time
 - [Rules](rules-dsl.html) - Automation logic, the "smart" in your Smart Home!
-- [JSR223 Scripting](jsr223.html) - Define rules and other runtime objects using [Javascript](http://openjdk.java.net/projects/nashorn/), [Jython](http://www.jython.org) or [Groovy](http://www.groovy-lang.org/).
+- [JSR223 Scripting](jsr223.html) - Define rules and other runtime objects using [Javascript](http://openjdk.java.net/projects/nashorn/), [Jython](http://www.jython.org) or [Groovy](http://www.groovy-lang.org/)
 
 The individual articles hold all details needed to understand the concepts behind these building bricks for your Smart Home.
-For more details on the base concept behind openHAB, please visit the [Concepts Overview page]({{base}}/concepts/index.html).
+For more details on the base concept behind openHAB, please visit the [Concepts Overview page](/docs/concepts/index.html).
 
 ## Versatility
 
 openHAB provides different user interfaces to modify settings, manage your things and items, build rules and access the sitemap results.
-Every interface has it's own strong points.
+HABmin provides a set of features to now overlap with Paper UI (which came later).
-
+Every interface still has its own strong points.
-### Comparison
+The following table shows what the user interfaces can be used for.
+For a recommendation to new users which one(s) to use, see the section below. "*" means recommended.
 
 <table class="centered highlight">
   <thead>
@@ -43,7 +42,9 @@ Every interface has it's own strong points.
       <th data-field="files">Textual Configuration</th>
       <th data-field="paperui">Paper UI</th>
       <th data-field="habmin">HABmin</th>
+      <th data-field="homebuilder">Homebuilder</th>
       <th data-field="karaf">Console</th>
+      <th data-field="recommendation">Recommendation</th>
     </tr>
   </thead>
 
@@ -51,37 +52,47 @@ Every interface has it's own strong points.
     <tr>
       <td>Auto-Discover Things and Items</td>
       <td>❌</td>
+      <td>✔️*</td>
+      <td>✔️*</td>
+      <td>❌</td>
       <td>✔️</td>
-      <td>✔️</td>
+      <td>Paper UI or HABmin<br/>Do not autocreate Items</td>
-      <td>✔️</td>
     </tr>
     <tr>
-      <td>Define Things</td>
+      <td>Define and manage Things</td>
-      <td>✔️</td>
+      <td>(✔️)<br/>not for all bindings</td>
-      <td>✔️</td>
+      <td>✔️*</td>
-      <td>✔️</td>
+      <td>✔️*</td>
+      <td>❌</td>
       <td>✔️</td>
+      <td>Paper UI or HABmin</td>
     </tr>
     <tr>
-      <td>Define Items</td>
+      <td>Define and manage Items</td>
-      <td>✔️</td>
+      <td>✔️*</td>
-      <td>✔️</td>
+      <td>✔️</td>
+      <td>❌</td>
       <td>✔️</td>
       <td>✔️</td>
+      <td>items/*.items files</td>
     </tr>
     <tr>
       <td>Define Groups</td>
+      <td>✔️*</td>
+      <td>✔️</td>
+      <td>❌</td>
       <td>✔️</td>
       <td>✔️</td>
-      <td>✔️</td>
+      <td>items/*.items files</td>
-      <td>✔️</td>
     </tr>
     <tr>
       <td>Define Sitemaps</td>
-      <td>✔️</td>
+      <td>✔️*</td>
       <td>❌</td>
       <td>❌</td>
+      <td>✔️*</td>
       <td>❌</td>
+      <td>Homebuilder or sitemaps/*.sitemap files</td>
     </tr>
     <tr>
       <td>Define Transformations</td>
@@ -89,6 +100,8 @@ Every interface has it's own strong points.
       <td>❌</td>
       <td>❌</td>
       <td>❌</td>
+      <td>❌</td>
+      <td>transform/*.map files</td>
     </tr>
     <tr>
       <td>Define Persistence</td>
@@ -96,46 +109,79 @@ Every interface has it's own strong points.
       <td>❌</td>
       <td>❌</td>
       <td>❌</td>
+      <td>❌</td>
+      <td>persistence/*.persist files</td>
     </tr>
     <tr>
       <td>Define Rules</td>
-      <td>✔️</td>
+      <td>✔️*</td>
-      <td>✔️<br />(Experimental)</td>
+      <td>(❌)<br/>only for the experimental rules engine</td>
-      <td>✔️<br />(Graphical)</td>
+      <td>(❌)<br/>not functional</td>
       <td>❌</td>
+      <td>❌</td>
+      <td>rules/*.rules files</td>
     </tr>
     <tr>
       <td>Manage Z-Wave Devices</td>
-      <td>✔️<br />(Not&nbsp;Recommended)</td>
-      <td>✔️<br />(Limited)</td>
-      <td>✔️</td>
       <td>❌</td>
+      <td>✔️</td>
+      <td>✔️*</td>
+      <td>❌</td>
+      <td>❌</td>
+      <td>HABmin</td>
     </tr>
     <tr>
-      <td>Modify openHAB Settings</td>
+      <td>Modify openHAB Settings/Services</td>
-      <td>✔️</td>
       <td>✔️</td>
+      <td>✔️*</td>
       <td>✔️</td>
+      <td>❌</td>
       <td>✔️</td>
+      <td>Paper UI</td>
     </tr>
     <tr>
       <td>Install Add-ons</td>
-      <td>✔️</td>
+      <td>✔️*<br/>mandatory for most OH1 bindings</td>
+      <td>✔️*</td>
       <td>✔️</td>
       <td>❌</td>
       <td>✔️</td>
+      <td>services/addons.cfg or Paper UI<br/>services/*.cfg for OH1 bindings</td>
     </tr>
   </tbody>
 </table>
 
-{: #text-vs-ui}
 ### Textual vs. Graphical Configuration
 
-With openHAB 1.x the smart home configuration was done via configuration files only.
+In openHAB 1.x, smart home configuration was done via configuration files only.
-One of the most visible additions to openHAB 2 is the administrative web interface Paper UI.
+openHAB 2 added the administrative web interface "Paper UI".
+It allows for configuration of the base system and setup of openHAB 2 add-ons.
+Please be aware that not every addon/binding of openHAB version 1.x has been updated to version 2 and thus to work with Paper UI.
+You can still run these but you need to use file configuration for them.
 
-Things and Items can either be defined and managed in configuration files or handled by Paper UI in a [system-side database]({{base}}/administration/jsondb.html).
+Things and Items can either be defined and managed in configuration files or handled by Paper UI in a [system-side database](/docs/administration/jsondb.html).
+For Things and Items, both methods can be used **side-by-side**, e.g. a Thing can be discovered and created by Paper UI and the Items that link to that very same Thing (that Thing's Channels, actually) can be manually defined in a `.items` configuration file. 
+Configuration done in files will be used (and they become visible and even changeable in Paper UI) if no Thing/Item of the same name was already created in PaperUI, but you can NOT create a Thing or Item using files and then use Paper UI to redefine or change it. Those changes will not be accepted.
+Configuration done in PaperUI will be used and permanently stored in the internal database if no Thing/Item of the same name already exists in files, but those additions or changes will not be copied into any `.things` file.
+openHAB settings as defined in `services/addons.cfg` and `services/runtime.cfg` will override any settings made in PaperUI's Configuration/System pane.
 
-Both methods can be used **side-by-side or even mixed**, e.g. a Thing is discovered by Paper UI and linked Items are defined in a `.items` configuration file.
+## Recommendations for New Users
 
-Configuration done in files will be synced to the database but configuration done in the database will not be written to files.
+All interface options are supposed to work, still some of the more advanced settings might work better in one or the other setup.
+You have the full freedom of choice. On the other hand, this can be very confusing at times, particularly for new users.
+To help starters in narrowing down choices, here is some guidance that might also help to avoid some future pitfalls:
+
+* Use Paper UI to setup and maintain the openHAB base system. Use it to define _which_ addons and bindings you want to install and to assign _basic, static_ configuration (such as the device name of a ZWave stick or the IP address of a KNX gateway).
+* Create items and groups in `.items` files. You can also use [Homebuilder]{homebuilder.html} to create your initial set of [.items](items.html) and [sitemap](sitemaps.html) files. It is a separate GUI tool to assist you with the creation of these components to represent your home, however it does not provide GUI support for all the functionality that is available for use in .items, so it is not recommended to keep using Homebuilder to maintain these files.
+* Use Paper UI to manage configuration of each and every openHAB 2 add-on and binding.
+* Use file configuration or Paper UI to manage configuration of openHAB 1 add-ons and bindings.
+* Use Paper UI or habmin to manage ZWave things, but use configuration files to manage ZWave items.<br/>
+  There is a rationale to this: to use a GUI is comfortable for one-time actions, but you get any repetitive task easier and faster done using a text editor (e.g. search-and-replace names and parameters).
+  _Things_ can be autodiscovered so you don't have to enter all of them manually. Once initially configured, their configuration is not changing much over time.
+  On the other hand, you will keep changing _items_ rather often.
+  If you are new to openHAB, you will e.g. keep changing all of your item names as you keep learning what is a naming scheme you like best to work with in your rules. And once you are a pro, you will want to keep using files anyway. You can configure items via Paper UI, too, and you can use HABmin as well for both but remember once you use files, this will override any UI-made changes on next openHAB startup.
+* Use the editor of your choice to edit [sitemaps](sitemaps.html). Start with the demo sitemap as a template.
+* Use VS code extensions to [edit rules, items and sitemap files](editors.html).
+  You can also use any text editor, but VS code extensions will help you by highlighting and cross-checking the file syntax.
+  Either way, be aware that any 'save' results in openHAB reloading the rules file.
+  This can take more than a minute on a slow box such as a Raspberry Pi, so better to not edit rules files in place.