suggestion - comments in doc pages

[al404]

I post in this section because i guess i most appropriate one.

I just want to give a suggestion for documentation / tutorial pages, i guess it would be very useful to find little hints on this pages too 

Php docs have a comment section under each page and often you can find an hint or a bug hint without searching the web, the also have up / down vote system that vote if is useful or not

an example page

http://php.net/manual/en/function.explode.php

[Dad72]

It is true that the PHP documentation is really excellent. One page was all that necessary, Description and Parameters, Examples with result, See Also, User Contributed Notes...

The examples are very helpful every time and that's what is missing is the documentation of Babylon for each function.

But the implementation of this, ask I think a huge work. But make it really perfect.

[al404]

I know that would take a huge work from authors, thats why i suggest to add user comments.

As in PHP docs some users add example code and hints, here it would also be possible to add playground link

[Wingnut]

Hi @al404, thanks for the idea/example.  That would be sweet, huh?  By the way, we have a pinned thread called Contributing to documentation 101   and another non-pinned thread called Tutorial Talk ...but everything is flexible.    

This idea does not really apply to tutorials, it applies to our class docs.  Allow me to take us on a little tour.

Let's choose observable.  http://doc.babylonjs.com/classes/2.4/Observable

Notice that this is a CLASS doc, and it lists properties and methods defined on that class.  The PHP method is more granular than this.  It (the php doc) is a long document for one single method.  But still, at the top of the observable class doc... there is some "teaching".  I wonder where this top teach-text is stored. 

See the word "particularity" there?  That's a fairly unique word.  Let's go searching the docs repository for that term.

Aha... there it is... https://github.com/BabylonJS/Documentation/blob/master/content/classes/2.4/Observable.md

md file... markdown... specifically github-flavored markdown.  Notice it's path/url.  It resides somewhat deep in our docs repo areas.  But who typed this .md doc?

Nobody.  This doc is generated... possibly by a JSdoc thing that the pro docs curators run... every time BJS has a version change.  Let's look at the folder that this .md resides-within:

https://github.com/BabylonJS/Documentation/tree/master/content/classes/2.4

Lots of "New 2.4 version" comments in there.  I wonder... WHERE is the ACTUAL data stored... (like that word "particularity")... that is used to generate these .md docs... that later get converted to .html files for the website?

Well, hmm, let's roll the dice and see if that word is found in the BJS SOURCE CODE repository (not the same as the docs repository).

https://github.com/BabylonJS/Babylon.js/search?utf8=✓&q=particularity

Aha!  There's our word... inside observable.ts and observable.js.  Let's look closer at observable.ts. ...

https://github.com/BabylonJS/Babylon.js/blob/master/src/Tools/babylon.observable.ts  line 42

So, it appears that our .html class docs, are created from .md class docs, which are generated by something similar to JsDoc, using the current BJS version .ts (typescript) source files.

Does anyone like me... wonder... at this point... IF someone made a change to observable.md... WOULD that edit/change get over-written when version 2.5 came out?  Likely so.

Along comes 7 year old Mikey Mangler, an enthusiastic youngster who is thinks he is an expert in Observables... and wants to change some of that teachy-text.  He learns where to change it, just like we just now learned... and he goes "mucking around" in the .ts source code.  While he is in there, he decides to add another parameter to the removeCallback method.  Hey, this is open source, he is certainly allowed to contribute code/ideas to the framework.  If he knows what he's doing, and can substantiate/justify the change to the curator who needs to approve that change.... all is well.

Me?  I'm scared of doing edits to .ts files, but that's me... not Mikey Mangler. 

My point?  I dunno.  I once talked with the docs gang... about having another database... with a web-form interface... where users could easily add "tips and tricks" just like the PHP document that @al404 provided as a demo.  Various experienced documentation managers (for other systems) told me that doing such things... is a maintenance mountain, and I can believe it.  Yet, there it is... for PHP explode() method, and it looks like it has been well-fleshed with user comments.

Yep, we'd need quite a large team of docs custodians.  PHP might have the large following needed for that.  I don't think BJS does.  And it doesn't help... that BJS, the framework... is so friggin' fun to play-with.  SO many times I have started to plan a docs edit, looked-for or created some playgrounds to assist my new docs section, and then ended-up playing with the playgrounds and not getting any docs-writing done.  Playing with BJS scenes is about 8000 times more fun than writing docs for it. 

Ok, just thought I'd tell you what I know.  I'm the kind of guy that believes .ts files are for core programmers, and not for docs writers to be playing-within.

The big question (which @Temechon, docs God, has probably already answered for me, but I forgot his answer)... is...

IF I make a change to 2.4 observable.md, will that be over-written when BJS version 2.5 is released and new .md files are generated from the .ts source code? 

If so, then we MUST edit the .ts files in order to get the change to "hold" across future versions.  And... SHOULD general users add tips and tricks to the .ts files?  That scares me (of course)... but the docs pros and core coders say "yeah, why not?  Open source."

SO, we could really flesh-out our class docs... by editing the .ts files.  All of us could.  Does anyone feel comfortable doing things that way?  I sure don't... but I have no confidence or balls.     

@al404 - your idea... is excellent.  Doing it?  hmm.  My dog has already run under the bed, scared, just from this post. 

There is another way.  Writing tutorials... like "Everything About Observables", and "Everything About the Scene Object" and "Mesh, the Whole Story".  These are ALSO maintenance challenges and need dedicated custodians... but this method feels "safer" to me.  But this method might be slower for users to find the answers they need.  And maybe... a forum search for 'mesh'... already automatically creates "Mesh, the Whole Story", right?

Sorry for all the yapping.  There is a saying that I learned from the TV show "The West Wing".   "Those that know, don't speak.  Those that speak, don't know."  If that is true, I know NOTHING!  (because I am ALWAYS speaking/typing)

*shrug*  Thoughts welcome, and please correct me wherever I said incorrect things.  I do that often.    Thanks for letting me trash-up your topic, 404.