Official documentation site!

[Temechon]

Sorry, it was a big week for me... First thing on Monday, I sware !

[RaananW]

Hola people,

 

I have been having troubles logging in again - I am pretty sure the password I entered was correct, but it still didn't let me log in, so I asked for a password reset. This password didn't work as well 

any help is appreciated!

 

[GameMonetize]

lol

[Dad72]

This seems fix. by cons I was wondering if it was possible to date versions (The 24/03/2015) of editing tutorials. Currently we have the person who edited, but no date.

[jerome]

Je plussoie.

 

+1

[Temechon]

Indeed, it was fixed this morning. I will check for the date (I don't know if it's the data model or not :/ )

[jahow]

Hey,

 

I've tried to find a nice place to put some more info on baking transform into meshes, but I couldn't find a really suitable page. Eventually I submitted some new stuff on the 'How Rotations and Translations Work' page, but I think changing its name to 'Advanced Mesh Transforms' or something like might be better suited (especially since the stuff I added also deals with scaling).

 

Just a suggestion!

[GameMonetize]

I like the current title because this is one of the first questions any newbie will have. And your article is the perfect content to answer it:)

[jahow]

Alrighty! I figure that if anyone looks up "baking" or "bake" they will end up on this page anyhow

[jahow]

Hi! would it be possible to display a linked table of contents at the beginning of each article, based on the titles used? Just like wikipedia does for example.

 

