doc.babylonjs.com v2.0

[GameMonetize]

Hello all,

 

I will start with Temechon a new version of the documentation site. I would like to gather here all things that you would love to have I cannot promise that everything will be implemented BUT we will do our best.

 

I'll try to keep here a list of must and nice to have:

 

Must have:

• Website available on Github to allow community to work on it
• Deployment from Github to Azure directly (for my convenience ): http://azure.microsoft.com/en-us/documentation/articles/web-sites-publish-source-control/
• Mobile version
• Better visual design
• Resizable TOC
• Empty page should be redesigned
• Empty page in Classes should display the list of classes (For instance clicking on 2.0 should display all classes from 2.0 and so on)
• Ability to deep link to all headers inside a page
• Ability to deep link to any function inside a class page
• Fixing some display bugs like http://doc.babylonjs.com/page.php?p=25073
• Display inheritance and children in a class page
• Better (and faster) search
• Correct class-hierarchy (Node -> Abstract Mesh -> Mesh , for example)

• Syntax highlighting for javascript

• For admins : Display differences between two pages in Pending validation

• Short sample code for each class member functions

 

Nice to have:

• Ability to move page from one section to another
• Ability to see page's history 
• The tutorial's date updated in front of the author

[Temechon]

- Syntax highlighting for javascript

- For admins : Display differences between two pages in Pending validation

[RaananW]

• Doc generation from source code (where applicable  )

Better (and faster) search

Correct class-hierarchy (Node -> Abstract Mesh -> Mesh , for example)

Ability to see page's history 

[GameMonetize]

@Raanan: Documentation is already generated from TypeScript files

[Dad72]

• Short sample code for each class member functions.
• The date of the tutoriels updated in front of the author.

I love, for example, Unity3D documentation that is simple and allows you to learn quickly. I think it might be a good source of inspiration.

[benoit-1842]

I think more youtube tutorials (videos) will help a lot. Like example, building a game from scratch and those tutorizls should follow along the documentation.... If you want an example of the best system of tutorials ever, you guys should be inspired by cycling74 max\msp.... You should seriously take a look at there documentation section, it's very clever to teach us a complex programming language.... But thank you for babylon.js it's doing in a certain way the job I want to do but I want to pass to an another level without having to relay everyday with the user forum.....

[RaananW]

@DK - sorry, wrong formulated :-) What I meant is that a kind of Doxygen-style documentation can be automatically generated, to prevent seeing this - 

@return {BABYLON.AbstractMesh} mesh under the pointer/mouse cursor or null if none.

and instead see a link to the abstract mesh class and a correct return description. 

[jerome]

documentation :

I would like for each class / method a link to the github file (line would be perfect) so we can understand what the method does if the doc is not complete.

It would better that the function/property names would sorted in alphabetical order within their own sub-section : properties, instance methods, static methods.

 

In the doc, it would be nice to have the last edition date (and maybe a edition number) with the author, instead of the author only.

 

editor :

For the editor, some little features would be very appreciable :

• either an auto-save every 1' with the ability to retrieve the current draft version
• etiher a manual draft feature : the user could save/re-edit its draft many times when editing and send it to validators only when complete

A better editor send process management (I get many times "the server has goofed" and I must save locally the markdown text before re-submitting later)... maybe something to tune in the POST request handling server side ?

 

It would be nice also, for the user who has edited, to have the ability to see/edit his pending submitted version while waiting for validation. We sometimes (often) notice that something important is missing or wrong and we need to correct it. For now, we have to wait for the validation and only then to edit back the validated text, fix it and finally re-submit it.

 

I would prefer a slightly different markdown parser (the same as github would be great) : the current one for instance needs two spaces at the end of the line to generate a <br/> and sometimes, if we copy/cut the markdown text for local save, some ending spaces are chopped so we need to re-format the text afterwards.

 

A set of menu buttons (SEND / PREVIEW / CANCEL) in the bottom of the web page would be nice also.

