Doc suggestion, for new users

Hi. This new doc is awesome, but I found something maybe strange, maybe wrong placed, I don’t know how to call it. Let me explain
The previous version of doc had a first page very similar to github readme, which I think help us ‘to catch’ the begginers in the babylonjs world, and now I feel like it is missing. It took a little bit for me to find ‘from where I can get the library…’ It Is in API/Diving Deeper/Develop With Babylon.js/Framework Versions or NPM, which to be honest it is not exactly what I expected.
I understand ‘Getting Started’ section is important, but I think before should be something like ‘How to start’, I mean from where I can download it (cdn/ npm- like github readme) and a small copy-paste demo explained (which can be this) After that if I want I’ll search for more informations in the doc, tutorials, github
Other reason is this… I saw a demo, …somewhere, I found it was made with babylonjs, now I google for it, …I found the main site, but here is no reference on how I can use it -the framework- (directly say do this and this and done,…if you want more, you have to learn, ask, etc). Same in the doc, we directly tell him to lear, whitout showing him a demo which to use directly in his app with as few clicks as possible
Again, this is a suggestion :yum: It is like a Wingnut post, but with bad english :rofl:

1 Like

From my point of view Getting Started section should be much shorter and describe just all necessary steps to begin quickly use Babylon.js - like it was in old Docs.
All examples are better to put in tutorials, being in the beginning of menu the are a bit confusing.
But for tutorials we need much more expanded section with more examples: how to build different applications.

Let me add @PirateJC who will for sure be intereseted in this feedback. But be patient, as he is in vacation until Jan.

1 Like

Hey all! Just getting back from some time away.

First off, thanks so much for sharing your thoughts on the new docs. Creating documentation pages is extremely tricky, because you have to design an information architecture that works for everyone. From the seasoned expert, to the brand new beginner.

@MarianG - I hear what you’re saying about missing the starting page that helps direct you to where you want to go if you’re a more experienced user. I’ll do a little thinking on that. No solutions yet, but I’ll spend a little time wrapping my head around the problem.

@labris - great point here for sure. The new getting started section is a re-imagining of the old Babylon 101. It’s something that we felt could work well for people who are JUST getting started with both Babylon.js and perhaps even web development. It’s definitely not for everyone, but we felt like we needed a place for the absolute beginner to start. Not saying it’s perfect, but hopefully it is a little more welcoming and informative to the newbies.

Anyways…thanks for sharing your thoughts. Keep the ideas coming. You’re definitely giving us more to think about for sure!

2 Likes

When I briefly used Babylon.js last year, the setup process was very straight-forward and featured prominently on the front page of the documentation site (Babylon.js Documentation). Now that I am revisiting the engine with all new documentation I’ve decided to run through the entire tutorial series. I’m trying to approach this as if I were a complete beginner to game/web dev, not only to learn the engine but to help identify any knowledge gaps the documentation leaves. I am only pretending to be stupid I swear :crossed_fingers:

I hopped into Chapter 1 hoping for a setup tutorial, but I got thrown a block of code right away. I see that it links to a playground example after another unexplained code block, but if I were a beginner I think this would be confusing. It’s smart to do the tutorials in the playground but I really wanted to get my “real” setup figured out before starting the tutorials. I searched and found this page hidden in one of the guided learning tutorials Getting Set Up | Babylon.js Documentation but it only presents one way of setup with NPM + ts. It does not tell you what NPM/ts are or how to get them, which has confused at least one person so far Npm install --save babylonjs

I know there are other ways of using Babylon.js so this immediately stopped me in my tracks. I have never used NPM and it seems weird to use a package manager when adding a script tag is so easy. Is this the only “correct” way to set up the Babylon.js environment now?

