Hope it will be well documented 
Did we fail in the past on that front?
I’ve spotted a PR in draft for the documentation a few days ago on GitHub. You can peek around too 
Honestly? 
I think we should start an initiative to ask the community to provide real life examples to the docs.
The getting started and the demo projects are too old and absolutely doesn’t reflect how powerful babylon.js is!
I would consider to rewamp the menu in the docs. For example my students were struggling even to find how to create a cube.
I’m on phone so just a short answer but I believe we should open a wider debate about the docs. Involving the newbies and the pros as well.
Once there was a question by the team what do we users would like to see in the docs more precisely documented. That time it was not realised.
EDIT:
Let’s do something like this:
https://threejs.org/examples/
1 Like
Just my opinion, but I often think “Why is that in here?”; e.g. if I want to learn about feature x, I do not need fancy lighting, shadows, 5 particle systems and a GUI spanning 400 lines of code.
But oh well, I have managed
Maybe it is the nested structure: Features → Deep Dive → […real docs]?
You mean like replacing MeshBuilder.CreateSphere with CreateBox in every default https://playground.babylonjs.com ? Give them an F 
I knew the material and geometry editors from Blender. If I remeber correctly, I never read through the docs. I learnt by rebuilding graphs (I extracted e.g. from a 5 hours youtube video on time code 3:34:44) and then googling for smaller concrete issues as they arose.
In Babylon editors I remember, occasionally, having difficulties knowing which node types fit together.
1 Like
We already redid the doc 3 times. It is never perfect for everyone and at the end a waste of time as everyone has a different opinion.
My stance is: As long as you can find (at some point) what you need we are good. For the rest we have the forum
1 Like
Yes, I know about these examples (I accidentally clicked on this icon so many times when I was trying to close the webpack’s multiple error overlays 
), but if we could make it more clean it would be cool, like this:
And the icon should be a call to action icon, let’s make it more visible.
I personally find the 3js one terrible;D And this is my point: nothing will satisfy everyone
And for the record this is how it looks like to me:
1 Like
Don’t get me wrong though: If you have a better idea or a suggestion to improve, let’s do it but we already did it 3 times and here we are
1 Like
Ok, I get it. Let’s flush this idea 
1 Like
You know what we really need? Beautiful demos. More stunning demos. We are far too technical
5 Likes
Old good demo scene…
1 Like
Fwiw @roland I wrote an 400+ page book to cover the docs between the Getting Started and Diving Deeper sections and I still only managed to scratch the surface! 
4 Likes
There is a whole thread by @CodingCrusader Coding Crusader's doing all sorts of fancy demo stuff.
Speaking of which: come on most of us indies are working hard and showcasing our stuff here: Demos and projects - Babylon.js
Chiming in here.
First of all let me say how much I appreciate the input and passion around the docs. I know it all comes from a place of wanting Babylon to be the best that it can be and making it as easy as possible for people to pick up and start running with.
As @Deltakosh mentioned. Written docs are an incredibly difficult thing to get right. On the forum, we get this same conversation that pops up every 6 months or so. The reason Documentation Organization is so difficult is because people are different. Each one of us wants the docs to look and feel like the way that would best cater to how each of us learns…how we want to consume information. The way the docs are currently organized woks for some people and doesn’t work for others.
In the past 5 years we have done 3 complete overhauls on the organization of the docs. Each time we’ve done this we have many folks praising the changes, and several others suggesting it missed the mark.
To take this discussion to a slightly different direction, I might suggest that the future of written documentation is probably NOT the way that we want people to learn Babylon.
Something we’ve been thinking a lot about on the dev team is does the emergence and acceleration of LLMs change this landscape at all? Is there a future where, when it’s time to learn Babylon, instead of turning first to the written documentation, instead you turn to your favorite LLM to learn Babylon. In this world, what role does the existing written documentation play?
I want to be clear, we are not actively working on an LLM that helps you learn Babylon, but I’d be willing to bet that just about everyone on this forum has dabbled with LLMs in their code-learning journey.
We have to acknowledge the fact that Generative AI has changed the landscape of “learning.” With this in mind we need to be thinking about the future of the role that documentation plays in this emerging future.
Apologies if that takes the conversation in a different direction. Just wanted to share what the dev team has been talking/thinking about in regards to this space.
4 Likes
Sorry I meant it from a doc stand point
1 Like
I had a thought that it would nice to link to forum posts in the docs. Essentially trying to get to a point where the community can kind of update docs (or links within docs) and not require pull requests. Meeting quality criteria could be a concern.
But to stay (somewhat automatically) updated would maybe require a few rules like “clearly state the applicable/tested version that the forum post references.” A flag on the forum post indicating whether it is still applicable, easily toggled by trusted users. And the flag indicates if that forum post appears in the docs. Another flag might indicate whether it needs updating for current docs. A couple of my posts, I think, might be appropriate to link from the docs. I’m still wading through the contribution requirements and pending my github setup to issue PRs.
A similar flag system (especially “needs updating” flag, might be appropriate for playgrounds, too.
Hey ideally I love that idea but it seems tough to build (We are not owning the forum code, it is a paid service). But my preference would totally go to everyone feeling empowered to do PR to fix / improve docs
1 Like
I personally find the docs fantastic and easy to traverse. The featureDemos (Babylon.js Feature Demos) could use some organizing though.
3 Likes