[jerome]

related to some other post : http://www.html5gamedevs.com/topic/14380-a-closer-look-at-babylonjs-tutorialoverview/?p=81976

 

Well ...

What did these guys do : http://threejs.org/docs/

 

They sorted everything in the API doc, not from the point of view of the code hierarchy, but from the point of view of some user thematic.

What is very clever, imho, because the incoming user (the newbee) doesn't need to understand first how the framework is internally organized (code hierarchy) : it's more usage oriented than BJS doc (my opinion only).

 

A framework is a tool : the final user, unless he then becomes a contributor/developer, only needs to understand how to use it, not how it works under the hood.

We do a little the same in the tutorial parts : successive thematic parts. But when the user has to go further than what he just learnt in the tutorial, he then faces the API doc... which is no longer organized on themes but on the internal code hierarchy.

I understand many people can give up at this point ...

 

Imagine now our API doc was sorted the same way our tutorials : scene, basic shapes, lights, positions/rotations, textures, etc

The user reads the tutorial, learns the basics, then starts his own code, comes to the API... and accesses the classes/methods he needs with the same approach he just did with the tutorial. I guess he wouldn't leave then

 

Just my opinion.

 

I know writting docs is really hard and time consuming. It's complex, it needs PG examples (btw the PG is THE real big BJS  side tool success imho) to illustrate things and so on. But it's the key to keep and attract new users.

The next step is a book (a primer) . Here's an example about lessmilk, one of the Phaser contributors, who wrote a primer about Phaser last year : http://blog.lessmilk.com/ebook-sales/

