Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[UX] Add first-run onboarding for users without ontology expertise

Open
  • Is something wrong?
#313 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
62/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
rust
Domain
frontend

Research direction

Start from the empty graph view that currently shows the text instruction to configure a model and upload documents, and from the main navigation listing Graph, Search, Chat, Library, Review, Ontology, Mappings, Settings. Build a dismissible, reopenable checklist whose completion state persists, then connect it to the empty states of Graph, Library, Search and Chat with role-aware actions for administrators versus members. Keep English and Chinese copy in sync, and cover the key states (unconfigured, empty, processing, failed, ready) plus admin/member paths with tests; done means the acceptance criteria checkboxes all pass.

Written by the indexing model from the issue text.

Description

Problem

Utopia does not currently provide a clear first-run journey for new users.

After registration, users are taken directly to an empty graph. The page mentions configuring a model and uploading documents, but it does not explain:

  • what to do first;
  • what happens after a document is uploaded;
  • when search and chat become available;
  • what the ontology does in Utopia;
  • whether the ontology must be understood or edited before the product can be used.

The main navigation exposes Graph, Search, Chat, Library, Review, Ontology, Mappings, and Settings at the same level, without showing the order in which a new user should approach them.

As a result, users may successfully deploy Utopia but still fail to reach their first useful result. The product also appears to require ontology expertise even though its default ontology and automatic extension mechanisms are intended to let users get started without it.

Current experience

A typical first-run flow is:

  1. Register an account.
  2. Land on an empty graph.
  3. See a text instruction to configure a model and upload documents.
  4. Find the model settings and Library without direct guidance.
  5. Upload a document without knowing what processing to expect or where the result will appear.
  6. Encounter concepts such as classes, properties, signatures, and axioms without an introductory mental model.

The README covers deployment and model configuration, but does not provide an end-to-end product walkthrough.

Expected outcome

A user without ontology expertise should be able to reach their first useful result without reading external documentation or editing the ontology.

The product should communicate this minimal mental model in plain language:

An ontology is the vocabulary and set of rules Utopia uses to recognize people, organizations, events, and their relationships. The default ontology and automatic extension features can help you get started, so you usually do not need to edit it first.

Proposed scope

Add a dismissible and reopenable first-run checklist for new deployments and empty knowledge bases:

  1. Configure and test a chat model.
  2. Confirm the recommended starter ontology.
  3. Upload a document or load sample data.
  4. Show parsing and extraction progress.
  5. Guide the user to view the graph, run a search, or ask their first question.
  6. Introduce Review and ontology maintenance only when relevant.

Supporting changes should include:

  • Direct “Configure model” and “Upload document” actions in the empty graph state.
  • Connected empty states across Graph, Library, Search, and Chat.
  • State-aware guidance for unconfigured, empty, processing, failed, and ready states.
  • Role-aware actions:
    • administrators can perform configuration directly;
    • other users are told what is missing and whom to contact.
  • An in-app Getting Started guide.
  • Plain-language explanations of ontology, classes, relationships, and review.

Acceptance criteria

  • A new administrator can configure a model and upload the first document without consulting external documentation.
  • The UI communicates processing progress and the next available action.
  • The user can reach their first graph result or cited answer without editing the ontology.
  • The UI explains the purpose of the default ontology and makes it clear that ontology editing is optional during initial use.
  • Every onboarding action links directly to the relevant screen.
  • Users are not shown actions they do not have permission to perform.
  • The onboarding flow can be dismissed and reopened.
  • Completed onboarding does not continue to interrupt existing users.
  • English and Chinese copy remain consistent.
  • Key onboarding states and administrator/member paths are covered by tests.

Out of scope

  • Teaching OWL, RDF, or ontology theory in depth.
  • Redesigning the ontology editor.
  • Adding new industry-specific ontology packs.
  • Changing the existing extraction, reasoning, or ontology-governance behavior.
Dominant language
Rust
Stars
8.1k
Forks
1.1k
Avg merge
21h 30m
Merged PRs (30d)
251

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from deeplethe/utopia

All issues in deeplethe/utopia

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.