Skip to content

docs: rewrite user docs for non-programmers - #8773

Open
sshiv012 wants to merge 15 commits into
apache:mainfrom
sshiv012:sshiv012/tex-86-user-docs-v2
Open

sshiv012 wants to merge 15 commits into
apache:mainfrom
sshiv012:sshiv012/tex-86-user-docs-v2

Conversation

@sshiv012

@sshiv012 sshiv012 commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

What changes were proposed in this PR?

User docs rewritten for people who aren't programmers, with screenshots of the current UI.

  • Rewritten:
    • the Python UDF guide: a first example, the 5 rules, and a troubleshooting table mapping each error message to its fix;
    • the "how to use Texera" guide: colors, where results and errors show, and a stuck-workflow checklist;
    • the dataset tutorial. The old one pointed to an environment tab that no longer exists, and its sample CSV link returned 404. The CSV now ships with the page.
  • New pages: Computing Units, Sharing and Permissions, and How Texera Runs Your Workflow (blocking operators, regions).
  • Links: the Python UDF reference pages now link to the guide, and dead links in Examples and Concepts are gone.
  • Warehouses: runs can now need a warehouse (feat: turn on per-user warehouses #8713), so the guide says where to pick or create one.
  • Retaken images: the two UDF error screenshots were retaken on a Texera built with the code PRs, so they show the new messages.
  • Layout: pages with images became folders (page/index.md with the images next to it). The URLs stay the same.

It quotes the new messages from the PRs below, so it should merge after them.

Any related issues, documentation, discussions?

Closes #8736. Depends on #8768, #8769, #8770, #8771, #8772, #9015. Replaces #8737.

How was this PR tested?

A separate reviewer followed every tutorial in a local Texera as a first-time user. The dataset tutorial reproduced the screenshot numbers (100 → 23 → 6). The steps they tripped on are fixed.

Was this PR authored or co-authored using generative AI tooling?

Generated-by: Claude Code (Claude Opus 5.5)

suryaacharan and others added 6 commits September 29, 2026 21:43
…hots

- Python UDF guide: working first example, the 5 rules (import, one
  class, matching method, yield, output columns), API table, setup,
  multiple inputs, and a troubleshooting table built from real errors
- How to use Texera: dashboard menu, computing units, operator state
  colors, where results and errors appear, pause/stop, and a
  "workflow looks stuck" checklist
- Dataset tutorial: current UI (Versions & Files, file picker), note
  that file paths pin a dataset version, bundled sample CSV (old link 404)
- Link the guide from the Python UDF reference pages; update UI
  overview menu; replace dead links in Examples and Concepts

Pages with images become Hugo leaf bundles (same URLs) so images sit
next to their page.

Refs TEX-86

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Computing Units: creating one (fields per type), status dots,
  reuse vs create, what terminating deletes, common error messages
- Sharing and Permissions: share dialog, read/write/owner, that
  datasets must be shared separately, public items and Downloadable
- How Texera Runs Your Workflow (Concepts): pipelining, blocking
  operators, regions and the Layers > Regions view, workers, and
  execution mode
- Link them from the Concepts index and the "how to use" guide

Result reuse is not documented: its controls are disabled on main
and each run clears the previous results.

Refs TEX-86

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A different unit can change memory, CPU, GPUs, the software image and
installed Python packages, so it can help with resource or environment
problems. Say that it usually won't fix code or configuration errors
instead of saying a workflow fails the same way everywhere.

Refs TEX-86

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Say how to open the Operators panel and the result panel, and that
  search-added operators stack on top of each other
- Filter: click + next to Predicates; field is Attribute
- Python UDF: under User-defined Functions > Python; open Result tab
- Static Error only appears when something failed
- Layers button can be hidden on narrow windows
- Admin menu contents; local units show NaN limits

Refs TEX-86

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The template now has an active import with its classes commented out,
and return-instead-of-yield, a missing super().__init__() and a dict of
DataFrames now get clear messages. List the new messages next to the
older ones, which deployments before these changes still show.

Refs apache#8736

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ehouses

- errors-all-operators.png and udf-console-error.png now show the new
  Static Error and Console messages, taken on a Texera built with the
  UDF error PRs
- Running a workflow can now need a warehouse (apache#8713); say where to
  pick or create one

Refs apache#8736

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Automated Reviewer Suggestions

Based on the git blame history of the changed files, we recommend the following reviewers:

  • Committers with relevant context: @parshimers
    You can request their reviews formally with /request-review @parshimers.

@github-actions github-actions Bot added the docs Changes related to documentations label Sep 30, 2026
@sshiv012

sshiv012 commented Oct 2, 2026

Copy link
Copy Markdown
Contributor Author

/request-review @Xiao-zhen-Liu (once we have other PRs merged)

@github-actions
github-actions Bot requested a review from Xiao-zhen-Liu October 2, 2026 20:32
suryaacharan and others added 3 commits October 8, 2026 12:04
- Import goes "at the top", results are never `return`ed as a value
- New wording for a DataFrame in a non-binary column
- Quota row mentions disconnecting local units

Refs apache#8736

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…unit)

Refs apache#8736

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Result panel: the empty states now say "No operator is selected" or
  "This operator has no results yet"; clicking a failed box shows its
  Static Error tab (apache#8771).
- UDF guide: new rows for "does not implement <method>" and "does not
  subclass a pytexera base class", @OVERRIDES on a helper, the
  "(NameError at line 2 of the UDF code)" format, and "Columns" for
  1-out UDFs (apache#8768, apache#8769).
- Retake errors-all-operators.png with the final message, on a Texera
  built from all five code PRs on current main.

Refs apache#8736

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sshiv012
sshiv012 marked this pull request as ready for review October 15, 2026 22:21

@Xiao-zhen-Liu Xiao-zhen-Liu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked each page against main and the open PRs it quotes. Apart from the inline comments, the UI labels, colors and quoted messages match the code. Two statements disagree with what users see: terminating a unit (comment 1) and the Static Error step for a stuck run (comments 2 and 3). This PR quotes text from #8770, #8771, #8772 and #9015, which are still open, so please merge it only after all four land, and recheck the quoted messages then.

Comment thread docs/tutorials/computing-units.md Resolved

- **Click the box that failed, or an empty spot on the canvas.** If the run failed, the result panel shows a **Static Error** tab with the error, including code that failed to start. With nothing selected it lists every operator's errors. A run that stops right away with every box at 0 rows usually means this.

![Static Error tab listing an error for all operators](errors-all-operators.png)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: #9015's description says the message loses its "java.lang.Throwable:" prefix once it lands, so this screenshot will be out of date. Since this PR waits for #9015 anyway, please retake it after that merges.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will do. I'll retake it once #9015 is merged!

Comment thread docs/getting-started/ui-overview.md Resolved
sshiv012 and others added 3 commits November 18, 2026 22:31
…menus

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Changes related to documentations

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make Python UDFs and the workflow editor easier for non-programmers to debug

2 participants