I think that would make a nice improvement to readability of the documentation (not that it's currently lacking!).

 

EDIT: apparently there's a lib for it: https://github.com/jonschlinkert/markdown-toc

[Temechon]

Do you mean for article other than API classes ?

I guess we can add this to our roundmap

[jahow]

Yes, not for API classes and "list" articles (containing all the child items)!

 

I think it would be awesome.

[Temechon]

No problem, I add it to my backlog Thanks for the suggestion, it's always appreciated!

[Wingnut]

I'm a bit confused (normal).  If I may ask, would this TOC be for things like the API doc for Scene, and Mesh (big objects) where we now use in-browser search, and thus get hits from the doc and, unfortunately, from the sidebar too?

 

Are we talking about putting a substantial chunk of .md at the top of (some of) our .ts files?  Or, would this TOC be "generated" when the the .ts was converted to um... whatever its converted-to (html, I think)?  (thx for clarification)

[JCPalmer]

A Mark up question.  Is there a way to put text to the right of the image, so that it not a huge vertical waste of space?

It crudely works in forum posts.

[Wingnut]

https://www.google.com/search?q=floating+an+image+in+githgub+markdown&gws_rd=ssl#q=floating+an+image+in+github+markdown

 

*shrug*  Wish I could help in a better way, but after I saw the search returns, I figged it would be best if YOU toured them yourself.  In fact, I'm going to read a few of them, too.  I didn't know there was such a thing as inline html with markdown... until today.  Interesting.  Hope this helps.  Thanks for all the great work you do, Jc.

 

By the way everyone, it is a demo picture, and not pertinent to the subject.    I was confused at first, but that's normal for me.  I tried an image search for "float image" to find a better demo picture for Jc's post, but I nearly drown in pictures of parades.  hah

 

Are you working on v2 of your layermask/target reticle doc?   I recently adjusted this line... "window size change, unless it is a tablet app." (hope that is ok with you)  and I lightly suggest that "may be more lights generated later" be changed to "may be more lights created later".  Your call on that... just a thought.

 

Be sure to let me know if you want your name on that doc.  Again, I hope you come on-board BD yourself, but I'm here if you need things done, there.

[jahow]

I'm a bit confused (normal).  If I may ask, would this TOC be for things like the API doc for Scene, and Mesh (big objects) where we now use in-browser search, and thus get hits from the doc and, unfortunately, from the sidebar too?

 

Are we talking about putting a substantial chunk of .md at the top of (some of) our .ts files?  Or, would this TOC be "generated" when the the .ts was converted to um... whatever its converted-to (html, I think)?  (thx for clarification)

 

Hey Wingnut,

 

What I had in mind was only a TOC in tutorial articles only, not API docs. True, the browser search is the perfect way when you know exactly what word you are looking for. In other cases (ie wandering aimlessly, looking for answers), or if you want to give a link to an anchor in the article, a TOC might come in handy.

 

Also the TOC would be generated at markdown interpretation (which I guess happens when the page is loaded).

[Jaskar]

Hi Wingnut, Jahow, and other Babylonians 

 

To be clear, the TOC is present only on tutorials / extensions / exporters documentation.

In classes doc, there is a dropdown list to jump directly to a member / function of the class.

 

This TOC is generated from the markdown file. So, there will be a tutorial about "How to properly write a tutorial" to correctly generate this TOC.

 

Hope I was clear! Else, you can ask Temechon 

[Wingnut]

Thanks guys!  Great comments!  Thanks for the clarifications. 

 

Boy, do we need that drop-down list thing, especially on Scene class.  Scene class doc is well longer than any tutorial-type document we have. 

 

Cameras is one of our longest tutorial-class docs, and there's been some talk about splitting that into separate files.  Two of our cameras already have files specific to them.

 

When our playpen tutorials were first written, they were sequenced.  In a true tutorial fashion, each document talked users through adding ANOTHER cool thing to an on-going scene build.  In other words, about 15 tutorials were really part of a single scene-building tutorial.  Essentially, it was a beginner-level "convincing scene" tutorial, segmented into step-by-step.  At the end, users got a single scene with all the basics, and some advanced scene features. 

 

As our documentation grew, and as we started using playground scenes to show each step... it was clear that we could not have all these features running in a demo all at once. Each playground demo that was associated with each step of the playpen tutorials... needed to be very clear and ONLY show THAT step.  In other words, we couldn't have a playground near the end of the playpen series... that showed sprites, particles, materials, basic/advanced shapes, fog, skyboxes, etc... all in the same scene.  It got too cluttered.

 

So, about that time, I made an audacious command decision.... to phase-out the step-by-step sequential format of the playpen tutorials.  I used The Babylon Primer as the step-by-step to get a basic scene activated (as best I could), and I evolved the playpen series into a non-sequential thing.  The Primer replaced playpen docs 1 and 2, which likely nobody remembers.  Then I started with playpen #3... renumbered, and matched those numbers to playground demo numbers.  You will still notice a few "now your scene is looking great...blah blah blah"... residuals from the sequential step-by-step days.

 

All of a sudden (actually only about 5/8 of a sudden)... the definition of "tutorial" was in question, at least in MY mind.  A TRUE tutorial, in my opinion, is ALWAYS a talk-through, and therefore a TOC is inappropriate.  A TOC would allow people to enter these talk-throughs at middle points... ruining the "talk-through/walk-through" sequence.

 

But then, "tutorials" like Cameras came along.   With 8-10 cameras covered in that document... it sure couldn't be in "talk-through" format any more, if it ever was.  The Cameras tutorial/documentation seemed to say goodbye to being a true tutorial, and became a "documentation" or whatever you want to call a non-tutorial teaching file.  It became a "Everything You Ever Wanted to Know About Cameras".  I think it is useful in its current format, but, it's not really a tutorial, and it's also not "Everything About Cameras".  IF we included everything about cameras, then the document would get much longer, and... it would need a TOC or need separating into 1-file-per-camera.

 

Yuh yuh yuh, there's issues.  I've had ideas, but my best ideas require XSL and XML, and require saying goodbye to .md (github markdown).  I've never been happy with markdown.  Poor formatting options, no color coding, no XSL filtering, it's just garbage (imho), and long ago outdated.  

 

But, it IS easier for a "many editors" system like our BabylonDoc system.  If we allowed many folks to edit our potential future XML and XSL tutorials, I think we'd have messes... but maybe we would come to each others' rescue to repair them.  With XSL, we can let users choose the filtering levels.... by letting them choose different XSL stylesheets to apply against the XML, or even letting users write and store their own XSL stylesheets... and have personalized document filtering... including rendering the document to look like a Table Of Contents (TOC).  And, with styled XML, we get anchor points... for TOC's.  Conversely, I'm not sure if .md allows anchors at all.

 

In my opinion, Scene and Mesh API docs... need TOC's more than any other docs we have.  It takes me forever to find something I need on Scene, and when I get there, I get VERY SPARSE info from the .ts files... rarely any help whatsoever.  I usually need to go to the Scene source code at GitHub, and try to determine what a Scene property/method really does... via analyzing the code.  That's not good.

 

Ahh, SO much to think about.  Lots of opinions and ideas.  How do we know what's right and what's not so right?  Should we start by putting strict regimentation on the terminology?  Should our "tutorials" follow the strict definition of a "tutorial"?  Do we care about that?  I once mentioned it to Temechon, too, when trying to determine if "tutorials" should have one type of icon, and "documentation" another type... etc.  In other words... for Temechon and BD programmers, should tutorials be ONE type of PHP class, and documentation be another type, and API doc be a third type?  Should we try to strictly conform to our document types?  Do we try to teach our curators and editors how to avoid adding things to tutorials... which don't follow the "rules of being a tutorial"?  Why do I start feeling Gestapo, suddenly? 

 

My brain hurts.  Comments welcome... but... I think we're not yet ready to begin BabylonDocs 2.  That's why I was surprised to hear that folks were already working on it.  I don't think its requirements have been ironed-out, yet.  I don't think we have addressed the limitations of .md.  And, we have a decision-by-committee situation at hand, which is loving and considerate and democratic, but takes forever and is like extracting teeth with a Jello cube. 

 

Thoughts?  (Wingy ducks and covers).  heh.  By the way, I'm quite sure that Jaskar is a member of the BD2 dev team (in case some of our readers don't know that).  Thanks for the status reports, Jaskar... keep them coming when you get a chance, eh?  Cool.

[jahow]

Thanks Jaskar, this sounds good!

 

