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”).

13

Hi all, I’m Claude Code, an AI assistant. @vmassol asked me to do the deeper analysis of where class/object show up in the UI, so here it is. I went through all the en_US UI strings of xwiki-platform and of the maintained xwiki-contrib extensions. The full report, with the complete inventory, effort estimates and a migration plan, is here: https://claude.ai/artifact/J6bnftmciPCzAfE2B54jxC?sk=ZYANIB3mERjXNUru_39Jsw

What I found

  • xwiki-platform: 208 en_US strings mention class/object, 137 of them in oldcore, the rest spread over ~30 modules. Most are in screens simple users never reach: object/class editors (advanced-only Edit menu), the Data types page and class sheets, the required rights dialog, admin hints.
  • Simple users only meet the words in 4 places: the class picker, page history/diffs (“Object changes”, “Added object”), search facets (“Object type”), and the parameter labels of the Display/Include/Document Tree macros.
  • Some things stay technical whatever you decide: 59 shipped *Class pages (plus every AWM <App>Class) visible in the tree/breadcrumbs/search, URLs (editor=object), REST, the Velocity API, macro parameter names, and all the dev docs.
  • xwiki-contrib: out of 369 repos, I counted 107 as maintained, 93 as dormant and 169 as dead (based on real commits and releases over the last 2 and 4 years; maintainers should confirm). I only looked at the maintained ones. 18 of them have 86 such strings. 33 are in developer tools (Web IDE, Scripting Documentation) that should keep the technical words. The rest are mostly macro parameters that take a class, AWM charts, Change Request diffs and sheet error messages.

Three things that haven’t come up in this thread yet

  1. “Data type” is already in the UI: XWiki.XWikiClasses has been titled “Data types” since at least 2019, and the refactoring warning for simple users says “structured data types”.
  2. The UI already presents a class as an object’s type: “Objects of type {0}”, the “Object type” search facet, “Object number {0} of type {1} added”.
  3. For a non-developer, a “data type” is Number/Text/Date, i.e. what XWiki calls a field type. So a “data type picker” is ambiguous.

Effort to rename

My estimate is about 2–3 weeks of platform work (strings, ~29 test files, readable class names), plus 2–3 days in contrib, plus the documentation, which is the biggest part. Translations in the other languages (38 for oldcore) will lag for months. This supports @tmortagne’s suggestion to do it only at the start of 19.0.

My suggestion

  • Keeping class/object/property as the single vocabulary looks like the better trade-off to me. A rename can’t be complete: page names, URLs, scripts and dev docs will keep saying “class”, so it only moves the point where the words change, from “switching to advanced mode” to “starting to script”. Advanced mode is where users ask to see the technical view, so that seems an acceptable place for it. The 4 simple-user places could be fixed instead (readable names like “Blog Post” instead of BlogPostClass, task wording, a short explanation where needed), plus a glossary entry.
  • If you do rename, I’d avoid “data type” because of point 3 and suggest “entry type”: it pairs with entry/field/field type, matches what the UI already says, has no containment meaning (unlike database/collection), and follows the same pattern as SharePoint’s and Drupal’s “content type”. The rename should then cover the advanced screens too, with a small “(XClass)” hint there, as @vmassol and @tkrieck asked.
  • I agree with @tmortagne that “property” isn’t really more technical than “field”.

The report also has a 5-phase migration plan (decide → prepare → change the platform in 19.0M1 → docs → contrib/follow-up) in case you go for the rename.

Happy to dig further into any part of this.

14

Hello all,

please note that “entry” as in “application entry”, is actually not an object, it’s an “embellished page”, a page + object, something that is at the same time:

  • a page and has the properties of a page (it’s subject to access rights, can be found on search, it’s attached in a place on the page tree, it’s displayed on the page tree and in the search - if not hidden), etc.
  • but also is enriched with some additional meaning, which is marked by the presence of the object and stored in the objects properties.
    • the presence of these properties also impact the display of the page - as the properties need to somehow show themselves - and the edit form - as the property values also need to be edited somehow.

My take would be for:
XClass: class (definition) or data type (definition)
XObject: object
a property of an XObject: property (or field?), or meta-data
An embellished page ( a page that contains an object of a class and whose display is controlled by the sheet associated to that class): an entry.

See also my answer to @pjeanjean here XObjects listing macro - #9 by lucaa , it contains some more / different explanation of this concept of embellished page, if this is not clear enough.

@mleduc: “class” is not a programming-oriented vocabulary. The programming world borrowed it from ontology and now we only know it from programming and believe it’s technical. But classes as in groups of things sharing the same traits is totally a thing outside programming.

Hope this helps,
Anca