From 3b0cf47c2857375d545976599199bda96bfbb6e4 Mon Sep 17 00:00:00 2001 From: "Nicholas H.Tollervey" Date: Thu, 9 Jul 2026 13:44:53 +0100 Subject: [PATCH] Add UX report. --- docs/ux/ai_default.md | 98 +++++++++++++++++++++++ docs/ux/appendix1.md | 68 ++++++++++++++++ docs/ux/appendix2.md | 31 ++++++++ docs/ux/case_study.md | 67 ++++++++++++++++ docs/ux/conclusion.md | 106 ++++++++++++++++++++++++ docs/ux/friction_free.md | 60 ++++++++++++++ docs/ux/index.md | 76 ++++++++++++++++++ docs/ux/interviewees.md | 115 +++++++++++++++++++++++++++ docs/ux/introduction.md | 65 +++++++++++++++ docs/ux/js_boundary.md | 77 ++++++++++++++++++ docs/ux/key_findings.md | 104 ++++++++++++++++++++++++ docs/ux/onboarding_path.md | 75 +++++++++++++++++ docs/ux/packages_stability_errors.md | 58 ++++++++++++++ docs/ux/summary.md | 60 ++++++++++++++ docs/ux/themes_at_a_glance.md | 52 ++++++++++++ docs/ux/visibility.md | 81 +++++++++++++++++++ mkdocs.yml | 18 +++++ 17 files changed, 1211 insertions(+) create mode 100644 docs/ux/ai_default.md create mode 100644 docs/ux/appendix1.md create mode 100644 docs/ux/appendix2.md create mode 100644 docs/ux/case_study.md create mode 100644 docs/ux/conclusion.md create mode 100644 docs/ux/friction_free.md create mode 100644 docs/ux/index.md create mode 100644 docs/ux/interviewees.md create mode 100644 docs/ux/introduction.md create mode 100644 docs/ux/js_boundary.md create mode 100644 docs/ux/key_findings.md create mode 100644 docs/ux/onboarding_path.md create mode 100644 docs/ux/packages_stability_errors.md create mode 100644 docs/ux/summary.md create mode 100644 docs/ux/themes_at_a_glance.md create mode 100644 docs/ux/visibility.md diff --git a/docs/ux/ai_default.md b/docs/ux/ai_default.md new file mode 100644 index 00000000..3b910a8d --- /dev/null +++ b/docs/ux/ai_default.md @@ -0,0 +1,98 @@ +# Theme E: AI is now the default route in, through and around PyScript + +## What it is + +Large language models as the medium of discovery, learning, +construction and documentation for PyScript. This is not a single feature +request; it is a shift in the environment, community and industry in which we +operate. + +## What it means for PyScript + +AI now sits on almost every path a user takes. +Discovery: Nitau, an engineer, found PyScript because "the LLM told me that +PyScript runs Python in the browser using WebAssembly." Building: Claudiu, a +hobbyist, has moved from writing code to directing it, teaching Claude to use +his PyScript helper functions and stepping back until "I'm never reading the +code, because the code is being produced much faster than I can read it." +Momin, an engineer, has built an entire platform around a copy-paste-from-LLM +workflow for non-technical students. Sai, an informatician, runs an AI agent +that generates Python executed in PyScript, and finds it competitive with a +"billion-dollar company's" full coding-agent setup, partly because "PyScript on +the browser is way faster, I can see what's happening." + +There is a clear and important spread of attitudes, which we should represent +faithfully rather than lose under the generic "AI" term. At one end, Claudiu is +comfortable not reading the code. In the middle, Nitau uses "basic prompting" +as "a conscious choice," remaining "the gatekeeper" who reviews everything +before it enters his codebase, and Łukasz treats it as "a productivity +booster, but sometimes it's more like a slot machine." At the other end, +Kattni does not use AI at all, on ethical grounds (training data, climate, and +what she called an "evangelical" culture), and also because her self-assessed +Python knowledge means she "wouldn't be able to tell whether what I was just +given is good or bad." Anna, a learner, deliberately avoids AI for schoolwork +on principle while using it for lab work to move faster. + +Two practical sub-findings deserve emphasis. First, model quality against +PyScript changed materially and recently: Łukasz reported that before December +2025, using AI with PyScript was "pretty dangerous," and that with Opus 4.5 it +became "tractable," speculating it may have been trained on the PyScript docs. +Momin noted LLMs "cannot detect the current version of PyScript" and sometimes +add random imports that break the code. Second, and strategically most +important: our documentation increasingly reaches humans only after passing +through an LLM. Nitau observed that he fed the docs' Markdown files to an AI +and "it did a perfect job." Nicholas's own reflection, echoed to several +interviewees, is that the people who read our documentation "are not people, +they're LLMs." + +This extends beyond documentation. As AI-native tooling (coding agents such as +Claude Code and GitHub Copilot) becomes the default way practitioners build, +the question is no longer only whether a human can read our docs, but whether +an AI agent can correctly represent our APIs and services when a practitioner +prompts it. How well we express our work to these tools increasingly +determines the quality of response a practitioner receives about PyScript, and +about Anaconda's products more widely. Nicholas has +[written in depth about the challenges this poses](https://ntoll.org/article/predico/). + +## Future steps + +Treat "how our resources are consumed by LLMs" as a +first-class engineering, education and documentation problem (work Nicholas +has already begun). Ensure the docs, API surface and examples are structured +so an LLM produces correct, version-aware PyScript; the version-detection +failure Momin reported is a concrete target. Keep a genuinely AI-free path +fully supported and first-class, both because some valued community members +(Kattni) require it and because learners (Anna) deliberately choose it. Avoid +taking a single position on AI; the community spans the full range and trust +depends on us respecting and embracing that. Treat how our APIs and services +are represented inside AI-native coding tools as an extension of the +documentation problem: what a coding agent generates about PyScript is now +part of our public interface. + +## Standing across archetypes + +Universal, but polarised. Engineers and +hobbyists are furthest into AI-assisted building; educators are the most +cautious; learners are thoughtfully selective. + +## Challenges + +A definitional confusion has dogged discussion of AI and +PyScript inside Anaconda. "AI in the browser" can mean two quite different +things. + +1. The first is running LLMs *inside* the browser runtime itself, using + experimental web APIs. +2. The second is what every AI-using practitioner in these interviews actually + does: use LLMs as ordinary and complementary tools (cloud services or + agents) that generate or assist with Python, which then runs in PyScript. + +Internal advocacy at Anaconda has focused on the first sense of "AI in the +browser" (running models inside the browser); all the practitioner evidence in +this report concerns the second (LLMs as external tools generating PyScript +code or consuming PyScript-based resources). Acting on this theme therefore +requires realigning internal direction with the evidence, rather than +advocating for something with no demonstrated use case, market signal or +community demand. That realignment is beyond the PyScript team's sole +authority. Furthermore, were in-browser models ever wanted, JavaScript would be +the better-performing tool for the job. \ No newline at end of file diff --git a/docs/ux/appendix1.md b/docs/ux/appendix1.md new file mode 100644 index 00000000..c1361b9f --- /dev/null +++ b/docs/ux/appendix1.md @@ -0,0 +1,68 @@ +# Appendix 1 - Core Concepts + +PyScript's approach rests on three interconnected core concepts that +help us move from the abstract to the concrete (and back again): + +## Archetypes + +Archetypes are abstract definitions of roles or postures a practitioner may +adopt. We currently use six archetypes: + +* Learner - whose primary focus is skill and knowledge acquisition. +* Educator - helps, mentors and creates resources for the learner archetype. +* Engineer - builds valuable things with technology, often in a professional + capacity. +* Informatician - where technology is an important aspect of their job, + while their role is in an orthogonal discipline to coding (for example, + they're a data scientist, meteorologist, developer relations advocate or + medical informatics analyst). +* Administrator - an information worker who uses tech as a secondary + (facilitating) aspect of their job, which focuses on managerial, + bureaucratic or vocational functions. For example, the COO trying to build + a status dashboard or a doctor refining the EHR (electronic health record) + processes in their hospital. +* Hobbyist - is enthusiastic about tech (for tech's sake). They might think + of themselves as a "maker", "geek" or participate in open-source community + activities. + +These archetypes help us to think structurally about the different ways people +might approach and use PyScript, without assuming any single practitioner +fits neatly into one category. In reality, we embody multiple archetypes +depending on context or need. + +## Personas + +Personas are fictional yet carefully constructed embodiments of archetypes. +Each persona has a name, cultural context, background and specific needs. +They exist to help us explore concrete examples of requirements, working +patterns, and contextual motivations. Personas bridge the gap between abstract +thinking about practitioner types and the messy, specific reality of actual +human needs. They help us engage with enlarged empathy and imagination, rather +than through small-minded stereotypes that constrain our thinking. They are +the foil to feature-focused technical work based on "cool" technology and +coding fashions. + +Examples of such personas can be +[found in the Invent framework](https://invent-framework.github.io/design/#personas), +(work from 2023). + +## Practitioners + +Practitioners are real people who may encompass one or more persona +characteristics (like the participants in these interviews). They are the +ultimate source of truth. We validate our assumptions, refine our thinking, +and revise how we define both archetypes and personas based on what +practitioners demonstrate and tell us. Because of PyScript's open-source +foundations, engagement with certain sorts of practitioner happens regularly +through informal community channels. This research aims to formalise, broaden +and deepen that engagement. + +This vocabulary originates from work undertaken in 2023 for the Invent +framework (built upon PyScript) and draws upon Nicholas's experience with UX +research at organisations including The Guardian (which had their own +in-house UX "lab") and Marks and Spencer (who make extensive +use of joined-up personas in many teams, from tech and product to marketing +and PR). It reflects the PyScript OSS team's belief in holistic collaboration: +software engineers must work and collaborate with UX and product colleagues, +and not merely implement "features" in isolation or based on guesswork and +tech fashions. diff --git a/docs/ux/appendix2.md b/docs/ux/appendix2.md new file mode 100644 index 00000000..9b2a5f59 --- /dev/null +++ b/docs/ux/appendix2.md @@ -0,0 +1,31 @@ +# Appendix 2 - Theory and Practice + +This research was also informed by an internal Anaconda UX framework +organised around segments, personas and scenarios. Because this report will +be read outside Anaconda, we describe how that framework relates to +PyScript's approach without reproducing its confidential detail. Its segments +describe practitioner types as functional roles within organisational +structures, and map closely to PyScript's archetypes ([appendix 1](./appendix1.md)), which +describe postures towards creating with code. Its personas work just as +PyScript's do, giving the two frameworks a shared vocabulary. Its most +valuable addition is scenarios: three descriptions of what practitioners try +to accomplish regardless of role or background - Setting Up (their +environment, tooling and initial access to assets), Building and Development +(creating, testing and iterating on technical work) and Sharing and +Collaboration (distributing outcomes, working with others, managing access). +Every practitioner in this report navigates a variation of all three, and +they are a welcome lens on a practitioner's journey that PyScript's research +will adopt. + +Related is the notion of "AI-native" development, a term +[coined by Gartner](https://www.gartner.com/en/articles/top-technology-trends-2026) +to describe systems, products and engineering practices that integrate AI as +a core, foundational component rather than a bolted-on feature. Gartner's +specific forecasts are informed speculation and we treat them as such, but +the term is the current language of our commercial users, and this report +engages with what it names: how practitioners now build with AI-native +tooling, and how well our APIs, services and documentation are represented +inside those tools. [Theme E](./ai_default.md) presents the practitioner evidence for this and +[next step #4](./conclusion.md#4-make-pyscript-an-excellent-citizen-of-the-llm-ecosystem) proposes the response. It is where the open-source practitioner +focus of this report and Anaconda's commercial interests most clearly +converge. \ No newline at end of file diff --git a/docs/ux/case_study.md b/docs/ux/case_study.md new file mode 100644 index 00000000..1c5b88e1 --- /dev/null +++ b/docs/ux/case_study.md @@ -0,0 +1,67 @@ +# Case study: the Tufts tooling arc (PyScript.com reliability and TuftsHub) + +This case study sits slightly apart from the six themes because it is a single, +continuous story told across two calls, and because its subject, Chris and +Ethan at Tufts, is an institutional relationship rather than an individual +archetype. It is included in full because it does three things at once: it +states the PyScript.com reliability problem first-hand, it enumerates exactly +what a replacement must provide, and it demonstrates the engagement loop this +report advocates. + +## The problem + +Chris and Ethan both praised PyScript.com's ease of +developing, sharing and cloning, and the instant browser-based start it gives +students. The failure is reliability. In Chris's words the service "does with +fair regularity" become "ungodly slow", and when it does so mid-lesson "the +class kind of falls apart", with a middle-school workshop, college classes and +company presentations all named as failures. Because PyScript.com is +unmaintained, the fix path runs through colleagues and infrastructure and +takes fifteen minutes to half an hour, which is no use in front of a class. +This is the first-hand version of the crashes Anna and Hammad reported +second-hand. + +## What a replacement must provide + +The professors were willing to move +hosting to GitHub Pages, which they value for teaching industry-standard Git +workflows, but only three PyScript.com capabilities stand in the way: channels +(sharing information between pages over WebSockets), an API proxy (so a secret +key is never exposed), and authorisation (so a project is restricted to +approved people, since an open project is, as Ethan noted, "attached to my +credit card"). A useful clarification emerged on channels: they already run on +the same publish/subscribe logic as the industry-standard MQTT message bus, +with PyScript.com acting as the broker, and Chris confirmed they have +connected Raspberry Pis and ESP32s to the PyScript WebSocket. The desired +solution was a one-click, pip-installable tool that "just sits there happily +humming away in the corner like a fridge", local-first and offline-capable +(Ethan's "aeroplane version"), syncing to a GitHub folder, and self-hostable +on Tufts, Amazon or any other infrastructure. Nicholas noted this effectively +amounts to a white-label "PyScript.com enterprise" instance, a useful data +point and potential opportunity for Anaconda. + +## The response and its review + +Nicholas built TuftsHub (thub) against these +requirements, and the second call reviewed it. Chris demonstrated it serving an +app locally straight from the source he was editing, with user management built +in. Feedback and new requests followed: a one-action pull of an existing +PyScript.com project (reading the `pyscript.toml` and assembling a complete +offline copy), support for running several projects at once, and a +single-window view combining files, code and live preview to escape the sprawl +of many editor and browser windows. Nicholas was careful throughout not to +reinvent PyScript.com's in-browser IDE, preferring to open the design question +to colleagues Martin and Josh and the wider community, and floated his earlier +PySnippets work as a possible starting point. + +## Why it matters + +Beyond the concrete requirements, the arc is the report's +clearest example of engagement done effectively: requirements gathered on the +record so the movement from problem to solution is visible, a proof of concept +built quickly, a review to refine it, and then a deliberate opening-up, keeping +the repository under the Tufts GitHub organisation, seeking a better name than +thub, releasing on PyPI, and shifting future requests from private Slack to +public GitHub issues. It is both a source of requirements (Themes +[A](./friction_free.md), [B](./js_boundary.md), [D](./onboarding_path.md)) and +a template for how this kind of work should run ([Theme F](./visibility.md)). \ No newline at end of file diff --git a/docs/ux/conclusion.md b/docs/ux/conclusion.md new file mode 100644 index 00000000..593aba26 --- /dev/null +++ b/docs/ux/conclusion.md @@ -0,0 +1,106 @@ +# 6. Conclusion and next steps + +The headline is encouraging and directive in equal measure. PyScript's core +proposition, friction-free Python in the browser, is genuinely loved and is +working ([Theme A](./friction_free.md)). The recent engineering and documentation work is landing. +The clearest risks are not that people dislike PyScript, but that +PyScript.com's reliability is actively disrupting the teaching of our closest +institutional partners, that we win people on the easy case and lose them at +the JavaScript and browser boundary ([Theme B](./js_boundary.md)), and that too few people know +PyScript exists at all ([Theme F](./visibility.md)). + +## Next steps + +The following next steps map onto the themes. They are proposed in the +interests of discussion, not as explicit commitments: each requires +refinement based on evidence and feedback. + +### 1. Target the boundary drop-off + +**([Theme B](./js_boundary.md))** + +Commission a migration-style +tutorial series for Python programmers, showing the wrong way then the right +way across the FFI, workers and debugging. Tighten runtime-ready semantics +and framework-integration and header documentation. This is the single +highest-leverage retention move. + +### 2. Invest in demos and remixable examples + +**(Themes [A](./friction_free.md), [C](./packages_stability_errors.md), [D](./onboarding_path.md))** + +Treat idiomatic, tear-apart-and-recombine examples as a primary onboarding +surface. This directly addresses the blank page problem and gives learners +and educators something to start from. + +### 3. Finish the compatibility and error-message work, and add a stability story + +**([Theme C](./packages_stability_errors.md))** + +Surface package compatibility earlier and more loudly, add a +plain-language explanatory layer to common errors, and investigate a pinned, +long-term-support environment for educational and self-hosted use. + +### 4. Make PyScript an excellent citizen of the LLM ecosystem + +**([Theme E](./ai_default.md))** + +Treat how our docs, API and examples are consumed by LLMs as a first-class +problem; fix version-awareness in generated code; and keep a fully supported +AI-free path. Hold no single house line on AI in our external-facing +communication. + +### 5. Get Invent to an early release and validate it against real users + +**(Themes [A](./friction_free.md), [D](./onboarding_path.md), [E](./ai_default.md))** + +Hammad described Invent unprompted - an encouraging signal. Aim +for an alpha in Q2 2026 and put it in front of Hammad, Mark and others for +iterative feedback, designing to Mark's migratability test. + +### 6. Fix PyScript.com reliability, and ship the self-hostable tool + +**(Themes [A](./friction_free.md), [B](./js_boundary.md), [D](./onboarding_path.md), [F](./visibility.md))** + +Two parallel tracks, and a decision. Immediately, track down and +repair the underlying PyScript.com reliability problem, since it is +disrupting a named institutional partner's teaching now. In parallel, take +TuftsHub to a named, pip-installable PyPI release providing channels, the +API proxy and authorisation for local-first and self-hosted use, developed +in the open under the Tufts organisation. And decide, deliberately, whether +PyScript.com is to be properly resourced or retired ([Theme A](./friction_free.md)); **the current +unowned middle state is the worst option**. Note the strategic signal +Nicholas flagged: this is effectively a white-label "PyScript.com +enterprise" pattern worth Anaconda's attention. + +### 7. Build sustained visibility and repair trust + +**([Theme F](./visibility.md))** + +Stand up a +content strategy weighted to video and LLM channels; pursue the CodePen +partnership; make feedback routes visible from inside the product (an +in-product banner, per Anna); re-engage deliberately with contributors like +Claudiu; and treat the Tufts arc as the template for requirement-to-solution +work done in the open and based upon evidence. + +One forward-looking note. The commercial software world is increasingly framed +around what Gartner calls "AI-native" development (explored more fully in +[appendix 2](./appendix2.md)). Their specific predictions are speculation, and we treat them as +such. But the language is the language our commercial users already think in, +and engaging with it - meeting practitioners inside the AI-native tools they +now use - matters regardless of whether the forecasts prove accurate. This is +where the open-source practitioner focus of this report and Anaconda's +commercial interests most clearly converge. + +## Conclusion + +A closing observation. Almost every interviewee, unprompted, offered to keep +helping: to file issues, to share breaking examples, to trial Invent, to join a +community call. Chris and Ethan went further, co-developing a tool with us in +the open. + +The raw material for a vibrant, empowering PyScript is already here in the +people who use it. + +Our job is to listen, and make it obviously worth their while. \ No newline at end of file diff --git a/docs/ux/friction_free.md b/docs/ux/friction_free.md new file mode 100644 index 00000000..36e5ab6a --- /dev/null +++ b/docs/ux/friction_free.md @@ -0,0 +1,60 @@ +# Theme A: Friction-free, all-in-one is the core value + +## What it is + +The zero-setup, type-and-see, everything-in-one-window +experience. No virtual environments, no installation, no toolchain, no context +switching between editor, terminal and browser. + +## What it means for PyScript + +This is the thing that works, and the thing we +must not break as we add capability. It is disproportionately important for +learners and educators, for whom setup is the barrier that stops people before +they start. + +For Anna, a learner, it is the whole reason she can work at all: the +zero-setup, immediate-feedback loop was "super helpful when I was learning." +For Kattni, an educator, the value is that the environment collapses the many +moving parts of a normal Python workflow into a single location: "everything's +in one place... I'm not running around to different applications to do +different pieces of it," which she found "more similar to working with +microcontrollers than it is working with just pure CPython." Hammad, also an +educator, praised the same simplicity from the parent's side of the desk: +"there's beauty and simplicity, especially for picking things up." + +Note the mirror image in the critique: the same all-in-one quality that +delights learners is precisely what more advanced users say they eventually +outgrow (see [Theme B](./js_boundary.md) and [Theme D](./onboarding_path.md)). + +The Tufts case study underlines just how central this loop is. Chris was clear +that "the thing that makes PyScript.com powerful is the ability to quickly be +able to code and see," and that this fast edit-and-see cycle is the specific +property he most wants preserved in any replacement. It is telling that the +professors were willing to move their hosting to GitHub Pages for reliability +but balked at losing this loop, since the commit-deploy-refresh cycle there is, +in Ethan's words, slow and "not even predictable." + +## Future steps + +Protect this experience as a first-class product property. +When we add higher-level capability (Invent; see [next step #5](./conclusion.md#5-get-invent-to-an-early-release-and-validate-it-against-real-users)), the test is +whether it preserves the type-and-see loop. We should also be explicit, in docs +and onboarding, that the friction-free path is a deliberate design choice and +not a limitation, so that experienced users understand the escape hatches +exist. + +## Standing across archetypes + +Central for learners and educators; taken for +granted, and sometimes outgrown, by engineers. + +## Challenges + +PyScript.com was moved into unmaintained status by a decision +taken without consultation with the PyScript OSS team. The consequences +documented in this report (unreliability disrupting teaching at Tufts, silent +crashes for learners like Anna) were therefore foreseeable but not planned for. +Acting on this theme means either resourcing the platform properly or managing +its retirement deliberately; the current middle state is the worst of both, and +the reputational cost is already visible in this report's evidence. \ No newline at end of file diff --git a/docs/ux/index.md b/docs/ux/index.md new file mode 100644 index 00000000..fb0d6157 --- /dev/null +++ b/docs/ux/index.md @@ -0,0 +1,76 @@ +# PyScript Practitioners: Analysis, Findings and Future Steps + +Nicholas H.Tollervey 2026-7-3 + +## Key Quotes + +> "You guys, without knowing it, have built the simplest system of just +> getting started." + +- Hammad, engineer and home educator (on PyScript's simplicity) + +> "PyScript is closer to the LED blinking - you do the thing and it's all +> right there." + +- Kattni, educator (on how quickly it is possible to get results) + +> "I tried it out. It works for something simple, it didn't work for +> something else, I didn't know what to do." + +- Łukasz, CPython Developer in Residence (relaying what other Python + programmers tell him) + +> "It just becomes ungodly slow. If you're in the middle of a class, then +> the class kind of falls apart." + +- Chris, Tufts University (on PyScript.com) + +> "I basically walk away and hope it's working." + +- Anna, student (on what she does when PyScript.com crashes) + +> "I put a lot of work into that - a professionally done presentation. And +> nothing came of it." + +- Claudiu, project manager (on the marketing proposal he brought to the + project) + +> "The people who are mostly going to read our documentation are not people, +> they're LLMs." + +- Nicholas, core maintainer (on the documentation re-write) + +> **Chris:** "I want a one-click solution so that it just works. And maybe I +> log in with my GitHub stuff and I point it to a folder that I also have +> synced to GitHub..." +> +> **Nicholas:** "[You] just want to be able to pip install a thing, add a +> configuration file, and it just sits there happily humming away in the +> corner like a fridge. And you don't really need to worry about it from that +> moment on." +> +> **Chris:** *[nodding]* "Yes." +> + +- Chris explaining his ideal development / deployment environment to + Nicholas + +## Contents + +* Preface (this page). +* [Executive summary](./summary.md) +* [1. Introduction](./introduction.md) +* [2. Key findings](./key_findings.md) +* [3. The interviewees](./interviewees.md) +* [4. Key themes at a glance](./themes_at_a_glance.md) +* 5. Themes in detail + - [5a Friction free](./friction_free.md) + - [5b The JavaScript Boundary](./js_boundary.md) + - [5c Packages, stability and errors](./packages_stability_errors.md) + - [5d The onboarding path](./onboarding_path.md) + - [5e AI as default](./ai_default.md) + - [5f Visibility and community](./visibility.md) + - [Case study: Tufts](./case_study.md) +* [6. Conclusion](./conclusion.md) +* [Appendix 1](./appendix1.md) +* [Appendix 2](./appendix2.md) \ No newline at end of file diff --git a/docs/ux/interviewees.md b/docs/ux/interviewees.md new file mode 100644 index 00000000..0b1c75ee --- /dev/null +++ b/docs/ux/interviewees.md @@ -0,0 +1,115 @@ +# 3. The interviewees + +Each interviewee introduced here embodies one or more practitioner archetypes, +explained in [appendix 1](./appendix1.md). + +## Anna + +Anna is a computer science undergraduate at Tufts who began +programming only the summer after her first year. She works in Chris's +lab, building web interfaces that let connected computers control +LEGO hardware through a drag-and-drop, text-snippet editor. She uses +PyScript.com exclusively, with no local toolchain. **Archetype: learner.** Her +use case is educational hardware control within the lab; her current situation +is full-time study, with lab work as her main coding context. + +## Claudiu + +Claudiu is a global product owner and portfolio manager at a large +multinational, with a background in marketing and economics. He came to Python +around eight or nine years ago to automate repetitive work, then to web +development, and chose PyScript over Brython (another Python-in-the-browser +solution) because it felt "alive and kicking." PyScript is a hobby and "second +job" rather than part of his role. In an effort to give back and engage with +the open-source community he previously produced a marketing proposal for +PyScript which went unanswered, causing him to walk away. He now builds +LLM-first, delegating implementation to Claude Code and Codex with Playwright +tests. **Archetype: hobbyist (with administrator/strategy leanings).** + +## Hammad + +Hammad is an oil and gas engineer who moved into finance, travelling the +"Excel VBA to R to Python" road. He home educates his son and wants a +batteries-included, static, self-hosted PyScript setup modelled on his positive +experience with JupyterLite and Xeus Python, plus a simple opinionated UI +framework. **Archetype: educator (home educator, with finance/maths +informatician leanings).** His use case is teaching foundations without +configuration overhead. + +## Kattni + +Kattni learned Python through CircuitPython, which she helped build, and +now works on the BeeWare team with a documentation focus. An extensive and +well known community organiser, she will be the 2028 PyCon US chair. She +describes her own Python gaps candidly and brings a "professional beginner" +lens that is exceptionally good at surfacing friction. She does not use AI in +her coding, for ethical, cultural and self-assessed-competence reasons. +**Archetype: educator (teaching newcomers is her lens).** Her use case is +small teaching projects and lowering the barrier to entry. + +## Łukasz + +Łukasz, now at Facebook, at the time of the interview he was the CPython +Developer in Residence at the PSF and has been a core CPython developer since +2010. His focus at the time of interview was work on Python 3.15. He uses +PyScript for multimedia, games and generative art in the browser, and was an +early adopter. He wants proper version control in PyScript.com (Git +integration) and, given infinite resources, a browser-based game engine +packaged for desktop and consoles. **Archetype: engineer (expert power +user).** + +## Mark + +Mark has used Python since version 1.5, came from Lisp machines at +Symbolics and has a long-term background in visual effects, having worked in +the team behind the motion capture for The Lord of the Rings movies (among +other things). He builds machine-knitting pattern tools using +[LTK](https://github.com/pyscript/ltk), the Python Imaging Library and SVG. He +is highly experienced, quotable and opinionated as a result of his +extensive and broad expertise: "architecture is destiny." **Archetype: engineer +(veteran virtuoso).** His use case is real, shippable browser tools built on a +deliberately minimal platform. + +## Momin + +Momin is a backend Python and Django developer, based in Pakistan, who left +a job to build his own products. His platform LightAI.me lets non-technical +students publish AI-generated PyScript and JavaScript apps; he cites roughly +5,000 hits, 72 sign-ups and 159 projects, grown organically. **Archetype: +engineer (platform builder serving non-technical users; administrator +leaning).** + +## Nitau + +Nitau is a full-stack developer with a computer science and AI background +whose philosophy is simplicity, reusability and the Zen of Python. He found +PyScript via an LLM while building a note-taking app and plans to use it for +around eight future projects, including a CRM. He argues PyScript should be +seen as a front-end technology on a par with React or Vue: "inverse Node.js." +**Archetype: engineer.** + +## Sai + +Sai has a mechanical and petroleum engineering background and works at an +oil and gas service company, doing algorithm development through to software +deployment. His recent work has a cloud-based AI agent generate Python that +runs client-side in PyScript, using the browser's sandbox and existing +authentication. He authored the [PyKernel tool](https://www.pykernel.com/). +**Archetype: informatician (domain scientist writing software).** + +## Tufts (Chris and Ethan) + +Chris and Ethan are two professors at Tufts University who teach with +PyScript, and they are best understood not as individual archetypes but as an +**institutional relationship**. Tufts is a sustained partner: they run PyScript +in classrooms, workshops and company presentations, build prototypes with it in +the lab, and their students (Anna among them) are downstream users of the +infrastructure the professors stand up. Chris is a mechanical engineer; Ethan +is an electrical engineer and ed-tech developer whose concerns run to hosting, +authorisation, credentials and cost. Between them they speak with an +educator's, an engineer's and an administrator's voice at once, which is why +their evidence is handled as a case study (Section 5) rather than folded into a +single practitioner archetype. Their standing to us is different in kind: they +are not solicited interviewees but a continuing collaboration, and the health +of that relationship is itself a signal of how well we engage institutional +customers. \ No newline at end of file diff --git a/docs/ux/introduction.md b/docs/ux/introduction.md new file mode 100644 index 00000000..b5d6b35a --- /dev/null +++ b/docs/ux/introduction.md @@ -0,0 +1,65 @@ +# 1. Introduction + +We have three simple aims: + +1. To better understand how practitioners perceive and use PyScript through + evidence-based qualitative research methods. + +2. To identify how we should refine and grow PyScript in response to the + practitioner feedback - while clearly identifying and learning from our + mistakes. + +3. To demonstrate and embody professional, inclusive and cooperative + community engagement as good open-source citizens. + +Ultimately, this is an exercise in placing PyScript practitioners (be they +commercial customers or open-source community members) at the heart of what we +do, so we build something empowering, vibrant and valuable. + +Our evidence is of two sorts. + +1. Nine individual practitioner interviews spanning a deliberately diverse +range of the practitioner archetypes: learner, educator, engineer, +informatician, administrator and hobbyist. [Appendix 1](./appendix1.md) +defines these archetypes and the methodology behind them. + +2. A two-part tooling case study with two professors at Tufts University, +Chris and Ethan, who together represent an institutional relationship rather +than a single archetype (see [Section 3](./interviewees.md) and the case study +in [Section 5](./case_study.md)). The +first Tufts call gathered requirements around PyScript.com's reliability; the +second reviewed TuftsHub, the tool Nicholas quickly built in response. + +The individual interviews were semi-structured. Each opened with the person's +background and route into PyScript, moved through a recent project and their +tooling, probed the bumps in the road, and closed with reactions to community +tools and an open "moon on a stick" prompt about what we should build next. +Several included a short live coding session; these sessions produced some of +the most valuable material we gathered. See [appendix 2](./appendix2.md) for an +exploration of UX-related concepts used to inform how we organised, structured +and approached the interviews. + +A note on method. Jessie and Nicholas planned the interview structure with help +from Avery, Anaconda's in-house UX expert, and conducted the interviews +together over Zoom. All participants gave recorded consent and provided basic +information about their use and impressions of PyScript via a form sent in +advance. Participants were recruited from the existing PyScript community: an +open call in community channels, supplemented by direct invitations where the +volunteers left an archetype uncovered (Anna, our learner, joined this way). +Two participants, Nitau and Claudiu, are pseudonyms at their request; all other +names are real. Each interview produced textual outcomes: a full transcript, +summary and thematic breakdown. As a first analytical pass, these were read by +Claude (an LLM), which proposed candidate overarching themes. Everything that +followed was human work: Nicholas checked every transcript, cross-referenced +between interviews, and wrote and refined the report itself (with, in the spirit +of full disclosure, an LLM as proofreader and critic). This is a human-authored +report, with an AI used for analytical first passes and editorial suggestions. + +A note on the sample. The individual interviews skew towards experienced +engineers, with only one early-stage learner and no pure administrator. Claudiu +is the closest we have to an administrative or strategic voice, and he +straddles the hobbyist and administrator types. The Tufts case study partly +offsets this, since it speaks directly to institutional concerns (hosting, +authorisation, credentials, cost) that the individual interviews touch only +lightly. Even so, broadening the individual sample across all six types is +worth doing in future research. \ No newline at end of file diff --git a/docs/ux/js_boundary.md b/docs/ux/js_boundary.md new file mode 100644 index 00000000..d9682ca4 --- /dev/null +++ b/docs/ux/js_boundary.md @@ -0,0 +1,77 @@ +# Theme B: The JavaScript and browser boundary is where we lose people + +## What it is + +The Python/JavaScript interface, the FFI, complex worker +semantics, debugging across the two runtimes, and the browser's security model. +The place where a Python programmer's reasonable expectations become lost in +the unfamiliar and mysterious platform that is the browser. They are used to +being knowledgeable and productive but suddenly find themselves in confusing, +unfamiliar territory. The result is a feeling of disempowerment and loss of +agency. + +## What it means for PyScript + +This is the most important retention finding in +the whole set. We convert well on the easy case and lose people at the next +step, and the drop-off is concentrated at this point. Łukasz, an expert +engineer, articulated the pattern he hears repeatedly from other Python +developers: they try PyScript, "it works for something simple, it didn't work +for something else, I didn't know what to do." He is candid that his own +fluency is survivorship: he has learned to "avoid the rough edges, not because +they're no longer there, just because you know to avoid them." He described the +specific pain of debugging across two runtimes: the JavaScript debugger does +not step into PyScript code, and PyScript debugging techniques do not step into +JavaScript. + +The boundary shows up differently for different users. Hammad, an educator, +does not want to see it at all: "I know in your docs, it's like `import ffi`. +To me, I'm sitting there being like... there's more of a layer [that] can go on +top." Nitau, an engineer, hit a concrete limitation trying to extend web +classes (a custom `div` subclass) and found the translation into JavaScript +got in the way. Sai, an informatician, spends most of his time fighting the +framework-integration case (PyScript inside React or Next.js) and worker +headers, and reported non-deterministic runtime readiness: "when the agent +starts and spits out the Python code, sometimes it's flaky, sometimes the +runtime is not ready." Mark, a veteran engineer, wanted a straightforward path +to integrate arbitrary WASM modules such as ammo.js and found none. + +The Tufts case study names an additional problem in a particularly concrete +and actionable way. Reduced to essentials, what PyScript.com provides that +plain GitHub Pages hosting cannot is three capabilities: channels (sharing +information between pages over WebSockets), an API proxy (so a secret key such +as one for ChatGPT is never exposed), and authorisation (so a hosted project is +restricted to approved people or domains). Ethan was precise about why the +proxy and authorisation matter together: an open project means "anyone can be +using my chatbot, and then that's, of course, attached to my credit card." +These are not abstractions about "the JS boundary"; they are tangible +capabilities that, once a project needs more than to run by itself, push a user +off GitHub Pages and back towards a service. They are also the natural shape of +a self-hostable tool (see [Theme D](./onboarding_path.md) and the [case study](./case_study.md)). + +## Future steps + +This deserves dedicated attention. Concretely: (1) a +migration-style tutorial series aimed at Python programmers crossing the +boundary, showing the wrong way and then the right way, which Łukasz explicitly +asked for; (2) clearer, awaitable runtime-ready semantics and documented +patterns for framework integration and worker headers, drawing on Sai's +deployment experience; (3) better cross-runtime debugging guidance; (4) a +documented recipe for integrating third-party WASM modules, per Mark. Several +of these are documentation and example problems as much as engineering ones, +which makes them quickly tractable. + +## Standing across archetypes + +This is the engineers' and informaticians' +theme above all. Educators want the boundary hidden entirely; engineers want it +made navigable. + +## Challenges + +The browser platform itself is the constraint. Workers, +response headers, security policies and the FFI are inherent complexities of +the web, not defects we can engineer away. Our room for action is limited to +education, documentation, abstraction through frameworks (Invent) and API +smoothing (the built-in `pyscript` namespace): we can make the boundary +navigable, but we cannot remove it. \ No newline at end of file diff --git a/docs/ux/key_findings.md b/docs/ux/key_findings.md new file mode 100644 index 00000000..6e095fde --- /dev/null +++ b/docs/ux/key_findings.md @@ -0,0 +1,104 @@ +# 2. Key findings + +## Affirmations + +The strongest and most consistent theme is that PyScript's frictionless +experience is its defining strength: it just works. People who did +not enjoy setting up Python environments, or who could not, found that PyScript +removed that barrier entirely. Anna, a learner, valued that "there is no setup +you have to do, you just hit create website, and then you can type right in and +immediately see on the other side what is happening." Kattni, who teaches, +compared it directly to the moment that first drew her to CircuitPython: +"PyScript is closer to the LED blinking in the sense that you do the thing and +it's all right there." Hammad, who home educates, went as far as to say we had, +perhaps unintentionally, "built the simplest system of just getting started." + +A second positive: the browser gives Python superpowers for free. Łukasz used +PyScript to convert audio formats entirely in the browser for a friend on a +locked-down machine, noting that "all of this binary operations can be just +successfully done inside a browser." Sai found the browser's sandbox solved a +real security problem: an AI agent generating Python that runs client-side is +contained by the browser (in Nicholas's phrase, "the blast radius is only going +to be your Chrome"). As Sai put it, because it runs in the browser he does not +have to stand up "an AWS Lambda with some hacked-up Python," nor obfuscate API +keys, since the browser carries authentication for him. + +Third, the recent engineering work is landing. Interviewees repeatedly praised +the rewrite, the improved worker support, cross-browser progress, the rewritten +documentation with intentional examples, and the TuftsHub self-hosting release. +Hammad singled out the TuftsHub release not just for what it did but for how it +was delivered: a YouTube video plus a GitHub repo that simply worked. Mark, a +veteran engineer, was unreserved: "I'm able to do real stuff with it." + +## Challenges + +The clearest challenge is the JavaScript and browser boundary. This is where +experienced users get stuck, and it is the point at which we appear to be +losing people. Łukasz described the accumulated, hard-won knowledge of "the two +worlds that you're living in all the time," and was blunt that the rough edges +have not gone away: he has simply learned to "avoid the rough edges, not +because they're no longer there, just because you know to avoid them." +Crucially, he reported a pattern he hears from other Python programmers: "it +works for something simple, it didn't work for something else, I didn't know +what to do." We are converting Python developers on the easy case and losing +people at the next step as they attempt to dig deeper into the browser's +JavaScript APIs or try to use popular Python packages that simply cannot work +inside a browser. + +Packaging and stability came up repeatedly. Kattni hit the wall of C-dependent +packages and, tellingly, the failure was silent: "none of the error messages +implied this library is not supported." Hammad wants version stability above +novelty, arguing "the most valuable thing is your own time when you've set it +up," and is wary of Pyodide's release cadence (Pyodide is the CPython +distribution, compiled for the browser, that PyScript uses). + +Error messages and the blank page problem affect newcomers specifically. The +live session with Anna was the clearest illustration we have: she reads only +the top line of an error and ignores the stack trace, "because there's a lot, +and I know that I don't need to read every single line." Kattni named the blank +page problem directly: "you go to PyScript[.com], and it's this sandbox, it's +open... and I'm like, what do I do?" + +Discoverability and marketing were raised, unprompted, by most of the nine +interviewees. Kattni called it "a perennial problem" for open source. Nitau, an +engineer, found it "a little bit mind-boggling" that PyScript is not more +widely known given what it does. Claudiu had previously produced a full +marketing proposal that went nowhere; despite his explicitly asking an Anaconda +architect for guidance, none came - a frustrating experience we should own +and address (see Theme F). + +Finally, feedback channels are effectively invisible to users. When +PyScript.com crashed, Anna "basically walked away," told no one, filed no +report, and was unaware of any way to give feedback. This is not an isolated +attitude; Hammad described himself as a silent reader who assumed the problem +"might be my own" until we reached out. + +PyScript.com's reliability, which surfaced most sharply in the Tufts case +study, is another major challenge. Chris was blunt that the service "does with +fair regularity" become "ungodly slow," and that when it does mid-lesson "the +class kind of falls apart." He gave concrete casualties: a middle-school +workshop, college classes and company presentations. Because PyScript.com is +unmaintained, our current fix path is to escalate through colleagues and +infrastructure, which "takes 15 minutes to half an hour" - useless in a live +classroom. Anna's and Hammad's crash experiences echo this. + +## Opportunities + +Three opportunities stand out. + +First, a simple, opinionated higher-level UI layer. Hammad described, entirely +unprompted, something extremely close to Invent: "import UI, UI.run," bundled +so that "from pyscript import invent" just works. This is an encouraging +external signal for the Invent direction and work we had to stop. + +Second, AI as the new default route into and through PyScript. It is now the +way people discover PyScript (Nitau found it via an LLM), the way they learn +it, the way they build with it (Claudiu, Momin, Sai), and increasingly the way +our documentation reaches humans at all. This changes what "writing +documentation" means and validates our approach to rewriting our documentation +in Q4 2025. + +Third, partnerships and content. Mark's CodePen suggestion, Łukasz's and +Claudiu's calls for video content, and the repeated marketing theme all point +at the same gap: PyScript is largely invisible in the channels where developers +now learn and share trends and innovations. \ No newline at end of file diff --git a/docs/ux/onboarding_path.md b/docs/ux/onboarding_path.md new file mode 100644 index 00000000..1e21c3b7 --- /dev/null +++ b/docs/ux/onboarding_path.md @@ -0,0 +1,75 @@ +# Theme D: Onboarding - the blank page and the graduation path + +## What it is + +Two ends of the same concern. At the entry end, the blank page +problem: a beginner faced with an empty sandbox and no idea what to do in +PyScript.com. At the far end, the graduation problem: an advanced user needing +to know that PyScript.com will let them grow rather than trapping them. + +## What it means for PyScript + +Enabling a practitioner's growth is a design +responsibility, not something we can leave to chance. Kattni, an educator, +named the blank page problem plainly and gave us the remedy: she does "a lot +better when I have something to tear apart and put back together than I do when +I have to write something from scratch," and asked repeatedly for more demos +and idiomatic examples. This maps neatly onto the friction-free strength of +[Theme A](./friction_free.md): the environment is welcoming, but a welcoming environment still needs +something in it. + +At the other end, Mark, a formidably experienced engineer, framed the +graduation problem in terms of his "architecture is destiny" principle. His +advice on Invent applies to PyScript as a whole: design so that the skills a +user learns are migratable, and "if you're thinking about solving a problem in +a way that is not migratable, then you're bolting people into that +cul-de-sac." Where a cul-de-sac is unavoidable, make it "obvious to you" (the +user) that the dead end is coming, so they can move on deliberately rather than +hitting a wall. Hammad made the same point constructively from the +learner's side: users "can graduate to deeper tooling like UV in their own +time," provided we do not force it on them early. + +A framing Nicholas offered during the Hammad interview belongs here: limiting +a learner's surface area so they grow stepwise (Vygotsky's zone of proximal +development) applies to all practitioners, not only beginners. + +The Tufts case study gives the graduation path a concrete outcome. What Chris +asked for is a tool he can "pip install... and hit run and now suddenly +everything just works", something that "just sits there happily humming away in +the corner like a fridge." That is the graduation path for real: start on +PyScript.com's friction-free loop, then move to a local-first, offline-capable, +self-hostable tool that carries the same capabilities into a GitHub-based +workflow the students are learning anyway. The retrospective also surfaced the +risk at the far end that Mark warned about. Chris, having lived with TuftsHub, +found himself wanting a single window holding files, code and live preview, and +Nicholas was wary of "re-implementing PyScript.com," preferring to take the +question to the wider community rather than quietly rebuild an IDE. The +tension between meeting a real workflow pain and not trapping the tool in a +reinvention is exactly the migratability question highlighted in this theme. + +## Future steps + +Invest in demos and idiomatic, remixable examples as a +primary onboarding tool, not an afterthought; Kattni, Mark and Anna all pointed +here. Make the intended progression explicit: from PyScript.com, to +self-hosting, to full tooling, so that graduation feels like a signposted path +rather than a cliff. Carry the migratability test into Invent's design. + +## Standing across archetypes + +The blank page end is a learner and educator +theme. The graduation end is an engineer theme. Both are really the same +request for a coherent and clearly articulated pathway from first contact to +mastery. + +## Challenges + +PyScript.com is unmaintained and slowly bitrotting, so no +coherent graduation pathway can currently be built upon it. Work on Invent, the +most direct attempt to address the learning journey, was stopped in 2024. A +limited re-engagement was planned into Q1 2026, and, independently, this +research found an unprompted practitioner description of exactly what Invent +set out to provide (see [Section 2](./key_findings.md), Opportunities, and +[next step #5](./conclusion.md#5-get-invent-to-an-early-release-and-validate-it-against-real-users)). Properly +restarting that work is a resourcing and prioritisation decision that sits +above the PyScript team. \ No newline at end of file diff --git a/docs/ux/packages_stability_errors.md b/docs/ux/packages_stability_errors.md new file mode 100644 index 00000000..0f9391e6 --- /dev/null +++ b/docs/ux/packages_stability_errors.md @@ -0,0 +1,58 @@ +# Theme C: Packages, stability and error messages + +## What it is + +Three linked practical blockers: which packages work +(especially C-dependent ones), how stable the platform stays over time, and +whether error messages explain themselves. + +## What it means for PyScript + +These are the day-to-day friction points that +turn an ambitious first project into a curtailed one. Kattni, an educator, +came in with an ambitious idea, hit a C-dependent package, and had to retreat +to "something much more within my wheelhouse." The deeper problem was silence: +"none of the error messages implied this library is not supported. It was +failing in weird ways." We have already responded to exactly this with +[packages.pyscript.net](https://packages.pyscript.net/) and with improved, +documented error messages. Worth noting: this was a direct result of earlier +feedback from Kattni to Dan Yeaw (our previous PyScript engineering manager). + +On stability, Hammad, an educator, made the strongest case for valuing +continuity over novelty. Drawing a finance analogy about teams staying on old +Excel versions, he argued "the most valuable thing is your own time when you've +set it up," and was wary of Pyodide's deprecations and release cadence. He +admired the Xeus Python model of a self-contained conda environment where "the +package [is there] and it works." + +On error messages, the newcomer experience is stark. Anna, a learner, reads +only the line "that looks important", ignoring everything else. She routinely +pastes errors she cannot parse into an LLM "to figure out what it's trying to +say." Her suggestion was simple: she would read an error "if there was an +explanation of what it's trying to tell me." + +## Future steps + +Continue the compatibility-checking and error-message work +already begun. Consider surfacing package compatibility earlier and more +loudly, so an unsupported package fails with an explanation rather than in +"weird ways." Encourage and surface the stability and long-term-support story +for self-hosted and educational contexts, where the pinned, known-good +environment is worth more than the latest versions. On error messages, +prioritise a plain-language explanatory layer on the most common errors, since +this helps beginners directly and also improves what LLMs echo back +([Theme E](./ai_default.md)). + +## Standing across archetypes + +Educators and learners feel this most deeply. +Engineers tend to route around it; Sai and Łukasz, for example, compile their +own wheels when needed. + +## Challenges + +Package availability is largely upstream: PyScript depends on +Pyodide for its packaging story, so compatibility and version churn are only +partially within our control. Error reporting is deeply embedded in how +PyScript works, making clearer errors a significant engineering effort rather +than a quick fix. \ No newline at end of file diff --git a/docs/ux/summary.md b/docs/ux/summary.md new file mode 100644 index 00000000..ffe125bd --- /dev/null +++ b/docs/ux/summary.md @@ -0,0 +1,60 @@ +# Executive summary + +Nine practitioner interviews and a two-call Tufts University case study inform +this report. + +## Findings + +Findings from the interviews and case study: + +* A. PyScript's core asset is its friction-free experience: type Python and + immediately see it run in the browser. PyScript.com problems have damaged + this story. +* B. We win people on the simple use case but lose them on the technical + journey through the JavaScript/browser boundary. This is the key retention + finding. +* C. Package compatibility, Pyodide version churn and opaque errors are the + recurring practical blockers. +* D. Onboarding fails at both ends of the journey: beginners face a blank page + on PyScript.com and don't know where to start; experienced users lack a + graduation path to grow their skills and integrate PyScript into their + existing Python practices. +* E. AI is now the default route into, through and around PyScript. Community + attitudes span the full range of opinions about AI; we should cater to all of + them. +* F. PyScript is invisible in places where developers now learn, feedback + routes are unknown to users, and past community contributions have not always + been honoured - causing hurt feelings and a loss of trust. +* The case study shows PyScript.com's unreliability is disrupting Tufts' + teaching now. [TuftsHub](https://github.com/tuftsceeo/tufts-hub), built in + response, shows what a replacement needs and how such work should be done + (collaboratively placing practitioners at the heart of our development + process). + +## Proposals + +Proposed next steps (for discussion, not commitments; see [Section 6](./conclusion.md#next-steps)): + +1. Migration tutorials, tightened learning pathways and engineering fixes to + address the technical boundary drop-off. +2. Remixable demos clearly signposted as a primary onboarding surface. +3. Continue the package compatibility and error-message work; add a + confidence-building long-term-support story. +4. Make PyScript an excellent citizen of the LLM ecosystem; keep the AI-free + path first-class for those avoiding AI entanglement. +5. Get Invent to an early release and validate it with real users. +6. Fix PyScript.com reliability; ship the self-hostable TuftsHub. +7. Build sustained visibility and repair community trust. + +## An authorial note + +Nicholas planned this process, wrote this report, built TuftsHub, +created Invent, contributed to PyScript and conducted the interviews (with +Jessie). + +This concentration of roles is common in practitioner-led open-source research, +but it should be declared: you are entitled to know that I am reporting the +findings, and have a non-neutral stake in some of the work those findings +support. + +Nevertheless, every finding can be linked back to named interviewees. \ No newline at end of file diff --git a/docs/ux/themes_at_a_glance.md b/docs/ux/themes_at_a_glance.md new file mode 100644 index 00000000..b666d1c2 --- /dev/null +++ b/docs/ux/themes_at_a_glance.md @@ -0,0 +1,52 @@ +# 4. Key themes at a glance + +## [A. Friction-free, all-in-one is the core value](./friction_free.md) + +The zero-setup, +immediate-feedback, everything-in-one-place experience is what people love, and +what makes PyScript viable for learners and educators. It is our strongest +asset and most obvious benefit. + +## [B. The JavaScript and browser boundary is where we lose people](./js_boundary.md) + +The gap +between "works for something simple" and "works for the thing I actually need" +is real, and it sits squarely at the Python/JavaScript interface. This is an +education and retention problem, not just a documentation problem. + +## [C. Packages, stability and error messages](./packages_stability_errors.md) + +Package compatibility +(especially C-dependent packages), version churn, and error messages that fail +to explain themselves are the recurring practical blockers, felt most acutely +by newcomers and educators. + +## [D. Onboarding: the blank page and the graduation path](./onboarding_path.md) + +Beginners need +something to take apart, not an empty box in PyScript.com. Experienced users +need to know the tool will not trap them in a cul-de-sac. Both are about +growing a practitioner via a clear learning pathway to PyScript mastery. + +## [E. AI is now the default route in, through and around PyScript](./ai_default.md) + +Discovery, +learning, building and documentation are all being reshaped by LLMs. This is a +first-class design constraint now, not a side topic - which validates our focus +on LLM-friendly code and documentation in Q4 2025. + +## [F. Visibility, community and partnerships](./visibility.md) + +PyScript is largely invisible +where developers now learn (video, LLMs, sharing platforms), feedback channels +are effectively unknown to users, and past community contributions have not +always been honoured, causing hurt feelings and a loss of trust. Fixing this is +as much about showing up and building trust as it is about marketing or +traditional PR. + +## [Case study: Tufts](./case_study.md) + +Running through several of these themes, and told as a single story at the end +of [Section 5](./case_study.md), is the Tufts tooling case study: the +PyScript.com reliability problem, the three capabilities a replacement must +provide, and TuftsHub, the tool built in response. \ No newline at end of file diff --git a/docs/ux/visibility.md b/docs/ux/visibility.md new file mode 100644 index 00000000..466f5ddb --- /dev/null +++ b/docs/ux/visibility.md @@ -0,0 +1,81 @@ +# Theme F: Visibility, community and partnerships + +## What it is + +The cluster of concerns around PyScript being under-known, +feedback being hard to give, and community contributions not always being +honoured. Marketing is part of it, but trust is the larger part. + +## What it means for PyScript + +Practitioners raised visibility unprompted, +again and again, and often with a note of puzzlement or frustration. Kattni, an +educator, called marketing "a perennial problem" and pointed out that PyScript +"really does fill a gap" that people simply do not know exists. Nitau, an +engineer, found it "mind-boggling" that PyScript is not "incredibly viral," +arguing it should sit in the same mental list as React, Vue and Svelte. The +channels people named are specific and consistent: video content and +YouTube/Twitch (Łukasz, Claudiu), sharing platforms like CodePen (Mark), and +LLMs ([Theme E](./ai_default.md)). + +Two more uncomfortable truths sit inside this theme. First, feedback channels +are effectively invisible to users. When PyScript.com crashed, Anna, a learner, +"basically walked away," told no one and filed nothing, and was unaware of any +feedback route. Hammad, an educator, assumed the fault behind the problems was +his until we spoke. If our most engaged users do not know how to tell us +something is broken in PyScript.com, we are flying blind. Second, Anaconda +has not always honoured past contributions. Claudiu produced a professional +marketing proposal that segmented the audience and set out an approach, and +"nothing came of it," with no alternative direction offered despite an Anaconda +architect being explicitly asked for guidance. Nicholas offered a direct +apology in the interview. + +Mark's CodePen idea is the most concrete partnership opportunity: approach +CodePen about running MicroPython (and PyScript) in their environment, learning +from the earlier Vue integration, so that "every example that you make, you put +on CodePen" and draw people in who do not yet know PyScript exists. More +generally, put PyScript where the practitioners are already found rather than +on a relatively little-used website (i.e. PyScript.com). + +The Tufts case study is the positive counterexample to this theme's harder +truths, and may be a good future model. Rather than an invisible feedback +channel and an ignored contribution, the two Tufts calls show the engagement +loop working end to end: requirements gathered on a recorded call precisely so +"folks can see how we've moved from a requirement to a solution," a proof of +concept (TuftsHub) built quickly in response, a review call to refine it, and +then a deliberate move to open the work up, keeping the repository under the +Tufts GitHub organisation and asking Chris to raise future requests as public +GitHub issues "rather than private Slack messages, so the wider community could +take part." That is exactly the inclusive, in-the-open collaboration the rest +of this theme argues we have too often failed to sustain. The lesson is that +we already know how to do this well; the task is to make it the norm and +mitigate future self-inflicted and thoughtless community faux pas. + +## Future steps + +Build a sustained community-engagement and content strategy, +weighted towards video and towards the LLM channel, rather than one-off pushes. +Make feedback routes visible from inside the product itself; Anna's own +suggestion for hearing about new things was an in-product banner on +PyScript.com, "something I would definitely read," since she ignores email. +Pursue a CodePen partnership and look for similar amplifying partners. +Re-engage deliberately with contributors like Claudiu so that offering help to +PyScript is visibly worthwhile. And treat the Tufts arc as a template for how +requirement-to-solution work should run: recorded, in the open, and refined +with the community. + +## Standing across archetypes + +Visibility is felt across the board. The +feedback-channel gap is most visible among learners and quieter educators; the +honouring-contributions point is most acute for the hobbyist and +administrator-leaning contributors who give their time without being paid. + +## Challenges + +Repairing trust requires sustained cultural change in how +Anaconda engages with open-source contributors, and that change is for Anaconda +to own and act upon. The evidence of the cost is in this theme's body: a +professionally prepared community contribution was ignored despite explicit +requests for guidance, and the community contributor walked away in +frustration. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 0e25058f..ac78b8ba 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -126,4 +126,22 @@ nav: - Developer Guide: developers.md - Code of Conduct: conduct.md - License: license.md + - UX Research: + - Preface: ux/index.md + - Executive summary: ux/summary.md + - "1. Introduction": ux/introduction.md + - "2. Key findings": ux/key_findings.md + - "3. The interviewees": ux/interviewees.md + - "4. Key themes at a glance": ux/themes_at_a_glance.md + - "5. Themes in detail": + - "5a Friction-free": ux/friction_free.md + - "5b JS Boundary": ux/js_boundary.md + - "5c Packages, stability and errors": ux/packages_stability_errors.md + - "5d Onboarding path": ux/onboarding_path.md + - "5e AI as default": ux/ai_default.md + - "5f Visibility and community": ux/visibility.md + - "Case study: Tufts": ux/case_study.md + - "6. Conclusion": ux/conclusion.md + - Appendix 1: ux/appendix1.md + - Appendix 2: ux/appendix2.md - FAQ: faq.md