Babylon.js Ease of Use

Questions
41

We are working on fewer clicks, keep you eye open for PR for docs.

Can you help here?

42

I think babylonjs is the default, which is the product developed in the production environment,

43

Just according to the learning background and learning roadmap, babylonjs should launch learning paths for different development groups
For example, front-end engineers use babylonjs to develop 3D business
How do traditional game engineers use babylonjs and how to develop 3D business
Web3D is a new field for front-end engineers

2 Likes
44

cc @RaananW about SEO

45

I used to manage large SEO and Adwords campaigns for companies. These days only coding + UX/UI Design, but can definitely help with Babylon homepage. (Do not want to promise the entire site, because I do not have much free time).

5 Likes
46

None of the XR examples in the document supports the WebXR device emulator browser extension. I think this makes novices doubt their life. It’s better to give an example of xrweb simulator

1 Like
47

I thought @RaananW addressed this one not long ago ?

48

Yes I did. Did it stop working again? I’ll check that in a sec.

1 Like
50

Just checked, everything is rendered correctly, but then I read again what you wrote, and I guess you meant that the playground itself doesn’t support the emulator correctly?

The playground you pasted is the physics playground. Click the left button (i.e. “squeeze button”) and the scene will reset. right one will shoot spheres from your right controller. The only thing that is missing is the teleportation, which you can enable if you force it to work with the main button. This is a limitation of the emulator that is stating it has a thumbstick but doesn’t let you control it.

2 Likes
51

Just chiming in with some random commentary here, since I have spent quite some time working on technical documentation and also with novice programmers/CS students… maybe it will be of use, after all.

Let’s first take a look at the front pages these open source projects:

We can see that both Node and Docusaurus have optimized for getting people started as fast as possible, with the “Getting started” tutorial link being the first (and most prominent) thing featured on the front page. There is information about what the project can do for you, and lots of additional resources, but the focus is clearly on making the new user experience as smooth as possible. Electron has succumbed to a bit of bloat here unfortunately, but it still does feature the “getting started” section on the front page, where it can be found by just about anyone.

There’s also a quickstart project people can simply clone from GitHub and get started with making changes for both Electron and Docusaurus; it does introduce some additional complexity by requiring new users to blindly use yarn or npm but overall it’s almost impossible to not see a working example application within minutes (not one hour). Again, it “just works” and you don’t even have to think about it until you’ve had time to see what it does and how it can be used in the most basic of cases.

BJS on the other hand focuses more on wowing users with all the amazing things it can do. While that is understandable, it can only be the first step, and the very next step should be to get new users started ASAP. Nothing like following up their initial thoughts of “Wow, this looks awesome” with “… so how do I get started?” to sour the first impression. Why is there a mention of specifics like WebXR and HDR files, that only a subset of potential users will even know what to do with, when the most pressing concern of all new users would instead benefit from having a big fat “Getting started” button that is impossible to miss instead?

Going by my own experience, as well as having observed multiple people try to use some or all of these projects with no previous knowledge (but some years of programming experience), the approach that Node and Docusaurus take has BY FAR provided the most painless experience, compared to most other projects I’ve encountered that didn’t focus on the initial bootstrapping process as much. You want your users to feel like Ii “just works” and once they’ve passed the initial hurdle, it will be much easier to take additional steps.

I will admit that BJS faces some issues here, because there are many different contexts where it could be used. The best way to deal with it is probably to let the user decide: They know if they want to make a website with 3D features, or a standalone app/game. If there was a simple app that you could clone and within 2 minutes you get an Electron app with BJS installed, that shows the cube/sphere examples when started via npm start that would go a long way. For browsers, you might need to include a simple webserver to serve the webpage and mention that this is only a substitute for the real-world website they’d be using, but otherwise there’s no reason the first steps couldn’t be similarly straight-forward.

Another issue that is very prevalent in the BJS docs is that there is no explicit mention of the knowledge required, meaning as a new user I don’t know if this topic is appropriately difficult for me or if I still need to do some reading up (and what concepts I must learn because they’re silently assumed). The simplest, and in my experience most effective solution, is to always add a brief “Prerequisites” section where the fundamental terminology is listed, and links are provided to either other parts of the documentation that may be required reading, or external resources.

In a similar vein, there should always be a “see also” section where people can go to documentation pages for related concepts or “advanced” topics that build on what they have just been reading about. I think this already exists on some pages, but it’s probably worth considering the structure of the documentation as a whole in terms of “how can we effectively link related information so that users make the required connections?”. This is crucial because learning involves forming connections between related knowledge, so if there are gaps (and they can’t just be filled by googling, because you don’t know what to google for…) then there will never be a complete understanding.

Lastly, one important thing I want to draw attention to is that there are multiple different types of documentation that serve different purposes. Mixing them into one giant documentation soup is problematic because it means people are confused, they can’t find the information that they need, and worst of all they will feel like it’s their fault and that they’re just stupid (usually, at least if they’re inexperienced). Needless to say, that isn’t exactly fostering motivation, and the fact that the documentation for most open source projects is like this isn’t a good reason to keep it that way.

