Site Redo (cumbersome to use)

[tim-montague]

Hi Babylon team,

I know you guys have redone the site a few times (based on what I’ve seen in the YouTube videos), but it’s still not easy to use. And I really do appreciate all the hardwork that you guys are putting into Babylon, but I need to be critical for a moment.

If the Babylon team hadn’t rewrote the code with Typescript, then I probably would not have taken a closer look. And it’s definitely the website. I will often visit websites, and if they don’t sell me in the first 30 seconds then I leave the site. It’s not on purpose, it’s just how my brain is wired. I probably visited the Babylon site 15 times before I actually even got interested enough to dig deeper.

These things actually drove me away…

1. The dark blue, orange, and gray color scheme is not attractive. The dark blue really bothers me. The header should be a lighter orange, or white, or black. And the grays need to be different too. Might seem silly, but color schemes really play a factor in me wanting to use software.
   

   

2. I can’t return to the main page (https://www.babylonjs.com) from the docs (https://doc.babylonjs.com) or the forum (https://forum.babylonjs.com). It drives me nuts, because it’s naturally how people navigate back to the main page. Even if they are under different sub-domains, the expectation for the user is to go back to the main page when they click on the Babylon.js logo.
   

3. The docs (https://doc.babylonjs.com) are not well organized. When a developer visits the documentation page they want to see the API. Three.js organizes this much better (three.js docs). This is how I would structure the documentation page:

   • Getting started: simple instructions on how to npm install, and import the package. No full blown tutorial, because the user isn’t ready for that adventure yet.
   • Animations (topic)
   • Audio (topic)
   • Behaviors (topic)
   • etc…

• Basically the topics under “Diving Deeper” are the reason I’m even visiting the documentation. The link that says “API” is nice too, but I need the API grouped into topics like “Diving Deeper” does, so I can learn why the API methods exist in the first place.
• The current “Getting Started”, “Guided Learning” sections, and “Playground search”, are all nice - but I’m not ready to begin building an entire world when I don’t even understand the basics. These are good references for when I need examples when I get stuck. But I don’t really spend my time on tutorials, because it’s often not something that I want to build.
• The “Getting Started”, “Guided Learning”, “Playground Search”, “Tools and Resources” should all be under a section called tutorials (or playground).
• The “Utility Functions” under “Tools and Resources” should be grouped with the topics to which they relate (animations, audio, meshes, etc).
• The “What’s New” section is a bug change list. That does not need to be in documentation, and can instead live on the GitHub page.
• Most the “Extensions” should be apart of “Getting Started” (not the tutorial version, but the one I’m recommending), importers and exporters are basic needs during the bootstrapping of the system.
• Sections under “Extensions” like… “Tree Generators”, “Mesh Writer”, “Dynamic Terrains” should actually be grouped with the “Diving Deeper” topics.

4. The hamburger menu on the main page, doesn’t even open when I click on it half the time (might be because I use Safari, but that shouldn’t matter - should be basic HTML). Not sure why the most important links are collapsed in the first place.
   
   Likewise the topics on this menu are also oddly arranged. “Tools”, “Get”, “Release Notes”, “Learn” all provide redundant links to the docs. And then there are multiple links to what is clearly marketing material “Ecommerce”, “Games”, etc. which could all be grouped together under a marketing section.

Anyway, don’t mean to be critical. But thought the feedback might help.

[labris]

@tim-montague

When a developer visits the documentation page they want to see the API.

This logical assumption seems to be either subjective or just incorrect.
When a developer (or other person, it is not necessary a developer) visits the documentation page, they want to see the documentation - and they can see it.
When developers want to see API they just visit API section, that’s all.

@tim-montague

Three.js organizes this much better

The lack of documentation is the constant of three.js from the very beginning.
There is still no full API documentation at three.js website, and documentation itself is unfriendly to beginners.

[sebavan]

Adding @PirateJC and @RaananW

[Deltakosh]

And @PatrickRyan for design

[Deltakosh]

@tim-montague

When a developer visits the documentation page they want to see the API

I challenge that a lot. I totally disagree as being myself a developer

[PirateJC]

Hey @tim-montague,

Thanks so much for taking the time to share your thoughts. We genuinely want Babylon.js to be great and useable for everyone, so we welcome feedback like this on how we can make it better and more useable for everyone.

First let me start by saying that we look at absolutely everything that everyone suggests with an eye towards curiosity and growth. If we can make meaningful changes to help everyone then we ABSOLUTELY will.

I do have to point out the idea of perspective. You have a clear, and well articulated perspective about what you’d want to see as a developer and are able to communicate that clearly. We love that! It is SUPER helpful data.

The problem here, is that not everyone shares the same perspective that you do. Sure we could change the colors of the site and change the documentation to include the API sections more deeply integrated into the various sections, but we MUST ask ourselves if everyone would share the same perspective? What is the most helpful to the MOST amount of developers.

When it comes to the documentation, the recent reorganization of the documentation was done with the careful data gathering from a number of creators, from beginners to experts. The documentation is designed to take a person who is BRAND new to Babylon.js on a journey from learning the basics to learning the advanced…one topic after another. And so we have a path that is geared towards those folks. Now our HOPE is that for the more advanced user or the person who likes to explore on their own can still do so to their heart’s content.

So to sum up, thank you very much for your thoughts and for sharing them with us. We will look at them carefully and look at what’s best for everyone who comes to this platform.

Second - Please keep in mind that, while valuable, you have 1 certain perspective and we need to balance the needs of an entire community.

Thanks for your thoughts!

[shaderbytes]

the guys have definitely done something right in regards to SEO because I normally just use one google search to jump right to the docs page i want , and it is mostly always the first returned result from google.

eg search “babylonjs node api” and it returns as first result :

Node | Babylon.js Documentation

search “babylonjs light api” and it returns as first result :

Light | Babylon.js Documentation

search “babylonjs PBR api” and it returns as first result :

PBRMaterial | Babylon.js Documentation

Those are API examples , what about diving deeper? well try this :

If i search “babylonjs light diving deeper” it returns as first result :

Lights | Babylon.js Documentation

Not exactly on topic but I think related to some things you talk about. Google in this regard is the fastest means to get to what you want in the docs.

[Deltakosh]

@raananw deserves all the credits for that

[PatrickRyan]

@tim-montague I will also take a moment to describe the process for the creation of our color palette. You can see our style guide for information about our identity and color palette as a whole. We will be expanding our style guide as needed as as time allows, but we have set out this simple baseline for our identity system that we are adhering to.

I understand your feeling that the color palette is not attractive to you and that UI has an impact on your desire to use software. In effect, most users will gravitate toward an experience that fits their aesthetic so what you said is not uncommon and is always something at the forefront of any design effort.

When we started our redesign efforts for the branding of the engine, we went through a long process of hundreds of sketches and revisions to land on the form of the logo. For the color palette, we started with the color palette from the last logo to inform our choices. This is because one of the hallmarks of branding is that changes to a brand cause insecurity, distrust, and confusion which can cause a drop in sales as your customers don’t recognize your product. So any efforts to rebrand are always a cautious process.

With that in mind, we started with the colors used in the previous identity system and chose colors that invoked that original palette. We went though numerous color palettes with an eye toward very important concepts such as legibility, contrast (inclusivity), and color harmonies. The base colors chosen for the logo drove the rest of the palette.

Any design effort will realize that not every member of the audience will be happy with the final design choices, but we make efforts to not make choices that we “like” but choices that “work”. Using objective reasoning, and often making choices that don’t align with the designer’s personal aesthetic because those choices fulfill a requirement like an appropriate contrast value means that any design system is full of compromises. And in the end, we strive to communicate effectively making sure that whenever someone views content our branded content that they have no question that they are looking at our brand. This means consistency in our use of our identity.

We are a little over 2 years into this new identity system. We will expand our style over time, but we also need time to establish our identity system as making changes often incurs all of the fears of the audience again. We do take all feedback into account, but do give more weight to objective feedback like our color palette is not inclusive (i.e. not enough contrast for someone who is color blind to be able to use our site) over subjective feedback about aesthetics. This is because in most cases we will find voices who do not like the aesthetics of our identity system no matter what we do, but if we hear a majority of our audience commenting on aesthetics we would certainly address that.

I hope this make sense and gives some light to the design process behind our identity system.

[tim-montague]

Thank you for the responses.

While my feedback is subjective, it’s based on my 6 years of experience working as a designer and developer on internal teams that build the customer-facing webpages at Tesla, Google Developers, and Apple. So I hope I’ve learned something about web design, web development, and consumer psychology.

Documentation

The statement "When a developer visits the documentation page they want to see the API" was meant to illustrate the directness of getting users to the core content provided by the API (Animation, Behaviors, Cameras, etc) - not to literally give the API without documentation. Similar to this “fundamentals” section on this Three.js page. Not sure if anyone has seen Grid Garden or FlexBox Froggy, but when a user visits the documentation, there could be a way to interactively walk them through core topics (topic by topic), and teach them the API. For example, “Meshes are such and such. Here are API methods used to create meshes. Can you create a cube mesh? Can you create a sphere mesh? Congratulations you’ve completed the Mesh topic”, then they are guided to the next topic “Cameras”. Interactively taking the user through step-by-step, so they aren’t getting lost in all the content. You can even set up A / B testing to see how users learn and engage with the content, to better focus on what to teach.

Color Theme

From the style guide, that Patrick (@PatrickRyan) shared, the logo color theme looks okay to me. The issue I have is with the black, on dark blue (#2A2342), on dark purple, on gray (#6E6259) backgrounds which are not defined in that color theme. Not sure a user with monochromatic (or dichromatic) color blindness can discern between the sections, when it’s hard for me.

(https://www.babylonjs.com)
Black, Dark Brown, Dark Blue…

(https://doc.babylonjs.com)
Dark Blue, Dark Gray…

There are quite a few color theme tools out there - Material Design or Adobe, which can help with picking analogous or complementary colors on the wheel for these background sections, if the original color theme does not offer enough colors.

Other feedback

• The YouTube videos have been getting better over the last year. But videos at 20 minutes are too long for me. It’s much easier for me to watch videos at 5-8 minutes. I also enjoy when David (@Deltakosh) covers performance features (he seems authentically excited about Instances, Thin Instances, etc). Jason (@PirateJC) is entertaining and good with tutorials (but also perhaps a little less excitement is needed at times). Lastly, the “new feature” videos are good - 4.1 and 4.2 videos get you super excited about the features, but again the excitement level is a tad much at times. Not sure how other users feel here about the excitement level being a bit too much.
• The forum is good (some clunkiness in navigation, but guessing that’s inherit to the use of it being 3rd party software)
• The mantra to answer all comments quickly (under 48 hours?) is good
• No complaints with SEO, also agree this is good
• The actual javascript library is pretty good, but (1) the common use of var statements in code (which are hoisted), when everyone now uses const and let (which are block-scoped) drives me a bit nuts; (2) the clunkiness of providing both Async and Sync methods in the library (which has a very Node.js feel) should simply be one promise-based method for which users can async / await the promises if they like, (3) like THREE, the all caps on BABYLON that prefixes each and every command drives me nuts - developers don’t really use the caps lock key - it’s just Babyon… not sure if this is from OpenGL convention, but certainly not a javascript convention, (4) there are far too many different ways to load assets - should just be a single method called SceneLoader.Load(), that figures out for itself what the user is trying to load.
• Babylon runs better than Three - my older CPU sweats when running simple Three code, and has no issues with Babylon.

Given that - I haven’t been using Babylon for very long, so I most likely will have further feedback in a couple months. Again this isn’t to be critical, it’s because I want to see Babylon continue to gain in popularity.

[Evgeni_Popov]

Regarding the javascript library, don’t forget Babylon exists for 8 or 9 years. At that time there were no const/let keywords nor promises.

We use const/let in new code and update some old code from time to time when we need to touch it but we didn’t make a full pass to update all var to const/let, which would be a very big endeavour.

Because we don’t want to break backward compatibility, once async methods have been added, the old sync methods remained.

As for the namespace being all caps, I think it’s a common practice in the javascript library land, at least before es6/imports existed (again, Babylon is 8/9 years old).

[torminator]

First, kudos to @tim-montague for having the courage to give constructive criticism on the website.

Some thoughts from me, I’m a fairly “senior” (as in both age and experience) developer, but a rookie at Babylon, just a couple of months into the webgl world.

The color theme didn’t stop me from getting into and staying on the site, so I think that’s a minor issue (although I’m sure the esthetics could be improved).

I have also more than once found myself clicking on the Babylon logo to go back to the main site, and then realize that just took me to the root of the sub site. This could be improved.

I have several times found interesting doc topics I needed to come back to, but after navigating more and maybe leaving the site for a while, I struggle to find the topic again. The help feature normally helps, but there’s something not quite right about it. It might be the menu structure and/or menu item names. Or possibly a missing cross reference which for instance shows all places “camera”, “mesh”, or “lighting” is discussed.

After reading/browsing the main docs enough times, the API pages become more important and I think they have the biggest potential for improvement. I would give API pages the entire screen real estate and replace the doc menu on the left with an API menu structure. I would change the sorting within the namespace, classes, etc from vertical to horizontal. It drives me crazy to visually navigate/scroll down the left column and then have to scroll back up to the top of the middle column and start over. I find the redundancy between the main body listing and the right side listing confusing. I would like to see clearly when/if inherited members are included in the listing (“is that all, or do I need browse to the base class too?”). I’d love to see a high speed (client side) filtering mechanism so that only the class members I’m interested in are displayed.

When it comes to the API content itself, I understand it’s takes effort and time to improve, and that I can contribute to this myself. A few improvements come to mind though. One, please add more links from API descriptions to code examples, tutorials, and playgrounds. Two, what is the difference between Properties and Accessors? I haven’t ventured into the Typescript world yet, and find myself scanning both sections when I’m looking for something. Three, please make navigation symmetric! When I click the link for a class member it might take me hundreds of lines down the page, but when I next click the back button, it does not take me back to the class header where I started (which means, if I’m on a mobile device, that I have to manually scroll up to the top again). Four, and last, API member descriptions which add absolutely nothing to the doc are frustrating when I’m trying to learn how everything works. For instance, the “Inputs” member under ArcRotateCamera (and possibly under its base class, but that’s not clear) is described as “Defines the input associated to the camera.” When reading this, my brain goes “yes, I get it, but what exactly is an input?”

Overall, Babylon is great, and I’m looking forward to going live with Babylon-based 3D product configuration/visualization on our e-commerce website in the near future.

[mawa]

Good Day @tim-montague,

First, let me quickly state here that I’m happy to see that I’m not the only one making long comments on the doc and overall usability of the BJS framework in 2021. I assume this is because you are considering using the framework for your clients in the future. I assume you did this because you have ‘the feeling’ or ‘instinct’ that things are going to/need to change for the future Internet and for consumer/user interactions. I did this ‘exploration’ and ‘assessment’ phase in 2020. And I did come to some conclusion, including regarding the doc, the com, the support and the community.

I’m also an ‘oldie’ just like you @torminator . I’m not a pure dev. I’m not a ‘pure’ anything, in fact;) Originally, a digital designer from the time digital design started (yes, I’m that old:( Also, I’d usually rather manage the devs and the overall project. But I do have a basic to average knowledge of many frameworks and codes. I also have 20y XP in com, corporate com and digital com (strategy, CX, UX, UI).

Although I find your comments interesting as per organizing/categorizing the content in a way to better ‘catch’ the newcomer as well as to provide easier access to info on project building; Although, I do also agree that things such as eCommerce (which for me could become a boost for rapid growth and should be better considered (or even better considered)…Although, overall, I agree to your comments && appreciate the time and effort you spend to investigate/evaluate AND share… Well, let me put it this way:
“Time is of the essence and the time is now”

@PatrickRyan

but we make efforts to not make choices that we “like” but choices that “work”.

The team (incl the com team) will probably (most certainly) have to set priorities for the upcoming months. I don’t feel investing time in the ‘cosmetics’ of the doc is at this very moment a ‘must have’.
I’ll leave my comment to just that and high level.

If anything, I think it is now time for BJS to ‘speak’ BJS. If anything from the doc and inspector and API (terms, names, methods), @RaananW @PirateJC " I’d like to see improved ‘consistency’, eliminating ‘frustration’ and ‘confusion’. "

And a last comment for this thing about the API being the entry point for a dev coding a project. I am the same as @Deltakosh . I’ve worked with dozens of very skilled developers (also settling new code/framework). I’d say the API doc is often the last point you reach, when you are desperate to understand why your code/method is just not working.

Edit for my API comment: *…except of course if you are creating or managing an API/end point or any other backend purpose. In which case, you know what you are looking for and the information is there even in the worst of API description, since always. At least, ENGs mostly got this part right over the previous decade;)

[dunk]

Hi @tim-montague ,
Well done for taking the time to comment on this. It’s not always easy to sumarise such subjective thoughts.

Since the Babylon team seems to like feedback, here’s another data point.

TLDR:
I would love a simple sitemap where as few of the menus collapsed as possible so i can see all the options at a glance.
I would love such a sitemap to be linked from the Documentation page /and/ the Forum page.
With this i could get anywhere in 2 clicks.

I can’t say i have an opinion on the colour scheme. It does not make any difference to me finding information so i don’t care.
Just my opinion. I’ll leave this one to more artistically minded people.

Site navigation.
I also regularly find myself trying to click between site elements, only to have to give up, open a new tab and start typing which usually lands me back at babylonjs.com.
This is all bad enough on an actual computer.
It is horrific UI on a mobile device.

I do not find the hamburger link at babylonjs.com intuitive at all.
As an experiment i just tried to find my way back to the documentation from here. I t went something like this:

• Open new browser tab.
• Start typing “baby…” until i can click on the suggested babylonjs.com.
• Click the hamburger link and read all the headings. None look immediately obvious for documentation so start clicking.
• “Community” maybe? Nope.
• It’s probably one of the first ones… “Tools”? Nope.
• Read the whole list again. Ah. Maybe “Learn” near the bottom? There it is: “documentation”. Disco.

I’m quite dyslexic so don’t tend to remember how i got there last time. I go through this dance every time.
I challenge the Babylon Devs to find an external Dev who does not know the documentation and watch over their shoulder while they try to find the docs.

The elements i care about:

• Forum
• API documentation
• Other documentation

The links between API and Other documentation are adequate.
I would like there to be a links between Forum and Documentation so i can navigate between the two without having to go through the main page.
Failing that, i would like there to at least be a link to the main page from the Forum and Documentation pages.

Documentation layout.

3.1
First up, i think the API layout is adequate.
I’m usually reading it on a laptop so i do wish the actual content i am trying to read wasn’t constrained to a silly scrolling section which costs me 1/3 my screen real estate but the actual /navigation/ here is fine.

3.2
Other documentation.
Yes, i agree here in principal it’s not always easy to find the exact topic i am liking for
but accept this is a hard one to fix.
The current layout has a similar layout to what you might see in a paper book.
The down side of that is the sub-topics are hidden so there is a lot of clicking to try to find the exact section.
Again i challenge the Babylon Devs to watch someone that does not know the layout in advance try to find a particular topic in the minimum number of clicks.
Then get them to try the same on a mobile platform.

There are a few broken links as well.
If it was my project, i’d probably run a crawler over the site, looking for broken links and broken playgrounds.

I accept that all this is just my opinion. I’m just providing a single data point.
That said, you could fig 80% of my frustration quite easily:
A link to a flat sitemap that does not collapse any of the menus. This sitemap would be a simple list of links to the various site sub sections.
Link this sitemap in the header of every page.
With this i could reach any sub section of the site in 2 clicks.

I’d also like to see a separate sitemap for the documentation.
With all the sub-menus expanded i could use the browsers search functionality if all else failed.

[mawa]

WoW… I can feel the emulation with all those (incredibly long and constructive) feedbacks… something is in the air, just something…

[JohnK]

As someone who contributed, in a small way, to the new docs let me add some thoughts. There are always going to be differences of opinion about how the docs should be structured. Especially in an open source project the focus of the core team will be on developing the source itself. Luckily the Babylon.js core team will listen to suggestions and will take them on board. In the case of the docs changes were made in light of previous comments and the fact that volunteers where willing and able to discuss what the changes were going to be and undertake them. Coding for the new structure being the major undertaking and brilliantly achieved by @RaananW.

There was a philosophy behind the changes constrained as usual by time and the amount of existing pages. Of course people might prefer a different philosophy or a different way of structuring with the same philosophy, again it depends on the volunteers implementing it. The philosophy was to move from an adventure game type docs to a book type docs and to try to make it accessible to a range of users including designer, developer, experimenter and total beginner. The home landing page gives some indication of which section might be useful to you. Whether or not we succeeded depends on your expectations and prejudices.

Given that the new docs are just that, new, there are not going to be any major structural changes. However the docs are open source and anyone who has suggestions acceptable to @Deltakosh and the team are very welcome to implement them and submit a PR. Before considering some of the suggestions in this topic note that they require more than just a simple edit. To demonstrate that the suggested changes work it would be a good idea to do what they docs team did when updating the docs. That is fork the site and use Netlify or other similar to demonstrate the changes.

Please note that my skill set is not up to implementing the ideas below. Doing them would require anyone wanting to make the changes to have the time, inclination and skills to do them.

Color Scheme
For reasons already given it is unlikely that it will be changed. If anyone wanted to try, it might be possible to produce alternative schemes that a user could select for their local use. Perhaps even a method of customising your local color scheme.

Sitemap
At one point I had the wild idea of using Babylon.js to produce a campus with buildings designated for different types of user. For example a designer building that you entered and different rooms and floors led you to different docs pages. Each building would have a getting started reception area tailored for that type of user. More conservatively no reason that there should not be a sitemap as described by @dunk just needs someone to take it on.

API
This is the area I am most in close agreement with these comments

@tim-montague

the API grouped into topics like “Diving Deeper” does

@torminator

replace the doc menu on the left with an API menu structure

For anyone thinking of working on these aspects of the API some important things to note

1. The API needs to stay up to date by ‘reading’ the Babylon.js source code and comments to produce the API.
2. Currently the ‘reading’ and API doc production is achieved using Typedoc. Can you use Typedoc or know a better way?

@torminator

please add more links from API descriptions to code examples, tutorials, and playgrounds

This one is more accessible for contributions to the API using @see in the comments.

Babylon.js needs you

[mawa]

@JohnK

The philosophy was to move from an adventure game type docs to a book type docs and to try to make it accessible to a range of users including designer, developer, experimenter and total beginner

I do adhere to ‘the philosophy’.

[mawa]

Out of my reach and expertise, but I will like and try push this anyway. This could help in the future.

[PirateJC]

Just wanted to say thanks again to everyone for the feedback.

While there is a lot to digest here and think about. It seems like there is a little bit of low-hanging fruit that we could make changes on fairly quickly.

The one that seems to stand out the most is people getting lost between Babylon.js, the Docs, and the forum. Being able to easily navigate between these important pages seems really important and if people are getting lost, that’s a problem.

Give us a little time to think about how best to solve this, but this definitely stands out as the first thing we should solve.

Thanks again all for the feedback

[JohnK]

@PirateJC

Babylon.js, the Docs, and the forum. Being able to easily navigate between these important pages seems really important

Easy navigation yes, clicking on logo and going to a different site, even if Babylon.js related, rather than home page of current site I would find very annoying.