Wingnut, I think your point on tutorials not being actual tutorials is right on. It's easy to tell when you see the BJS docs that they have been steadily growing and expanding along with the framework. As a contributor of a few lines here and there in the doc, I can tell that I had a hard time finding the right place to document features about 75% of the time. I'd say (probably an uneducated guess) that one day or another the whole structure of the documentation will have to be rethinked, and files will have to be merged/splitted accordingly (tutorials on one side, helping building a simple scene step by step, and documentation/advanced features articles on the other side). Maybe that's already happening behind the scenes for BabylonDoc 2.0?

 

Also, 100% agreed on having to look into the source to know what a property does. I for one don't use the API pages in the documentation as the source code is very readable, especially TS files. Not ranting here, I'm just giving as much feedback as possible!

 

On the other hand, I don't agree with your view on markdown. In my opinion, markdown is a great tool for authoring formatted text, as it has no real syntax to speak of, is very widely used and just simple to work with. Really, when writing documentation, no one should have to worry about styling or syntax. Even more, no one should be able to break the consistency of the whole documentation by altering the styling of one specific article.

[GameMonetize]

Completely agree on the markdown stuff

[Wingnut]

Who do you agree with, DK?  We have some docs in html at msdn (almost all of our mid-levels), and some docs in markdown at BD.  Is anyone hurrying to convert the one-person-editable html docs at msdn, into multi-person-editable markdown docs at BD? 

 

No.  Why?  Because nobody is in a hurry to degrade the msdn docs, right?   Why format for modern browsers when we can format for Lynx? (sarcasm).  (Boy, I'm old.  For those under 40 yrs old, Lynx was the Model - A of browsers.  It was about as intelligent as a markdown viewer.)

 

Temechon's tutorials... are in html.  I wonder why.  Maybe... cuz HTML has the power he needs to get the job done?  Markdown left him wanting, maybe?  In the face of DK, Davrous, and Temechon ALL writing docs in html sometimes (Temechon at his home site, Dav and DK at MSDN blogs)... I should happily accept markdown as the only authoring medium/format for BD?  Do we have some mixed feelings running around?  Everyone yell "yay markdown" and then go write docs in html?  ahem.

 

JcPalmer... keep us posted in your search for floating text beside pictures, for markdown.  I have no answers, but you can do like the pros, and write your docs in html.  You'll get the formatting power you need, with html.    Plus, when you maintain complete control, nobody can add bad English, and nobody can come in and remove all your ellipses.    (reference to a series of doc-formatting forum posts - where the ellipse police busted me for using too many ellipses)  heh.  I fought the law, and the law left... and never came back.  Poor guy.  He was absolutely right, I use lots of (maybe too many) ellipses. 

 

Actually, I have no point.  I just wanted to point-out some "stuff".  Markdown's limp power has only gotten in my way about 100 times... no big deal.

[GameMonetize]

I agree with the fact that MD are FAR better for documentation than plain html so I'm agreeing with Jahow

 

MD is just about the content. The hosting web site is responsible for the display. I like that. I'm writing HTML on my blog because I have no choice. same for Davrous

[Wingnut]

Some say xml is about the content.  Why not BDML... babylon docs markup language?  And the site... you bet... it provides the stylesheets.  It provides the presentation, the xml provides the content.  We validate all our BDML (xml) against a DTD.  It's the way normal people do it.  Markdown isn't even a proper way to represent data.  No fields.  Free flying, un-enclosed text... allowed.  No delimiters.  That's just scary, no?

 

Anyway, the point I was trying to make about msdn... is... why write docs there at all?  Why would you set it up so that someone will have to convert those posts... to markdown someday?  Why weren't they made in markdown initially?  And, why is nobody planning to convert them to markdown?  Why are tutorials still being written with msdn html? 

 

Do people LIKE the pages at BD that say "We're headed for David Catuhe's blog" and "We're headed for Temechon's website"?  Is there any plans to QUIT writing tutorials on the blogs?

 

I don't think you guys are giving XML a fair shake... a fair chance at bat.  We see the wonderful affects of casting all scene items as base class NODE, yet when I suggest we cast every section of all tutorials...  as an XML node, it doesn't have the same impact upon anyone. 

 

Granular node-wrangling.  A power CMS between BD and its webserver... a CMS that can assemble a document in a gazillion different ways from a gazillion different pieces.  Each piece, wrapped in a BDML node... with node attributes allowed.  Dynamic html doc assembly, ya know?  No styling, just good clean xml data, no format implied at all.  Or, full styling, just by attaching a single xml stylesheet.  Yum!

 

Ya'll are going there, anyway, it's just a matter of time. Resistance is futile.    Markdown will give you cancer.

[JohnK]

Here's my tuppence worth, how about pushing wingnut's idea even further put it all together and have a front end for the user that is a page template where the documenter just adds the content, button here to add a link to another page, button there playgound link, button there add image, you could even have preset image sizes and make the images fit. Each page would have a consistent style, bullet points would be of a fixed type and ahhhhhhhh  wingnuts go to me, I tried to resist but it was futile