Onboarding experience feedback + more prominent documentation/manual

First of all… I have to say that my experience with Observable thus far has been amazing! I am somewhat new to Javascript— I’ve started learning it more seriously in Jan 2019. It’s been a really helpful “sketchbook” environment for me and has been such a powerful learning tool. I used it in my coursework with many of my classmates—a swath of collaborators in both undergrad and grad programs at Columbia University. I think ObservableHQ .com has a very special place in the future of the Web, and the Jupyter analogies are a really big step forward for more widespread use. The “welcome” helper module on the logged-in homepage is a great addition.

That said, it has not been an entirely smooth journey, and as powerful and exciting as Observable has been, I’ve observed (no pun intended) a lot of things from my classmates and my own experiences with the app.

Caveat emptor: I am somewhat of a newcomer, but I believe many newcomers are prone to the following mistakes and misconceptions that come with learning a messy and historied ecosystem like JS in 2020.

1. The onboarding experience/“hidden dependencies” in prerequisites

– See " @sliminality/ply on GitHub for the reference on “hidden dependencies”

Most of the people I know who used Observable came to the app wanting to learn D3 and to create data visualizations—after all, I used Observable in my courses for data vis (alongside Tableau) and data science (alongside SciPy+Jupyter, R). However, it’s not entirely obvious for new users that “learning D3” requires() expertise in a boatload of pre-requisites: Javascript, HTML, CSS, SVG, (maybe even Canvas), and even ObservableHQ** itself, which behaves similarly to but is not identical to Javascript.

To make matters slightly more confusing for newbies, the article title Observable’s not Javascript suggests that learning Javascript =/= learning Observable and minimizes the importance of learning Javascript in its title—which might be the only thing a newbie reads.

This “learning path” problem might be solved with a more robust onboarding experience, or even an article on “how to learn Observable”— but in its current state, the onboarding experience from 2019–now may still be too daunting for users with extensive data science/statistics experience coming from non-Web backgrounds.

An aside on potential difficulty in searching for Observable examples/articles on Google: I point out the naming since most people I know in school (myself included) use Google search queries like “observable update without redrawing mapbox”, which often results in things related to RxJS—an entirely unrelated library which, by inclusion of “Javascript,” may mislead some newcomers to peruse the wrong documentation. I know this sounds ridiculous and silly from an experienced user’s perspective, but I do find that Google searches on obstacles encountered when using Observable yields results for RxJS, MDN articles, and “observer pattern” articles.

I’m not sure the best way to clarify these distinctions for newbies, but for what it’s worth, I suppose I’ll be telling friends to always include “observablehq” as a string in their Google searches on Observable.

… searching for help is related to another note:

2. Difficulty in finding help

Since joining Observable in mid-2019, I only recently realized that the “Help” button and the user forums are tucked neatly in a drop-down menu of one’s user icon on the top-right corner. Me nor my peers realized that there was [a more structured learning path in the form of “featured notebooks”]Observable: The User Manual / Observable / Observable — which is also available in the secret help menu mentioned above. I never thought to look there because I was never concerned about managing my profile/account as a student—I just wanted to play with notebooks and work on my assignments.

Learning to look for featured notebook examples has been the single most helpful pattern that I’ve picked up in trying to learn Observable— and I think super newbies may not learn this pattern, since most other libraries/tools have a sort of centralized knowledge hub for learning that Observable sort of lacks. In its current state, I think Observable’s learning schema is more decentralized, since learning Observable’s features and applications is an experience of juggling various instructional notebooks from staff members and power users. This is an exciting form of community, but it is more uncommon amongst peer software communities and tools.

Perhaps there is a more common place to place help docs/manual links—such as the bottom of pages, or even as dedicated menu items. For ex: other tools I use (and others in my academic program) use commonly all have Documentation/Help/Manual -type links in their headers, footers, or both. ggplot, Python, pandas, RStudio, Vega-Lite, etc…

I think it can be easy for experienced users to say “just keep learning more,” or to dismiss this audience as not the target users of Observable, and thus disregard the above feedback.

But I find that many people I’ve met who work on fantastic projects in the urban studies and social sciences have expressed utter confusion over
Observable’s identity as a programming platform and its learning path. Many of my peers (who prioritize tackling their domain-specific questions over learning a programming platform) just stick to Python+Jupyter or RStudio for the clarity in finding help, getting started quickly, and the perceived shorter time for a productive start.

Addressing these concerns might even quell some doubts on [the tight relationship between D3v5+ and Observable, which seem to frustrate a lot of users (see the post “I want to learn D3. I don`t want to learn Observable. Is that ok?”). I don’t want to point people away from using Observable—I think it has a lot of transferrable knowledge and is amazing in itself— I just feel that Observable in its current form could be greatly improved with a more structured learning schema that is immediately available to newbies—something like an Observable syllabus or “roadmap” that allows users to see the “big picture” as well as the connections between Observable’s dependencies, domain-specific applications, and pre-requisities.

Thank you for taking the time to take in this feedback and for working on such a powerful and inspiring platform and community. I’m excited to keep learning Observable, make more cool notebooks, and engage with the data vis community through Observable!

Edit: I couldn’t make 2+ links as a new user, so apologies for the lack of hyperlinks in my references. Also, about me: I recently gradated from my MS urban planning program at Columbia; I love HCI/user-centered design, the Web, cities, and data vis and am looking for work in that world, so let’s connect if you are looking for people! :slight_smile:


I just want to say THANK YOU. This is a very well thought out set of observations and suggestions. We really appreciate the time you took to write this down and share your experiences. We are definitely looking into these!