Depending on who you ask, the exact categories may differ slightly, but I tend to use these four:

  • A tutorial or “getting started” section. Target audience: New users. Goal: Get them to have a first positive experience, by setting up a working example ASAP and then let them either play around with it, or guide them towards the more advanced topic if they so choose
  • An assortment of “recipes” for solving commonly-encountered tasks (no matter if they’re simple or complicated). Target audience: Everyone who wants to solve a specific problem, that isn’t so specific it hasn’t conceivably been solved before. Goal: Provide examples that surpass the initial tutorial in breadth and scope (and often, difficulty) so users have a starting points for their actual task
  • A technical reference, where APIs, classes, design patterns or anything else of relevance is listed. Target audience: Intermediate to advanced users. Goal: Provide specific technical details to those who need to look up specific information, to be referenced frequently and usually out-of-order
  • A detailed explanation of concepts, design decisions made, trade-offs or background information. Target audience: More advanced users who seek to broaden their understanding, possibly future contributors. Goal: It should be possible to understand everything about the code by cross-referencing these explanations (and external resources, if need be) with the existing artifacts of the work that has already been done, even in the absence of the actual development team (!)

One key thing I’ve already mentioned before is that these need to be extremely easy to find. Users will probably always know what kind of documentation they need in a given moment, but they usually won’t know where it is due to how different projects may structure their documentation differently. In my experience it is best to be as explicit as possible and “don’t make users think”, which is just basic user experience design AFAIK.

Since it’s already too long and this likely warrants further investigation, let’s just take a brief look at the documentation front page:

  • There is a lot of text I can only describe as “intro blurb” (no offense!). As a user looking for specific information, I don’t care that Babylon is “powerful, beautiful, simple and free” or even that it has “one of the world’s most amazing development communities behind it”, I just want the information I’ve come here to find. IMHO this isn’t too harmful but certainly unnecessary as it increases the signal-to-noise ratio
  • There is seven (!) subcategories and it’s not exactly clear which ones will be the right one to answer my question. It’s important to keep in mind that we humans have tiny pea brains and can’t remember more than a handful of items after reading through them, some resources seem to claim the number is as low as 3 or 4, but certainly somewhere below 3-9 is where we just can’t keep it all in short-term memory (unless it happens to be related information, in which case it is grouped and treated accordingly). So here it’s not necessarily the number of categories that are problematic, but rather that there is some intersection between them and also that it’s not really clear why the separation was made the way it was, i.e. some are clearly just references and others are a combination of recipes and tutorials with some references mixed-in
  • The fact that there is a section in the documentation about how to use the documentation should speak for itself. This is completely silly and hints at a much larger issue (worst case), or it’s plain unnecessary (best case) depending on whether you think the current structure of the docs is good or bad
  • The getting started portion is at the very bottom, where chances are good new users won’t even see them before clicking on one of the other links that are immediately in their view. It’s also somewhat redundant since the first link already links to the “getting started” part of the documentation?
  • Then there’s “coming next” which implies some sort of sequence, but is actually just a bunch of related links that may or may not be relevant depending on the user’s goals. It’s also displayed in a list, but depending on your layout it may be arranged in such a way that you can’t read all of the elements without scrolling. Plus, it’s not instantly recognizable as a link, it looks like an image if you try to drag it, no hover effect, poor contrast of the font text with the white-ish background, and of course the BJS icon adds no readability here, while it does take up screen estate and it can also visually distract the reader

Apologies for the in-depth commentary and I hope no one takes any offense, because it is not intended as such! I love working with BJS and participating in the community, but since this thread is about the new user experience and that is always a pet peeve of mine, I felt like I should at least try to add to the discussion.

8 Likes
52

Thank you for some inciteful observations, there are many good points to consider, some requiring more major changes than others. We in the middle of discussing some changes to the documentation though not a complete rewrite some will be in line with your suggestions. We could well come up with a list of tasks. Should you think any of the tasks are ones you would and could go along with would you be willing to undertake some of them.

For example from your list

As part of the metadata for each page there exists a further reading section which links to either internal or external pages. You could look to see how you might use this to link information across the docs.

This also relates to this

and the coming next reference you made. The image to use is picked up from the linked page’s first image or one stated in the metadata. No images on the page the BJS icon is used as default. As images help to break up text on a page any one interested in adding relevant pictures to text only pages very welcome.

3 Likes
53

@rdw1 - First and foremost NO offense taken at all. The depth of your thinking AND the kindness/graciousness in how you present it makes it clear that you have the best interests of this community and platform at heart.

I have to personally thank you for starting your thoughts by recognizing that everyone comes to Babylon with different experiences and different goals. This makes the overall documentation design process quite a challenging one.

I think you raise a TON of amazing points and thoughts here. Please know that we’re actively in discussion about how to move the needle on this topic…from possibly reorganization of the docs, to adding new docs geared towards specific types of learners with specific goals.

We’ll absolutely be keeping these thoughts on our minds as we carry forward.

I really like your proposal for the 4 categories.

  1. Getting Started
  2. Recipes
  3. Technical References
  4. More advanced topics

This is a nice way to categorize and simplify the breadth of the documentation. Something we’ll definitely be thinking about.

