I wanted to give you my take on things. I’ve been using openHAB since about two years now. So since version 2.x. Which means I’m fairly late to the party.
With openHAB being so … “open” … there cannot be one “true” way of doing things. I still want to tell you what I think is a good approach now(!) as we speak. Doesn’t mean that’s true and doesn’t mean there are better ways now or in the future. But I have had my share of good and bad experiences as a newcomer. You are asking the right questions because the UI vs. text files part is what’s most confusing. From experience advice like “you could do that or that” doesn’t help in the beginning. So I’m being black and white now, but on purpose.
Use Paper UI for binding and thing maintenance and forget about all other UIs
Paper UI is my only graphical admin interface for bindings and things. It is the most mature and I think it is safe to say that is the current de-facto standard. Use Paper UI to create all your things. I only create things textually in very rare cases. In most of those cases it is because I’m forced to declare the items manually because the (exotic or new) binding doesn’t support auto-discovery.
Forget about sitemaps
This might be very controversial. But I truly believe that sitemaps are an unnecessary extra effort. I experimented with those years ago because due to the way the documentation is written one gets the feeling that having a sitemap is mandatory. It is not. Sitemaps are the basis for all automated UIs like the iOS app. They are no doubt useful. But if you do not want to use any of those, you don’t need a sitemap. Give your items english IDs and meaningful display names in your native language. Use groups extensively to order them.
Use HABPanel as your primary UI
HABPanel is an incredibly useful, mature, flexible and stable UI-designer / UI-runtime. It is both editor and dashboard in one app. You can start editing on your iPad and continue on your Laptop and switch between editing mode and “live” mode on the fly. All changes are synced. I have only good things to say about HABPanel. My advice would be to put everything you want to see or control manually on a HABPanel. It is ideal for tablets and works on a mobile phone as well. Although not as nicely, due to limited screen real estate. Combine that dashboard approach with voice control assistants like Siri or Alexa and you have covered 99% of all daily use cases. In fact, again, a sitemap would be of no use here: The mapping for voice assistants has to be done separately.
Create your items textually and put them in one file. Group all items.
I have one .items file where I keep all of my items. Having more than one file leads to smaller files (obviously), but there is a problem: Groups. You can only assign items to groups that have been declared in the same file. This doesn’t work in practice because you loose the ability to use groups as dimensions. For example I have one “catch all” group called “House” where all items are assigned to (directly or indirectly). This is not possible if you scatter your items across files. You should use groups because they can be used in rules and for the simple reason that the current de-facto standard UI for all text file editing (Visual Studio Code) uses groups to build a tree view of your items. You can assign an item to various groups. A groups does not need to be used for controlling multiple items at once. It can exist solely to semantically group items. This is very, very handy. Which leads me to…
Use Visual Studio Code for editing items and rules
VSCode is fast, cross-platform and as it currently stands it is the most mature openHAB text file editor. Not only has it syntax highlighting, auto completion capabilities and (limited) refactoring capabilities. But it also has a sidebar where it shows the current values(!) of your items in a tree view by group. I even use it if I do not want to do any editing just to get an overview of my item’s current states. Compared to a sitemap (that gets outdated and has to be maintained) this overview is “live” and always contains all items.
Make sure you have quick and easy access to the log files at all times
This is especially true once you start writing your own rules. On a Raspberry Pi there is the log viewer which is accessible via web browser. It depends on other platforms. I’m on Mac OSX, so I just share the log file folder over the network and open the files with the text editor of my choice (capable of auto-refreshing).
Again: This is my personal best practice. It is in no way the right thing to do.
Hope that helps!