End-users XClass and XObject vocabulary

Development
1

Hello all,

In this proposal I’d like to explore the vocabulary to use when using the concepts of XClass and XObject in the context of non-technical users.

The main use case is my current design work to improve the usability of the class picker for non-technical users. And I believe that using the class/object vocabulary is too technical.

To be clear, I am not proposing to change anything:

  • At the API level
  • In UIs meant to be used only by advanced users

This is equivalent to the way we use “page” in the UI and “document” in the code.

Related discussions

Current state

App Within Minute (AWM)

  • Class is mapped to structure (e.g., Step 2 - Structure your data)
  • Object is mapped to entries (e.g., Application entries are wiki pages that contain structured data.)
  • Property is mapped to field

Note that we also have an AWM revamp discussion and proposal by @amilica introducing a new vocabulary.

  • Class is mapped to data
  • Object is mapped to record
  • Property is mapped to field, a field has a type

Live Data (LD)

  • Class is not explicitly mentioned
  • Object is mapped to entry
  • Property is mapped to property

Class Sheet

Directly mention class, object and property.

Object editor

Directly mention class, object and property.

Proposals

I tend to think that “entry” for object and “field” for property are already uniformly used and should stay as is. I’ll only discuss the class vocabulary below

Option 1 - keep using class

Pros:

  • Nothing to change

Cons:

  • We keep a programming-oriented and technical vocabulary

Option 2 - structure

Pros:

  • Already part of AWM vocabulary.

Cons:

  • A structure picker feels odds

Option 3 - data type

Pros:

  • A data type picker seems ok to me

Cons:

  • Required to uniformize the UI globally.

cc @tkrieck and @amilica to make sure this does not conflict with Revamping AWM ( App Within Minutes)

Option 4 - database

Pros:

  • Matching the vocabulary of Confluence and Notion users might be familiar with

Cons:

  • The database word kind convey a notion of containment of the objects. This is not true and not something we want, the locations of the class does not say anything about the location of the objects

Alternative vocabulary with the same cons:

  • collection

Questions

Q1 - Do we want to uniformize, or is it ok for some extensions to use their own domain specific vocabulary?

+1, but for instance Live Data is more generic than object/class listing and can use its own vocabulary.

Q2 - Class vocabulary choice

+1 for option 3 (data type)
-1 for option 1, option 2 (structure), and option 4 (database)

Q3 - Use entry/field

+1 to keep using entry/field for object/property

Q4 - Migration

If the agreed upon vocabulary requires a change, how should we proceed?
I’m +1 to create a dedicated task and to change the vocabulary globally all at once, then use the same vocabulary for new UI elements requiring it.

Thanks for reading this far. WDYT?
cc @lucaa and @caubin

2

You meant “class” here no? since you said just above that you think “entry” is good for object just above?

3

+1 to uniformize but it has quite a few implications

+0 for option 1 (class): I know class/object is very technical but we can explain it and it might be easier to actually keep that vocabulary than changing it for something we believe will be better in terms of UX

-1 for option 2 (structure) and option 4 (database)

+0 for option 3 (data type)

+1 to use entry but note that we do use object too in the UI (e.g. we have an object editor)

So there’s plenty of different things to consider IMO. There’s all the mention of it in the UI, but we need to pay attention to the translations too: it won’t be easy to change all that consistently. Then there’s the documentation: class and objects are mentioned in plenty of docs, snippets, tutorials etc. If we decide to change the vocabulary IMO we still need to have a clear documentation stating that there is a mapping between the new vocabulary and class/object to not loose people. Especially since we also have all our API documentations that are using this vocabulary too.

4

+1

-1 for “database” (would collide with a very different kind of “database” in the XWiki ecosystem, and it’s also not accurate at all since the class does not contain the entries), “structure” (not really less technical than object IMO, so I don’t see any value in moving to it) and yes “class” is definitely too technical for non dev users.
I’m not a huge fan of “data type” used on its own (if you don’t use “data” for objects for example) but let’s say +0 to not put -1 on all proposals :slight_smile:

What about “definition” or “entry definition” ? I know it’s not used yet, but I don’t see any reason to limit ourselves to already used but never really discussed namings if we want to try to find the right one.

+1. I don’t really have anything against this naming. Just wondering if “property” really is that much more technical than “field”, at least enough to justify the API vs UI difference and all the work.

It’s a huge work. But sure, ideally, it’s always nicer to change it all at once, I’m just wondering if it’s realistic. I guess I would do such a thing only in 19.0.0 and have the whole cycle to fix all the breakages and inconsistencies.

5

Thanks for catching this, I’ve fixed it.

As I said in my initial post, I’m not proposing to change the working for UI meant only for advanced users. I believe the object editor fits in this category and should keep using the object/class vocabulary.

That’s an interesting option. I would leave us a full cycle to solve the inconsistency instead of having to rush it.
We could even stay with the old wording for the new UI elements I plan to integrate, and see how early users reacts. Though this would mean a whole cycle with the old vocabulary if we introduced those new UI elements in the 18.x cycle.

6

I feel this requires a much deeper analysis of all the places that currently surface in the UI.

I’m not sure I agree with this. A simple user switching to advanced user will suddetly see different vocabulary and will be lost and have a WTF effect.

7

Hi Manuel, thanks for the proposal.

+1

+1 for data type also

+1

+1 also

We can always rework the wording on our proposals easily. The main point being reduce technical term exposure to regular end-users (not advanced users).

I agree, ideally we want the same terminology regardless of type of user. If possible, it’d be intersting to show a hint only for advanced users mentioning the technical names (XObject, XClass).

Thanks again!

8

Thanks, so this goes toward waiting the start of the next cycle and do a full pass over the whole UI and documentation to make the vocabulary uniform, including for pages dedicated to advanced users (unless the technical vocabulary is necessary punctually).

I’ll try to make this discussion progress with a more exhaustive analysis of the impact of this change. Thanks all for the early feedback.

9

Thanks for the suggestion. Adding a new option for other to express their votes.

Option 5 - definition

I’m -0 for that one:

  1. A definition picker feels odd
  2. The generic term seems to be easily conflicting with other domains such as a dictionary definition
10

Thanks for proposal

Given my :plus: only here

+1

+1, although it maybe a bit difficult to translate to other languages ​​at first without extra context, as I see that such keys have already been introduced on the l10n platform.

11

Q1.
+1 to uniformize, bundled extensions in XS should all use a similar vocabulary. Worst case scenario, in discussion we can just use the name of the extension to differentiate the concepts (but ideally they’d all be working similarly from a user POV).

Q2. +0 for data type, IMO it’s the best of the new options proposed.
I have a small concern about using two words instead of one, I have a feeling that there must be some places where this will be more difficult to understand/heavy than class.
+1 to uniformize on class, it has the advantage of being mostly consistent in time (i.e. already used in a lot of places, so people that already use XWiki won’t be lost). I believe tech vocabulary is becoming more and more common, and such a frequent abstraction is easy to understand for more and more people.

Q3. +1 for entry and field. Note that “field type” would also appear in some UIs.

Q4. +1, I agree with tmortagne, catching all the fallout will probably need to be done over a whole cycle.

Thank you for starting this discussion!
Lucas C.

12

Generally a very good idea to make UI language more accessible.

In practical development context, the term “class” is closest to “object specification”, “format” or “construction plan”.

Maybe, “specification”, “format” or even “description” is good. “Definition” on the other hand is too abstract. Anything can be defined by a language that is powerful enough to define it. Objects can be interpreted as mere proxy definitions stored and used in the computer for real-world objects.

If I see right, when it comes to Live Data, a “class” becomes the table schema, since a live data table collects objects of 1 class into a table, like a database query. Therefore, another candidate as a replacement term is “schema” (which also sounds like “format”).