Lots of great thoughts here. Thank you again so much for taking the time to share them.

Cheers!

6 Likes
54

I didn’t read this as a question at first, my apologies. If there’s something simple enough a dummy like me can do, I’ll be happy to assist :slight_smile:

The missing images might not be a big deal, I just figured that icons are normally used to make finding information easier but in this case they don’t really help (since they’re mostly the BJS logo). Inside of the individual documentation pages, they can of course help illustrate things, but whether using those images as “icons” improves anything is something that would likely have to be experimented with.

Speaking of experiments, I think it would be supremely useful to have some data on these topics to make more informed decisions and identify what the biggest problems are. Off the top of my head, here’s a round of (quite possibly very silly) questions that I couldn’t answer with just my intuition:

  • How many (new or existing) users prefer to read in-depth vs. just try things “at random” if they don’t know what to do? Do they want “book-style” guides, or “out-of-order” references? Maybe both at different times?
  • What are the parts of the documentation that are understandable vs. which parts are the most confusing? Why are they unclear? Missing information? Lacking prerequisites? Poor writing? Lack of illustrations/playground examples?
  • What even are the user groups BJS wants to serve and what are their motivations, goals, etc? How well do they “feel” like they’re currently being served (by the documentation)?
  • How much “handholding” in terms of surrounding infrastructure (npm, typescript, etc) would particularly new users expect? Is this unreasonable, i.e. putting too much of a strain on the team or could be achieved with possibly some re-prioritization? Should this be something BJS needs to worry about at all or are external references sufficient for the average user?
  • Which features of the framework are people most interested in? Which ones are the most complex ones, that people feel might need special attention in the docs to be explained clearly?
  • Which features or topics in general cause the most (repeat) questions on the forums?
  • What kinds of posts can generally be answered just by linking to the docs or forum posts vs. which go unanswered or can’t be answered to the users satisfaction? (This might be difficult to determine, but if the info exists and can’t be found that is a different problem than it simply not existing anywhere in the docs, and if it exists but can’t be understood that hints at yet another, very different problem)

Again I’m mostly focused on the “new user experience” here, since it’s the topic of this thread, but I’m sure a lot of issues could be uncovered in the process of investigating those types of questions that may affect intermediate and veteran users, as well.

55

Listening to feedback is a great starting point, but it’s also equally important to look at the analytics data. In marketing, it is a well known fact that in order to maximize conversions, you should pay close attention to what people actually do.

The discussion here are very insightful indeed, but it’s lacking data. For example, what keywords (aka search phrases) do people use the most when they arrive to the homepage? That user intent should be the deciding factor when it comes to redesigning the homepage (or any page on the website).

For example, if the most encountered keyword is 3D visualisation on the web, then indeed focusing on wowing users first is more important than Get Started button.

The reason big frameworks like Node.js, Electron.js focus on get started first is because their main audience’s intent is to begin playing around with the code (since by the time they arrive on homepage, most likely they have read about the framework somewhere else, and they are devs - most dev prefer hands on approach than typical wow-me-first approach).

3 Likes
56

i just wanna drop in that over the last 6 months or so I’ve found there is a Microsoft mdn saturation of Google search results with stuff about reverse kinematics that is interfering with a lot of my searches. none of which are about ik

57

u wut m8

58

lol. sorry over the last six months, my ability to Google useful stuff about bjs has become more and more saturated with useless (to me) results about inverse kinematics (and some other basic topics), which are all on mdn.

a year or so ago, my search results were more or less what i expect from such an ecosystem.

now I’m constantly battling Google to find anything.

1 Like
59

This is an excellent point, and also what I was trying to emphasize in my second reply: If there isn’t any data it’ll be difficult to decide what should actually be done, in terms of actionable changes and their expected impact.

The suggestions I made are otherwise focused on making it easier to get started, based on the difficulties described in the OP (thesis), and given from a developer’s point of view. Since I don’t have any other data, those ideas might as likely be terrible as they are great if that’s not something you want to focus on.

That said, keywords alone can also be problematic: Wowing users might be more important if you need (want) to convince stakeholders to adopt BJS, but making it easier to get started is more important if you want to focus on a great developer experience. There’s a bit of a strategic decision involved here, but at the end of the day these aren’t mutually exclusive and you could still have both :slight_smile:

1 Like
60

If it turns out to be a split case (half of the users are Managers/CEOs, and another half are devs), then a common approach is to have multiple CTAs (call to actions) at the top, splitting the screen into two sections, like what marketplaces usually do. Something along this line:

For Decision Makers | For Developers
----- [Live Demos]-----|–[Get Started]–

My point is, it should be a holistic approach.

Be flexible like fluid, strong like ice, and light as steam. Be like water, my friend.

Something along that line, as said by Bruce Lee :wink:

1 Like
61

I would suggest something officially maintained for this new ES6 world. Much like create-react-app that hides away all the scariness of webpack, webpack-dev-server (or whatever local server) and having startLocal/build commands all set up. With the same type of option to eject the configs for advanced users. Also bootstrapping them with a basic setup / example scene to go off of.

1 Like