I am a bit hesitant whether we need those concepts page or not.
For example for rules, iMO a concepts or introduction page is required, while reference documentation is located in the docs of the individual automation add-on.
But I agree that having Concepts - Configuration might not be the best structure.
I personally tend to think of the configuration docs as reference docs for file-based docs, but there are also important information for UI-based config …
My idea would be to restructure the docs and e.g. for Items have a page, that explains Items as a concept and their properties etc., and another page that focuses on the .items file-based config.
We need to balance between consistency and legacy.
For Items it’s always been called the “name” back as far as OH 1.x. But being internally consistency is important. That’s what let’s users anticipate the correct way to do things based on what they’ve already done and avoid surprises.
If we change this to Item ID, the docs will need to be scrubbed and updated accordingly. We shouldn’t call it one thing in the UI and something else in the docs.
Then there are the rules to consider. The Item Object calls it “name”. The event Object calls it “name”. And any function call that needs the “item id” calls it the “name”.
I like the idea of changing it to “Item ID” but only if we do so comprehensively. If we just change it in the UI, we’ve just moved the original problem and not actually solved it.
That’s another but easier inconsistency to deal with. For OH purposes, there really is no difference between an ID and UID.
It’s too big a change for me to tackle at this point. So in that case, should I change the UI label back to Name or Item Name instead of Item ID (Name) whilst proceeding with the other changes, as per the table I’ve made in the PR?
In the case shown “UID” and “ID” are different things (and this is consistent with the way we have it in code): the “UID” is the “full” identifier (e.g. amazonechocontrol:account:cae6d640:refreshActivity) consisting of the thing’s UID (amazonechocontrol:account:cae6d640) and the id of the channel (refreshActivity). The UID but be unique globally, the id only within its “namespace” (refreshActivity is a valid id for more than one thing, because the unique thing UID makes the channel UID unique).
“Unique ID” is therefore a bit misleading, you can’t have two config:s transformations with the same id, but it’s perfectly fine to have a config:map transformation with the same id.
But from the end user’s perspective is there any practical difference? Is a user going to do something different with something labeled an ID from a UID? Do they need to be more or less careful?
If so that’s needs to be made clear in the UI and the docs. If not, calling them something different adds complexity and confusion.
I agree in the code there is a difference but if it’s a difference that doesn’t matter to the end users, exposing that difference to them adds complexity and confusion for no reason.
I think it’s too big a change for any one individual to tackle and it probably be something discussed among a broader set of maintainers before it’s attempted.
Ultimately we need to make it clear that it’s what is going to be called “name” everywhere else in OH. From that perspective either if these is ok, though if you choose “Item ID (Name)” this is going to be the only place where it’s call the ID.
@massi based on feedback from others, it seems that we need to keep the input field Name as is. Changing it to Item Name doesn’t make it any clearer, and adding an extra term like Name (Item ID) would actually cause confusion because now we’re introducing two “names” for the same thing when the name Item ID didn’t exist before.
How about this as a compromise:
When adding an item:
I think this is a good “compromise”, at least there is an inline that helps to understand why there is both Name and Label.
However I am more “worried” about the mess that basically every object ID in its new/editing page is labelled in a different way: Name, Identifier, Unique ID, almost every permutation!
Your table in the GitHub issue is quite impressive and tells a lot about this mess.
I am one of those convinced that OH will not survive longer if we do not make it much simpler for new users, and this mess is indeed and obstacle for new users.