Documentation!

[Stephen Andrews]

As a new member of the BabylonJS community, I can definitely say that documentation is probably the biggest papercut. My team (3 guys total) are new to the WebGL scene, but we've been working on projects with more traditional engines (Horde3D and Panda3D before it). To be honesty, BabylonJS is one of the most well put together APIs we've worked with yet.

 

In the interest of Better Documentation , however, we wanted to lend some of our technical writing skills (we're all professional JS developers, with lots of experience writing API docs) to solve our only major complaint, but it seems like the current documentation was generated from a fork of the project? We can't seem to find any of the comments that would generate what's on http://www.sokrate.fr/documentation/babylonjs/index.html.

 

Having skimmed through this topic, it seems like there's some new documentation coming down the pipeline. If it would help, I'd love to volunteer myself and the other guys on my team. On the other hand, if, for whatever reason something falls through, we can totally make a pull request adding jsdoc generation, and go from there. Just let us know where we can hop in!

I expect it to be somewhere in here, but a quick skim reveals nothing. I'll take a closer look when I'm done with my day job.

[GameMonetize]

Hey guys, we are working on a more flexible documentation system where anyobe can contribute. (due by end of november)

 

In the meantime, Wingnut is working hard on the wiki where anyone can also contribute:

https://github.com/BabylonJS/Babylon.js/wiki

[Temechon]

And I can say the new documentation will be MUCH more beautiful than the current one

[Dad72]

delighted to hear that. but where it can be this new documentation. You see where you Temechon ?

[GameMonetize]

Not available now. We are working on.. ETA: End of november

[macguyvok]

Excellent! That sounds great!

[Dad72]

Ok, thanks Deltakosh 

[Stephen Andrews]

I'll clean up the grammar on the wiki whenever I read it.

[joshcamas]

After realizing I could fix stuff on wiki, I did.

[Wingnut]

Oh sure, now we have Josh causing trouble in the wiki.  Oh boy!    Captain Rambunctious!

 

Just having some fun with you, josh.  But I ask that folks try to be careful in our wiki materials.  PLEASE try to avoid making as many mistakes as I do.   It shouldn't be too difficult to accomplish. 

 

Speaking of trouble, Deltakosh and I have caused some, recently (mostly me, though).

 

1.  HOME... a New Combined Wiki Menu.  Our Basic Series wiki menu (called 'Tutorials') has become a re-direct to our new centralized 'Home' wiki menu, and was combined with it.  Take a look.  The Basic Series tutorials are now called 'The Playpen Tutorials' and each one has a corresponding demo scene at the Babylon.js Playground.  So each Playpen tutorial has a Playground demo that travels with it, and the two could be called a 'Playpack'.  A 'playpack' is a basic tutorial and its corresponding playground demo scene.  Wow, eh?  (long story)

 

2.  A Promotion for Advanced Texturing.  A (former) playpack called 'Advanced Texturing' was recently moved OUT-OF Playpen #13, and therefore Playground Demo #13 was removed as well.  Playpen playpacks (I spit a little) are BASIC, not Advanced.  So... 'Advanced Texturing'  had to go... upward.  Where, you ask?  To the Mid-Level documentation section. 

 

You see, it's a gray area.  What is a 'tutorial'?  What is a 'help file'?  What is 'documentation'?  It's all a blur.  All in all, playpack 13 became an empty slot... when Wingnut got the dumb idea to move Advanced Texturing.

 

3.  Filling the Hole.  A playpack called 'Environment' has been running around, lost in the wiki jungles (it was basic series #15, but we had no playground scene to go with it).  It really didn't have a home, yet I always considered it 'Basic Series' (now Playpen)... because it taught about fog and skyboxes.  Those are 'basic' things, in my opinion... mostly because those two things are SO IMPORTANT to making even a simple scene... look real/nice. 

 

So, the 'Environment' playpack (tutorial and playground demo)... got moved to Playpen slot #13.  Its tutorial got some things added, like scene.clearColor and scene.ambientColor.  These things, in my opinion... are "Environment' things... but I am just now learning about scene.ambientColor and could use some help explaining it to new users.  I have more testing to do... to make sure I am teaching it correctly.  All help certainly welcomed!  And thanks, Deltakosh, for a one-liner comment about it... that you told me a while back.  Your comment got me on the right track to learning it  (used in calculations with material.diffuseColor and material.ambientColor... to determine final mesh color).

 

4. Closing Ranks.  To be brief... playpack 17 became 15, 16 became 14, and now all of the Playpen Tutorials... are in good order (in my opinion).  Sorry if this inconvenienced anyone.  Deltakosh feels (and I completely agree) that a single wiki Home menu, with attempted categorizing, is a good idea.  The Playpen Tutorials now number 1-15, and the first 15 Playground demos... are dedicated to Playpen use.  The Playpen tutorials were, initially, a step-by-step hand-hold... that added more and more 'things' to a single scene.  Essentially, it was the "Creating a Convincing World" document... done step by step, tutorial by tutorial.

 

The Playpen tutorials are evolving away-from that format, now.  The MSDN-based "Convincing World" tutorial has been a tremendous success, garnering about 70,000 hits per day!!!  (Nah, I'm lying.  But it IS a very good tutorial that has launched many success stories.) 

 

"Unleash the Standard Material" is #2, at 50,000 hits per day!  Good stuff.  This is my favorite tutorial!  (so what, wingy?)

 

The CYOS document... "Create Your Own Shader" is #3, and climbing fast. 

 

5. The Temechon Files.  These great off-site tutorials are brand new, and were all created by our good friend and superhero... Temechon!  (I bet you guessed that already.)  His very useful tutorials were already in the Home wiki menu, but I decided that they should get a Hollywood heading.    He was cool with it.

 

 

All in all, in the process of centralizing the wiki menu, it was deemed that 'Advanced Texturing' needed 'advancement' to a mid-level category, and that caused a chain reaction of hellish shuffling of playpacks.  Deltakosh thought that you guys and gals might want to be told-about this.  But maybe he is pulling my leg, because I think I hear all of you... yawning violently. 

 

I hope everyone is cool with all this.  Comments welcome, here, or in Tutorial Talk.  Take care!

[macguyvok]

Excellent! The reorganization really helps out, I love it!

 

A couple of comments:

1. The Environment link was pointed to a placeholder. (I fixed it)
2. In the Environment wiki page, there's no discussion about setting mesh.infiniteDistance on the skybox to keep it's position the same as the camera's position. I see it does now include a discussion on rendering groups (thank you!), but that's only half the problem, typically. I'd be up for making an improvement, but I wanted to get a little bit of feedback about adding it first.

[Wingnut]

Hey, thanks for fixing the link, (and for the kind words)... and yes, as far as I am concerned, add anything that you think is valuable (and on-topic).  Definitely.  Thanks!   Good good good!

 

A chap named Stephen (I think)... added the section on renderingGroups... yay!  I ALMOST overwrote his edit by accident.  Maybe I did, but he was kind enough to put it back into the document.  I don't know what his forum name is, but good correct information is loved, no matter who adds it.  Thanks, you guys!

[Stephen Andrews]

Hey, thanks for fixing the link, (and for the kind words)... and yes, as far as I am concerned, add anything that you think is valuable (and on-topic).  Definitely.  Thanks!   Good good good!

 

A chap named Stephen (I think)... added the section on renderingGroups... yay!  I ALMOST overwrote his edit by accident.  Maybe I did, but he was kind enough to put it back into the document.  I don't know what his forum name is, but good correct information is loved, no matter who adds it.  Thanks, you guys!

O_o

I know I wrote something about renderingGroups, but I forgot where and when... And my username generally displays as TriBlade9.

 

- Stephen Andrews, laughing his head off, and will shortly proceed to hunting down this other 'Stephen' character and dismembering thanking him.

[Wingnut]

To whomever changed all the italics in the Environment tutorial... to inline code:  Why was this done, considering all our other tutorials use italics?  *scratch scratch*  No big deal, but, an interesting decision.  I will not override, but please consider a rethink on that.  Thanks.

[GameMonetize]

Who was the latest editor of this tutorial?

[Dad72]

I do not see the italics in the tutorials? I watch several tutorial and does not see italics.

[Dad72]

oops double post ....

[Wingnut]

The early tutorials and MSDN docs use/used italics for property names in paragraphs, I think.  But maybe I am mistaken. 

 

I'm not trying to create any hassles.  Whatever everyone wants to do is fine with me.

[Dad72]

I do not mind it either with italics or not.

And yes, I see italics on the tutorial camera

[macguyvok]

I was the one who made the change. Just for clarification, my rationale was this:

 

1. When referencing an API, inline code helps make it clear that you're referring to something code related. It's also pretty standard; every generated API doc I've ever seen uses it.
2. It's used sporadically throughout the rest of the tutorials; I made it as a separate change in case it needed to be reverted, but my intention was to convert one tutorial, and see how everyone felt, then convert the others.

Unfortunately, I had some intense work-related things that kept me from getting back to these forums until tonight, or I would have brought this up myself.

 

In short, how do people feel? I volunteer to go through all tutorials and make this change across the board if people agree with me; if not, I'll totally discuss in PM with anyone who wants to debate, other wise I'll accept the general consensus. 

[Wingnut]

Hi Macguyvok!  I've decided not to care anymore.  But 1/3 of our tutorials are located at MSDN blogs.  What do you propose for those? 

 

And what do you consider to be "excess elipsis"?  (edit 8354a52) 

 

Is there a number of elipsis that you have determined is "excess"?  Could I please have that number?  I don't want to anger the elipsis police. 

[macguyvok]

Hmm, that is a little problematic, I won't lie. But, the intention was to improve things, not make waves. If it's not seen an improvement, then clearly the change doesn't belong, right?   I was just looking to apply some of my experience writing technical documents to improve the tutorials. But, like I said, if there's any objections, I'll stick to just content updates, not formatting.

 

And, since you asked, here you go.   (Mostly, it seemed like '...' was being used in place of ','.)

[Wingnut]

Thanks, M!  That was useful.  I use them as places to pause the reading.  But not everyone would agree with me as to when and where pauses should happen.  I use them often, but I am longer-winded than many others. 

 

It's all cool.  I (and likely everyone) appreciate your edits and additions, and your knowledge of English.  Be well!

[Dad72]

Hello,
 
You forget 'Anaglyph camera' and 'Texture TGA support' in Features on github Deltakosh. 
 
I think the page and the link "Tutorials" can remove view that everything is focus on this "Wiki".

[Wingnut]

Good idea, dad72.  It was my idea to temporarily make 'tutorials' a redirect, so that people had some time to re-target their old links.

 

I gave out the link to 'tutorials' many times, and although I re-targetted all the occurences that I ever did on this forum and in other github wiki documents, maybe others need some time to re-target THEIR links to the new 'Home' menu.

 

I was thinking about maybe 90 - 180 days, and then after that, remove the 'tutorials' document completely.  I thought it was a wise idea to avoid making 'tutorials' become an instantly dead link.  But, maybe my idea is a bad idea.