Proposal for Structuring Cristal's Onboarding Process

tkrieck · April 28, 2025, 1:43pm

Hello everyone,

I would like to present a proposal for structuring Cristal’s onboarding process. Drawing inspiration from the approach used in XWiki, I suggest dividing the onboarding into two distinct flows:

First-Time Run: Intended for administrators to configure the application.
First-Time Use: Designed to guide end users through Cristal’s main features.

In this post, I will outline both flows and provide an overview of the proposed structure.

The overall onboarding flow is represented below:

First-Time Run (Administrator Setup)

This flow is aimed at administrators during the initial setup of Cristal. The suggested steps include:

Backend Selection: Choosing the backend service to be used.
Backend Configuration: Setting up the selected backend with the necessary parameters.
Design System Selection: Selecting the design system to be applied.
Basic Wiki Settings: Setting up initial wiki details such as the name, logo, and potentially other configurations.

Layout Proposal

The initial configuration flow would follow a simple structure:

A dialog or basic page (to be decided during implementation).
A Hero section introducing each step with basic instructions.
A form section containing the necessary fields, varying significantly by step.
Navigation buttons for user progression.

Step 1: Backend Selection

The first step combines a welcome message with backend selection.

The available backend options may vary depending on Cristal’s deployment environment (for example, “Local Folder” may not always be present).

Step 2: Backend Configuration

Based on the chosen backend, a tailored configuration screen will appear.
Some configurations may require more extensive screens or even multiple sub-steps.

Example: XWiki Backend

Example: Nextcloud Backend

Step 3: Design System Selection

If multiple design systems are available, users will be prompted to select one. If only one design system is detected, this step will be skipped.
It’s important to include visual elements (such as logos) to enhance the selection experience.

Example with Shoelace selected:

Step 4: Final Configuration

In this final step, users will input key details about the wiki, such as logo and name. We could also consider adding basic user creation at this stage.

After completing this initial setup, users will be transitioned directly into the First-Time Use flow within the newly configured wiki.

First-Time Use (End User Tour)

After setup, end users will be welcomed with a short guided tour of Cristal. The goals for this tour are:

Provide a quick, clear orientation, similar to XWiki Standard.
Highlight major areas of the UI.
Introduce key concepts succinctly.
Keep the entire experience under one minute.

Layout Proposal

The tour will follow a simple layout with familiar elements (similar to XWiki Standard), and will include a step indicator for better clarity.

basic layout (1)

Proposed Tour Steps

The key areas introduced during the tour include:

Main Sidebar

Document Header

Action Bar

Document Information Tabs

user - document information

Contextual Onboarding

Cristal’s onboarding can dynamically introduce new steps based on user actions. For example:

After logging in, users may be introduced to the Edit button.

After clicking “Edit”, users can be guided to the user list functionality, particularly useful in collaborative environments.

I look forward to hearing your feedback and suggestions to refine and improve this proposal.
Thank you all for your attention!

mleduc · April 28, 2025, 3:43pm

Thanks for working on this!

Just to be sure we are on the same line, the configuration is actually more complex than that and is likely to be even more complex in the future.
For instance, your current example is missing:

editor choice
the real-time server configuration
the authentication bridge configuration that we need for Nextcloud or GitHub

And can guess more will happen in the future, some of the being optional or backend type specific.

WDYT of also adding an (optional?) description, as an additional hint of what’s the backend for end users.

Some things I don’t see on this proposal.
You presented the creation of new configurations, but what about seeing existing ones, editing, or removing them for admins?
I think discussion on what users can configuration needs to be considered for this proposal (cc @pjeanjean who is currently working on this topic).

tkrieck · April 28, 2025, 4:00pm

I’m aware . The intention here is to establish some patterns that we can reuse in the steps we deem necessary. The main point I guess is, whenever possible, we set some sensible defaults to facilitate setting everything up.

I’m not sure if I follow, you mean as a reminder of what back end was selected in step 1?

I see this as a config page in the Administration section, not as an onboarding step. Both can look alike or even be the same page, but the moment each is accessed will be different. Onboarding for new wikis, or new instances and Admin page for established ones.

pjeanjean · April 28, 2025, 4:19pm

Thanks for working on this! This is looking good and streamlined already, which is exactly what we want.

Regarding backend configurations:

This makes sense to me, but we probably need to discuss this a bit more. In particular, right now we have default configurations shipped with Cristal (XWiki’s demo instance, and FileSystem with a default storage location for Electron), and we can manage that a few different ways: we could continue including them (to be optionally removable later), get rid of them entirely (but we lose the “fast demo set-up” we have right now), or manage them in the onboarding, which I think was Manuel’s point (could be via flavors, or we could ask the admin early if they want a demo instance or a production instance).

Regarding user configurations: there will be some “global” options that would benefit from being separated from the rest of the configurations. For example, after an admin does their onboarding with an initial backend, and they set-up an authentication bridge and a realtime server, they would need to allow or disallow the use of these services to users making their custom configurations. Or at least be aware that these specific parameters could be re-used for other configurations made by other users.

mleduc · April 29, 2025, 9:02am

What is selected in step one is a kind of backend.
But, we can easily imagine a Cristal instance being configured with two configs with the same kind of backend.
For instance:

Config A: XWiki backend, pointing to https://xwiki.org/
Config B: XWiki backend, pointing to another server running xwiki on another domain
Config C: File System backend, pointing to $HOME/personalNotes
Config D: File System backend, pointing to $HOME/workNotes

When listing all available configurations, if the list if:

XWiki
XWiki
File System
File System

It will not be clear. That’s why I’m proposing to allow defining a name and a description for each configuration.

A minimal definition of who can do what is:

server admin:
- can upgrade versions
- can add new dependencies (e.g., install the code to support a new kind of backend)
- can define global configurations
- can allow/disallow some settings for users
end-users:
- can access the list of available configurations
- can define their personal configurations (if allowed by admins)

tkrieck · April 29, 2025, 11:41am

Ah, that makes sense. Well the layout itself can accomodate that kind of information as it is already composed of a title and description. So I would add a “type” field to make it clear, besides the icon, what kind of backend each access means. See the image below.

Now, regarding making one of these configurations, perhaps the onboarding can start a process in which the admin users will config as many backends as they wish and what the default config should be. Here we could point to a demo config as well, for testing purposes.