This was then the first outcoming book about this framework(at this moment, everyone said : the API changes too fast, it's not fixed, etc, etc). People yet all bought its book and it attracted many many people who couldn't read the generated API doc what was at this time as "confusing" as ours .

[Temechon]

I don't like the Three.js doc to be honest, I don't find it very detailed. When you want a specific class to check if a specific attribute exists, you have to check the code by yourself => not very easy.

 

Maybe we should define the target of the babylon doc: do we want an exhaustive list of all class ? If so, how can we sort all these classes ? Today, the class list is automatically generated from the Typescript definition file (but still a manual action to launch), so the class list is sort the easiest way: by parent-children relation.

 

Or maybe do we want a semantic list of classes (like Three.js did) ? If so, how to generate automatically the list of class ? I think it should be a manual process to be created by a contributor, somehow like Wingnut did with the class list.

 

@Jerome : I'm trying to write a book, I don't know if it will be as successfull as lessmilk, but who cares ? I'm having fun xD

[Dad72]

This book is in French Temechon?

 

I had thought myself to create a great tutorial for beginners on the website "openclassrooms" (formerly 'site du zero'). It can ultimately create a book with the tutorial. Made a tutorial on this site and it will do a huge advertising BabylonJS and attract many people. 

 

http://openclassrooms.com/ (multilangue) You can find all kind of tutorial. I learned programming in my early here.

 

The doc ThreeJS is not so bad, one quickly finds what one seeks. Do you know the doc Unity3d ? she is really well done

[Wingnut]

If I could "inject" a few of things from my wish list...

 

1.  User-comments with each edit they do.  "About this edit" - a line of user text that can be seen by curators... in the Pending Validation area.  Also, "About this New Document" for non-curator document creators.  Curators have auto-validate for the most part.

 

2.  Top-of-folder dynamic menus wherever possible... generated from the contents of THIS folder.

 

3.  If possible, 2 portals/styles to the site.  One similar to current way, one that looks like a Commodore 64 Programmers Manual table of contents.  (Like a book.  Mostly for wiki documents/tutorials, not classes.)  This could be the e-book mentioned above.  It could have a different url, but it still uses data from BabylonDocs.

 

4.  Ability for ANY users to query Azure BJS db from HTML docs.  (if possible)  See #5.

 

5a.  I would love to see urls like basedomain/abstractMesh/Mesh/showBoundingBox/ ... return something usable to offsite folk writing html pages anywhere.  These returns need to be wrapped in basic html, ideally with id attributes and a link to a stylesheet... probably located at the originating site.  This is related to something we used to do in the old days... node-serving (kind of a Ted Nelson transcluding thing, rtb).  But this works best on XML tutorials, and not so well on .markdown tutorials.  sigh. 

 

In the old days, we could parse-out one or many xml/html nodes (elements) from a document returned FROM ANYWHERE ... retrieved by the XHR object.  Then XHR got all clogged up with permission problems.  Now it seems you need to retrieve "node" documents with IFRAME, and it is difficult or impossible to harvest nodes from the iframe sandbox.  Maybe clone.  Dunno.  Follow all that?  You're amazing!

 

5b.  Each "section" of our tutorials... could be stored in a DB.  For example, we have about 10 types of cameras.  Depending upon the "query template"... the user could retrieve a document with ONE camera, or a document with all 10 cameras.  User could view a doc with one light, or all 4.  The tutorials would be "assembled" when requested.  Each light... each camera... a db record, and the database could be edited via a web form.  Heavy.  Dynamic tutorials.  Phew.

 

6. XML instead of .markdown.  (likely impossible and folks would surely hate editing it... maybe.  It would need a nicely-written hide-the-xml web form)  Then, we can style the xml, so we get colors, and fonts, and and and... pretty stuff

 

7. Drag-able vertical bar between sidebar and main viewer.

 

I love all the suggestions, so far.  (not mine, but the rest of them are great) 

 

Can we "evolve" the current site... instead of re-approach?  *shrug*  If not, we're going to need a crowd-funding system.    Thanks for listening.

[jerome]

"Commodore 64 Programmers Manual "      

[JCPalmer]

I echo the following must haves:

• Mobil version - Does that mean a topic larger than the display will scroll on an iPad?  I just bring it up if not.  Also header takes up a lot of space on a small device.
• Resizable TOC - Test on mobile.

I just got a doc account today.  I wrote a section I committed to, but no longer think it should be in lights, the requested spot.  Picture of, tacked onto bottom. Where should I put this?

 

This brings me to a thought that the whole tutorials sections looks like a random note of stuff glued together (probably because it was).  I think it would be better if the more advanced stuff was underneath its respective intro section in the TOC.  You need not link down, but now if you have a general idea of needing something in Materials, you can drill down in TOC, rather than look in 4 spots.  Finally, not sure all these numbers add value.

 

My LayerMask section:

[GameMonetize]

I agree with Temechon, I do not like the 3js doc. I find it worse than ours.

 

And because you all have great idea, I started a .md file on the repo. Please send PR:)

https://github.com/BabylonJS/Babylon.js/blob/master/documentation%20v2.0%20-%20wish%20list.md

 

Don't be shy!

[jerome]

Guys, when talking about API Threejs doc, I don't talk about the content, its pertinence or whatever ...

But only about its organization only.

 

They chose to display API entries by themes, not by code hierarchy. It's surely a manual process rather than a generated doc.

I try to hear thus what some newcomers say : "The tutos are great, the PG is great, the forum is great, reactive, responsive... but then, when we need to go further, it's hard to find an old answer in the forum and even harder to understand the API doc because we can't find anything the same way we did with the tutos, etc. So we leave".

 

I don't keep the Truth.

I can just hear feedbacks.

 

Is a thematic oriented API doc better than a generated one ? I really don't know.

 

I, personnaly, have sometimes difficulties to find things with our API doc. So I mix : forum search + google search + API search ... and I often read the code in github (when I know something exists !)

 

I notice the Pasher guys evolved from a generated API doc, last year, to a mixed one (thematic entries, then generated doc, now : https://phaser.io/docs

I like this mix : the global display is organized by feature themes (not code classes, could be done manually once), then you get to the classical generated relative doc.

[RaananW]

I think the API/Classes/Functions/Whatever-you-want-to-call-it documentation and the turotials/how-tos should be generated differently, not using the same tool. A wiki is wonderful for the 2nd one.

 

I know I sound like a broken record, but using JSDoc templates or Doxygen generators creates a clean Documentation, if using the right template. Examples:

http://davidshimjs.github.io/jaguarjs/doc/

https://github.com/danyg/jsdoc3Template/wiki#screenshots

http://documentcloud.github.io/underscore/

 

We can learn from those.

[Wingnut]

 

the whole tutorials sections looks like a random note of stuff glued together

 

Really? 

 

The Babylon primer... is a very hard-thought document that covers everything for the raw beginner.  Everything.  Lots of thought went into WHAT to include in that document, and its order of presentation.  No glue.

 

The playpen series are all basic documentation with associated playgrounds for each, and the order matches the PG demo scenes.  Each "sister" PG demo TRIES to cover all the options and features for the system/document being discussed.  You call that glued together?  If that's glued together, it is an organized and hard-thought gluing.

 

Advanced Texturing (mid-level tutorials) is a document that compliments the Materials tutorial.  Much thought went into what belongs in Materials and what belongs in Advanced Texturing.  No glue. 

 

Two of the mid-level tutorials are sort-of repeats of playpen series... #3 unleash and #4 lights.  They are legacy documents and we didn't have the heart to kill them, so they were moved to mid-level and used as 'More about Materials', and 'More about Lights'... which is mid-level-ish.  The rest of the mid-level were deemed (after discussions amongst curators) to be more commonly-used than the things in 'More Advanced Features'.

 

More Advanced Features IS a glue pile, because all that remains is advanced things... once the basics are covered.  It became a dumping ground for the newest documents and systems... and it could use some organizing IF someone can find a categorization criteria amongst them.  Good luck with that.

 

We recently added ribbons and tubes, and their documentation was placed in a subfolder beneath basic shapes.  They needed a subfolder, because it's a new, likely-expanding section... and parametrics are not the most basic of basic shapes.  They needed room to grow, and Jerome needed real estate to play-in.  He did it perfectly with his subfolder, and I still see no glue, but I do see some organization and forethought.

 

Everyone has a different opinion.  Everyone has preferred methods.  I prefer html over md... because it gives me more power to teach.  Primarily, colors, but there's many helpful teaching toys in HTML.  In .md... I feel I am in handcuffs... especially considering I'm teaching English (to some) as well.

 

When I first arrived at BabylonDocs as a curator... I was scared.  Thank God admin didn't put any "pending validation" duties on me, because I felt BD wasn't ready, and it felt real alien to me.  I spent the first 2 months after BD opened... bitching about it.  What little wiki-doc organizing gumption I had... went out the door.   I concentrated on bitching and getting the features into BD that I needed to operate, and getting the rest of it explained to me.  Plus, we had documents getting chopped, and un-movable documents... un-rename-able documents, and still, we tried like hell. 

 

Temechon cracked 3 ribs from bending over backwards trying to satisfy my bitching.  I don't know how he survived the whining hell that I put him through... but he is to be applauded big-time.  Temechon built the BJS tags system and the power query tools that go with it, and that system was active in BabylonDocs, too.  Power search by tags... what a great idea... and I hope he/we get the chance to make that system (or similar) fully operational someday... because... it's the answer to many of the concerns I have heard here.

 

Ever try organizing something when the documents cannot be moved, but instead need to be recreated in a new place, and the old one deleted?  It makes for some SLOW organizing, and even slower idea-reverts (changing your mind).  It was nobody's fault.  The systems that were implemented, dictated much of that.

 

Should we talk about HOW FAST the framework was changing, and still is?  DK and other contributors were writing documentation SO FAST for awhile there, that I couldn't even keep-up with the "tweaking the English" part, speak nothing of helping DK and others get some playgrounds made.  Dad72 stepped-in and rescued me/us... in the instancing division... took some serious workload off-of the TODO list for us.  Lots of people stepped-up and helped just at the right time... to keep me from pulling my hair out.  Temechon was well-bald by that time. 

 

Deltakosh is the wise one.  He shaves his hair SO SHORT (out of pure necessity) that he can't pull it out.  That's the mark of a PRO hair-puller. 

 

Go XML... and I have options.  I can use XSL stylesheets to glean THE SAME huge document... into beginner level, mid-level, advanced-level, or pure API and no-talk presentations.  I just use a different XSL stylesheet for each version.  The gleaning/filtering is done by the browser, so it's FAST! 

 

But editing XML is a challenge... and we'd HAVE TO follow the BDML DTD.  BabylonDoc Markup Language, and the DTD (doc type declaration) that we validate the docs against.  Folks would HAVE TO use babylonDoc xml tags... or else the docs won't validate.  But once this "standard" is established, we get full XSLT and XPATH power... and that lets us "present" tutorials in many different ways, including user-writes-their-own XSL node-gleaner.  (makes their own big-document filtering template)... (or database querying template in the case of an all-db/cms tutorials section).

 

Back to main topic, Sure, BD has SOME glue-together looks to it, but some of it is very thought-out.  Sure, I got behind on my duties, and I'm not sure HOW to organize this thing... but you can ask Temechon and Deltakosh how many times I asked for their opinions on the layout/org of the tutorials section.  The guys approved-of the current org, but I think, like me, they "felt" something.

 

One of the early big-mods... was hand-making menus at the top of each folder.  Wingy bitched (of course) about such manually-updated menus... and then he made them.  Things still didn't feel fast, so I made the hotlists.  Are the hotlists glued together?  Hardly.  There are categories, categories that tried to be followed, and the hottest classes IN those categories... were listed first.

 

If these things are glued, then it was a glue that thought about where to apply itself, and tried its best, while asking for opinions and directions in Tutorial Talk and not getting much for replies.  Hell, just trying to explain how we BD contributors are thinking... takes so much text... that it just scares-off the non-native English folk. 

 

How does a doc-author or comment-writer get past bad English-to-whatever translations?  By explaining things in multiple ways, so the auto-translate can process the line in multiple ways.  What happens with multiple-explanations?  Big documents that scare folk away. 

 

Self-defeating, you see?  The more you talk, the more folks get confused... even though you are re-explaining something over and over and over.  I'm still learning about this.  WHEN to teach meticulously, and WHEN to dangle a worm HERE, and WHEN to kick a newbie in a certain direction THERE. 

 

Our forum is great for seeing both extremes.  DK... one or two lines of newbie answer.  Wingnut... one or two pages.  I carefully observe the ramifications of both ways.  No conclusive results found.    There is good and bad to both ways.

 

Back on topic... wouldn't it be better if everything was in tiny pieces in a db?  (have I begged about this enough yet?) hehe.  Use the DB as a CMS. (content management system, the thing that often feeds data to websites... behind the scenes). 

 

Query for the pieces and translate on the fly.  BD could actually generate French documents.  ANY language.  We translate the little "paragraphs" of text gotten from the DB, and if the translation is crap, we try a different way to word the paragraph until we get good translation.  (unpredictable from language to language, though). 

 

Dynamic tutorials.  Dynamic menus.  And even... user COULD set his/her preferred way to view BD... because the user can have their own templates... at home, even.  No more documents.  EVERYTHING is in little pieces in the DB, and editable via html forms.  Each piece has a class/datatype/nodetype... like paragraph, picture, code example, playground link, etc... and the querying template generates an entire document... only when someone browses for one.   Otherwise, the documents do not exist... just the pieces... in the db.

 

I am not sure if any of that is possible, but talk about some POWER!?  Holy crap, Batman! 

 

I'm quite-a-bit responsible for the organizing... and I have been big-time lazy in that dept.  Sorry about that.  But BD is not all organized haphazardly/willy-nilly.  Thought was done, opinions were asked-for, and options were weighed, all under the anvil of "can't easily move documents at BD".  Party On!

 

Addenda:  Ok, ok, I agree.  It LOOKS sort-of glued-together.    Here Jeff, try this 60-proof Glenfarclas stuff... it makes things/people look better. 

[jerome]

Imho, the user doc, tutos, examples are  good, rich, pertinent and quite well organized

far more better than in any other open-source framework

 

the effort should be done on the API doc, imho

this is where people hardly go in

[Vousk-prod.]

Ah ah ah Wingnut, I'm so waiting the day a single post of you will take a whole topic page :lol:

[JCPalmer]

Really? 

...

Self-defeating, you see?  The more you talk, the more folks get confused...

 

Yes, really.  I was talking about the overall organization of the Table of Contents, not the contents.  The Highest level of any tree can serve as the intro, having links to the next highest at the bottom of the page.  If you using it as an index though, all topics that would fit under a top level are right there.  A hierarchical TOC means it can also be used as an indexed.  I mean why are DeviceOrientation Cameras mid-level, but virtualJoysticks cameras advanced?

 

Here is a stab, I took of it:

Tutorials

     01. Scenes

          07. Caching Resources in IndexDB

          09. Using incrementatal Loading system

          12. Create QR-Code Maze

          13. Create WebGL Games for Windows Store

          16. Playing sounds & music

          03. The Temechon Files

          How to Create Your Own File Importer

          How to use Lens Flares

          How to use Path3D

          How to use PostProcessRenderPipeline

          How to use Postprocesses

          How to use SceneOptimizer Tool

          How to use the Tags System

          Optimizing Your Scene with Octrees

          Transparency and How Meshes Are Rendered

          Using depth-of-field and other lens effects

          Using the Debug Layer

          Using the SSAO rendering pipeline

     02. Meshes (formerly Discover Basic Elements)

          Parametric Shapes

               Ribbon tutorial

          How to Merge Meshes

          How to dynamically morph a mesh

          How to use AssetsManager

          How to use Instances

          How to use LOD

          In-Browser Mesh Simplification (Auto-LOD)

     03. Positions, Rotation, Scaling

         How Rotations and Translations Work

     04. Materials

          01. Advanced Texturing

          03. Unleash the STandardMaterial

          05. Using Multi-Materials

          15. Understanding Shaders

          17. Using Decals

          How to use DepthRenderer to get depth values

          How to use FresnelParameters

          How to use Procedural Textures

          How to use Tiled Grounds

     05. Cameras

          08. Understanding DeviceOrientation events

          How to use Multi-Views

          How to use OculusCamera

          How to use VirtualJoysticksCamera

     06. Lights

          04. More About Lights

          Using the Volumetric LightScattering post-process

     07. Animations

          How to use Actions

          How to use Bones and Skeletons

     08. Sprites

     09. Cameras, MeshCollisions and Gravity

          10. Using the Cannon.js Physics Engine

          11. Using the Oimo.js Physics Engine

              Adding Your Own Physics Engine Plugin to Babylon.js

     10. Intersect Collisions - mesh

     11. Picking Collisions

     12. Particles

     13. Environment

          Supporting fog with ShaderMaterial

     14. Height Map

          06. Creating a Convincing World (probably obsolete)

     15. Shadows

[GameMonetize]

This is really a good idea and I would love to have people (And most of all, wingy) opinion on this

[Dad72]

What proposes JCP is perfect and much clearer as regards my opinion.

 

 

[jerome]

I had no opinion before reading this ...

once read, make up mind : I really like this

very pertinent and coherent imho

[Temechon]

I like this too. What about the class list ?