I see that I am not alone who still miss the clear and understandable introduction, like it was in old Docs just at the frontpage (you may see the older version here - https://endoc.cnbabylon.com/ )
The new version is hidden and seems to be a bit more difficult for beginner to understand how to use it. In old Docs there was very basic example with the code which you can copy-paste; now one needs to combine several lines of the code from the Getting Started page or check the source code from the examples.


In picture above (from old Docs) one could just copy-paste the working HTML. Now it is not so evident, because if you’ll copy-paste the code from Getting Started - Chapter 1 - Setup Your First Web App | Babylon.js Documentation template, you’ll get the empty canvas, which could be a bit frustrating for beginners.

This picture from old Docs was maybe not of a good quality but very informational for beginners too:

1 Like

Maybe at the beginning of the “Getting Started” section there should be a short paragraph explaining how to follow along at home, and a link to a more fleshed out installation/setup guide for the more advanced users. I would write it myself but I’m unsure if I even have my own environment set up correctly :sweat_smile:

As a person who was part of the team involved in creating the new docs and the author of the getting started section I am obviously biased. That doesn’t mean to say I don’t think that improvements cannot be made. It is interesting to note that the comments about the new docs all come from users of the old docs.

Some thoughts on the construction of the ‘Getting Started’ section. Since we can have no idea of the background, expertise or interest of a new Babylon.js user any attempt to write for them must be based on some assumptions. Our starting point is that they will be interested in creating 3D models in some form on the web. As such they will have various degrees of knowledge about and interest in coding models, designing models and using the web to display their models, with more than a beginners level of understanding of JavaScript and HTML. Chapter 1 attempts to cover the basics of these areas for a new user. You could argue that these are in the wrong order but an order needed to be chosen and

  1. You can build scenes and models with Babylon.js
  2. You can use Babylon.js to display models built with Babylon.js or other software on the web
  3. You can use Babylon.js to import and use models built with other software
  4. You can use Babylon.js to directly build scenes and models on the web

seems logical.

To pick up on some specific points

An assumption on my part that having read the previous pages of chapter 1 a user would understand that they could add their code into the setup template at the positions described to create a working their basic setup. Also assumed that users would know how to find and view the page source for the two linked webpages giving a working setup. Will add and clarify with the code for a complete working setup.

My italics - debatable but will add something more at the start about the playground being the place to experiment with Babylon.js before moving onto you own HTML set up.

Note API not need in above path. There could be room for a further page or pages within /Diving Deeper/Develop With Babylon.js that describes a more fleshed out setup/installation guide.

There was a deliberate effort to move away from the ‘adventure’ type style of the old docs to a more ‘book’ style and so there are generally many fewer links between pages. However where needed they can be added using the further reading system in the metadata and links to more on settup from the First App on the Web page to other such pages does seem to be possibly a good place to add them. What do you think @PirateJC ?

At one point we did talk about producing a 3D campus type model using different blocks of buildings for different types of users that you could use to lead you to the appropriate pages of information you needed. Perhaps this was going too far but an interactive 2D system of better quality than the picture mentioned to guide you to what you were looking for in the docs could well be useful. Anyone want to produce one?

2 Likes

Sorry, I made a bad assumption about the target audience. My remaining point is that it would be useful to condense the various install/setup methods onto a single page, describe the benefits of using one over the other, and make that page easier to find than they currently are. I’m still wondering whether I should go with the NPM/TS route of setup or continue with my old-fashioned script tag, and that makes me a little anxious (Yes, I am a millennial :crazy_face:).

Seems that here are too much assumptions :slight_smile:
Not all users are comfortable with page source viewing, and it seems a bit strange when one has to see the page source in Getting Started section. The simplest solution - just to put the source code to the page, as it was in old docs. It will not make any harm but only good.

Well, new users have no chance to see the old docs, so they have nothing to compare with. But “old users” remember that some things in old docs were more intuitive or more comfortable to work with.

Here is my story as a new user.
Several years ago our client asked us to publish in the Web 3D model which we’ve made for him.
Inspite the fact that I’ve created more than one hundred websites in my life I’ve never did 3D Web before (we produced usual C4D renderings) so I start googling.
First I came to Three.js. I spent there maybe 4 or 5 hours reading, coding and trying to understand what I need to do in order to load and demonstrate GLTF model - but with no success.
After this I came to Babylon.js. After copy-pasting the initial setup example from Getting Started I went to the GLTF file loader doc page, copied relevant lines and pasted to my example - and, miracle! After 10 minutes (reading time included) I had working example; and, because the Babylon.js documentation is really clear and understandable, after just a week I already published my first demo at the Forum. Since then I am here :slight_smile:

The point is that with the new Getting Started section I would spent not 10 minutes but much more time to find the basics. It is not so evident for new users now, believe me :slight_smile:

As always I just want to thank everyone for their passion about this subject. As you can all see/guess, finding the right approach to teaching people about this amazing platform is not a simple task. Mainly because as @JohnK elegantly points out, we have no idea what a “new” person coming to these docs is like. We don’t know their experience, we don’t know their comfort level…we don’t know anything about them.

There are some wonderful points here.

@labris and @Knar - What I’m taking away from your comments is that there’s still some work to do to get back to the simplicity that each of YOU as individuals found with the old docs. Especially in your initial interactions as you began your Babylon journey. I love and respect that perspective and we should find the right way to action on it!

@labris I think what you have clearly communicated - with the idea of having a code block that people can cut and paste and see a 3D models quickly, is wonderful. And getting that further up front and early in the doc content is a great idea. It’s simple and easy. Let’s do it!

Couple of thoughts goals for how we should approach it:

  1. It cannot distract from the Getting Started tutorials. Those tutorials have been expertly crafted by @JohnK and I believe they are incredibly useful for a large group of new users to Babylon. That being said, I recognize it’s not ALL users!

  2. Let’s create a new page that is COMPLIMENTARY to the Getting Started tutorials. Credit goes to @JohnK here as he introduced this thought early on in the redesign process, but it may be that we need to have 2 (or eventually more) paths for people in Getting Started. Let’s have a first step be a new page within Getting Started, that is Simple, and focused on the copy/paste html template for people who learn best by just starting to hack away. On this page: Welcome to Getting Started with Babylon.js | Babylon.js Documentation we will expand it to indicate that there are 2 paths here for people to choose from…a curated tutorial path (with link to Getting Started Chapter 1) and a “let me start playing around path” (with link to this new doc page).

@labris - Since you have the clearest perspective on what resonated so well for you when you were first starting with Babylon, can I ask you to take a first pass at this new page? It does NOT need to be perfect, I’ll be happy to massage and edit it for you. It just needs to be simple and to the point for people who learn like you.

Lastly - on the note about the “choose your own adventure.” aspect of the old docs. Yes that graphic was very helpful to some people, but it was also immensely overwhelming to others. This is where it gets REALLY tricky to teach people of all different types of backgrounds. We have made an intentional choice to move to a more linear teaching path with the docs. This path does not impede anyone who wants to learn at their own pace, but simply structures the information in a more linear fashion for those that might previously have felt overwhelmed by the presentation of the information. Hopefully you can see that this is an effort to try to reach both of those types of learners. We are ALWAYS open to conversations about how we can improve this, but the mostly positive response we’ve gotten to this new structure, points to us having landed on something very meaningful for the community at large. Hope this all makes sense.

Keep your ideas coming, they are wonderful and cherished even if we don’t act on every one of them.

Thank you all for your continued support of this awesome community and platform!

Each of you rocks!!!

I’ll think it over and will provide some example soon. I think we may call this section “Basic setups” and, maybe, it will be enough just to rewrite a bit this page - Getting Started - Chapter 1 - First Web App | Babylon.js Documentation

By the way, it seems that there is no difference at abovementioned page between First App and First Coded App.

Another imporovement which would save a lot of time for all of us - the possibility to restrict the search with API only (simple checkbox will do it).

I have made some changes to the Firsts chapter along the lines I indicated in my last post, including adding code into some templates. I have submitted these as a PR.

First app loads the box, the First coded app uses direct code building of the box. This should be clearer after the PR.

This is done by using the ‘Search’ at the bottom of all the menu items, clicking on this brings up a search box with an API only check box

I hope it will be clearer :slight_smile:
I am not sure that the term “model” is good for the box mesh.
It would be clearer if mentioned, that the first example loads GLTF model with just one mesh in it, and the second example builds the same mesh with Babylon tools. It really helps to understand it much more quickly.
(and I wouldn’t say that it is “rather uninteresting”) :slight_smile:

As for API search - here are the steps which one needs to do in order to search:

Let’s say, that I am at API page. In order to find something in API I need either use Ctrl+F (given that I am at the right page atm) or load the Search page. Then I need to check API checkbox. After the search I open the link to API page… and the cycle begins again, I need open the search page again etc.
It would be simpler and more intuitive, if we would make either the API search field just at the top of API pages, or include API checkbox to the main search field. It will reduce clicks and page loads, as well as some confusions.

And, by the way, for some reasons there is no footer at Doc pages. Adding the footer may help to show a lot of important additional info and links.

Once PR has been accepted happy for you to have a go at any rewording. It might be virtually the simplest possible but technically the box is still a model.

Can see your point of view about API search and possibly a footer however it would not be me doing the work so pass over to @PirateJC and @RaananW

1 Like

I cannot disagree with that; still we are writing the docs not just to be “technically strict” but in order to help people, so some extra explanatory words would be not useless.

And of course, if you are like me and not a coder, something understandable by a modeler. As for the start up tutorials, it was nice to see my name in the “Off Site Tutorials” :slight_smile: I have no compliants even though I have yet to understand all the differences between “var”, “let” and “const”.

My biggest compliant are the playgrounds. When I do a search of playgrounds on a specific topic, I seem to find a lot of broken playgrounds Often with a big red bar at the bottom. Drives a non-coder mad!

Stay Safe All, gryff :slight_smile: