Tutorial Talk

[jerome]

currently :

- we have quite a good documentation site with tutos, examples, etc, nothing to be ashamed compared to the other frameworks, especially those that The Name Can't Be pronounced Here

- this documentation site is rather updated by different kind of people from time to time (so not stale)

- we have a very poor API documentation within the API site

- noone ever edits directly this API site, the few documentation that may appear only comes from a kindly coder when he thinks to add a documentation comment.

The main idea is just now to consider as a good practice to systematically add doc comments when fixing/updating the related code (so won't go stale either). These comments must be as straightforward and pertinent as possible (accepts this type, returns this type, doesn't create a new object, returns a new object, overwrites this other property, useless if this other one is set to true, etc), else a link to a PG demo would be enough.

[Wingnut]

hehe.  The thing whose name thoust shalst not speaketh. 

I would REALLY like... where... coders simply drop a note/form into the Dockers In-Box, and then the coder can move-on in happiness.  The dockers take it from there.  In a perfect world, the dockers would visit the coder for "final approval" before the change in documentation... is published to the world.

[GameMonetize]

I would love to be able to do that Wingy:) But so far I don't see a lot of contributions to the doc site.

Don't forget that all comments that we put in the code are automatically extracted to populate the Class documentation on doc.babylonj.com. So no one is forced to open the code. And this remains a simple way to provide a first round of documentation

 

[Wingnut]

Users might not be forced to open the code, but they MIGHT do it anyway... to help with the documentation of methods and properties.

(Especially now that you have told them that info inside there... is automatically used in the docs) 

So, can I assume that no info is gotten from the OLD class md... during the generation of a NEW class md?

IF the class.md building/batch-run DID retrieve info (former comments) from the old class.md, then you could remove all "documentation comments" from the source, and no longer use source comments (except as messages to self and other coders)?

[JohnK]

My preference to enhance the API documentation would be a link to a PG for each class/method/property with comments in the PG. For example

Description

class PolygonMeshBuilder

Playground

Example

Constructor

new PolygonMeshBuilder(name, contours, scene)

etc............................................................

 

However it is alright to make suggestions if I was going to do something about it and do some editing. So why do I not do this? Main reason is that like most people who use BJS and the forum I am more interested in playing with the code that writing documentation. With the best will in the world I think about it but then get distracted by my own projects such as generating trees or whatever. So it is hardly fair for me to complain about the API documentation. The secondary reason is I am not sure what I wrote in the PG about x-z plane and camera direction is true or whether my interpretation of the evidence is flawed and for many parts of the API I am not sure why they are there. For example

Constructor

new Mesh(name, scene, parent, source, doNotCloneChildren)

when are parent, source, doNotClone necessary when constructing a mesh? Are these parameters just used when using the clone method?

Here is a commitment - if this idea of a PG example for class/method/property is an OK one for the community then over the next month I will write at least 5 examples of ones I understand as a starting point.

[Wingnut]

Well-stated and well-analyzed, JK.  Great ideas and uber-thooz, too (nice enthusiasm/spirit). 

But... it would require an ENORMOUS amount of playgrounds to accomplish this, and up-to 10% of those playgrounds would go broken when a BJS version changes.  It would likely be a maintenance hell. 

I do love your ideas... what a dream-come-true that would be.  We'd need a team of 30 dedicated docs custodians to do it.  Got team? 

Still, I'm going to keep these ideas solidly in-mind, and try to figure out ways to do it, or similar.  Thanks John!  (Wingy ponders and scratches).

[Wingnut]

Sorry for being so yappy, and pardon me, guys, but I need to speak with the docs elders here... for a moment.

It's likely... we already have, or can generate... "the list", right?  A list of all methods and properties on all objects.  Hell, I probably already have one in my local docs repo clone.

hmm.  What if... we started another "section" in Azureville?  (We store our playgrounds in Azure, currently.  Works great, and admin there... have shown us some kindness, I heard.)

In this DB... we would store class meth/prop docs text.  It might use the same @key names... as is currently used in our source.ts files.

THEN... we interface it to the forum.  Yep, two fly-by-night companies... IPS and MS... working together... or possibly using an extension or plugin to the forum.  The primary objective is to let users who have a forum account... add-to and edit... that database (but maybe have some limits, there).  The main thing... is for Azure (and its new forum-webby interface to our area) have the abilities to identify the forum member who is "calling" (trying to make an edit).  We build a nice forum interface.... so that folks feel at-ease with editing information in that DB.  It's easy, and each record/field is identified with its contributor(s).  We know who initially wrote the record/field, we know what obj/prop/meth it is for, and we know who last edited it, and when.

Then, at ts-to-md build-time... Temechon and the boys... query that Azure DB... live... picking-up all the goods... to use for ClassDocs - The Next Generation.

Holy crappers, eh?  No more fear of github.  Everyone participates.  You get "Docker Points", too... proudly shown near your name on the forum.  What if?  Wow!  No more documentation in the source... only comments to coders.  Yum!  (Why do I subliminally-hear Temechon saying "yech!" right now?) 

[GameMonetize]

Quote

IF the class.md building/batch-run DID retrieve info (former comments) from the old class.md, then you could remove all "documentation comments" from the source, and no longer use source comments (except as messages to self and other coders)?

It did. This is the current way of working. But NO ONE update the class.md. NO ONE. So I suggested to Temechon to remove this and instead use only code comments.

We are talking a lot about documentation but so far I don't see a lot of documentation produced.

[satguru]

Wingy,

I think you should reconsider your stand on documenting inside the code and the API documentation

Frameworks like ours are targeted at developers.

For  developers, API doc is the first  go to place . It is their bible.

I come from a java background and I cannot live without the JavaDocs.

They provide a wealth of information

Consider, for example, just a simple Class like "String"

https://docs.oracle.com/javase/8/docs/api/java/lang/String.html

Look at the amount of information here.

And all this is picked up from code.

Look at the code for the same

http://hg.openjdk.java.net/jdk8/jdk8/jdk/file/687fd7c7986d/src/share/classes/java/lang/String.java

More documentation than code !!

And all written by API developers

The person writing the code is the perfect person to document that code

and the place you write the code is the perfect place to write the document.

For the coder it is not a big burden - his writing is limited to just the piece he is working on.

If class - document the class, if method just that method, if property just that property.

Further the  API developer, I suspect, would be the most motivated to write the doc.

After all he wants other people to use his API.

What he does not want is using a separate, complicated system to write code or worse coordinating with another person to write documentation for his code.

 

Now I do agree that we do not want to burden  the non API developers to have to muck around in the source code GitHub to add to the  API documentation.

So a system which can merge the API Docs with  user submitted doc would be great

And I believe we do have such a system in place.

 

[Wingnut]

Good points, SatG.  I agree... a combination.  But one point that I'd like to address...

25 minutes ago, satguru said:

Frameworks like ours are targeted at developers

No, not entirely.  It is targeted at artists and storytellers, too.

----------

Dk, I'm searching for ways to make it easier.  I understand that you want action, now. 

I think the participant flow will improve... when the trail isn't quite so scary.  We need more ideas, in my opinion.  I would rather shoot fire-starters than fight fires.

[Nockawa]

Guys, I just want to share my experience, I wrote 3D tools/libraries/middleware for ten years, professionally. (i.e. not open source).

I think I've tried everything I could, and I really mean it: documentation was essential to us because we had fast release cycles and without doc the users would just not buy the product.

What I've learn from all these trial and error is:

1) The code is the ultimate starting point, the ultimate referential: you build code, you change code.

From this statement, having a second referential (the document written separately) is a living nightmare that sucks all your time.

 2) You need reference documentation and overview/tutorial documentation: they are complementary, they serve a different purpose and the user will switch from both constantly.

You don't have to produce them the same way.

 

Writing reference documentation in the source code is definitely the best way to achieve the best result, almost every company I know selling libraries does it, when they don't, they have HUGE dedicated doc team (which is not something to consider for an open source project).

Concerning overview/tutorial: a wiki is definitely what I found being the best compromise between the time you spend on it and the result for the user.

 

When I started on Babylon.js I quickly realized that the architecture for the document was really good (IHMO) and I mean it, but read my words carefully : "architecture".

Everything has been setup to achieve a good result, but being an open source project contributed by a bunch of passionate guys: documentation is always "the thing I'll do at the end" and we all know how it ends most of the time.

Tutorial are great, but the reference documentation is hollow.

But you know what? This is a collaborative project, right!? Which means everybody can contribute! Even if I think that a reference doc should be written by the guys who wrote the code, I know very well that the two guys that started working on this side project late at night couldn't afford to doc everything, especially when you refactor/change the architecture constantly when the project is at its very beginning.

Instead of debating on this forum which lead to a considerable waste of time, why wouldn't we try to produce some doc? You may not be pleased with the rules in place, but we need rules and only the core team is responsible of them.

Everybody can't be satisfied and won't be, let's just try to improve things.

Personally I will write some ref doc when I'll be comfortable with a given part of the lib. Until then, it's still a learning process...

[Nockawa]

7 minutes ago, Wingnut said:

I think the participant flow will improve... when the trail isn't quite so scary.  We need more ideas, in my opinion.  I would rather shoot fire-starters than fight fires.

We don't need more ideas, everything is already setup and working. We need doc contributors, period.

Still my opinion...brutal, but honest.

[Wingnut]

Thanks Nockawa... I would LIKE that, but I've reached my 10-like daily limit. 

If you think this is a considerable waste of time, then split.  I need to learn, and want to learn.  There's others here... doing the same.  You're welcome to your opinion on that... but the true waste of time... is saying something is a waste of time.  (imho)  *shrug*

[adam]

This looks promising:

http://typedoc.io/

http://typedoc.io/guides/doccomments.html

Here is what the default theme looks like:

http://typedoc.io/themes/default/

[Nockawa]

3 minutes ago, Wingnut said:

Thanks Nockawa... I would LIKE that, but I've reached my 10-like daily limit. 

If you think this is a considerable waste of time, then split.  I need to learn, and want to learn.  There's others here... doing the same.  You're welcome to your opinion on that... but the true waste of time... is saying something is a waste of time.  (imho)  *shrug*

I'm just saying, whether you like it or not: there's already everything ready for people to contribute:

• Building ref doc from inline code documentation
• Building Tutorial from github using .md files
• The Playground to showcase features.

My first contribution is here I didn't do any ref doc but I should have and will be, but I'll do it when I'll know what DK needs me to do. Everybody can't do as they please otherwise the project will be a mess in few weeks..

[Wingnut]

Have you looked at our TS files, Adam?  We're already there. 

[adam]

1 minute ago, Wingnut said:

Have you looked at our TS files, Adam?  We're already there. 

That is a tool for generating docs from the code.  Maybe I don't understand.

[Wingnut]

@adam See all the @stuff in the ts file?  I have a feeling that the elders already use a typedoc module to generate the class md files.

[adam]

Got it.  Sorry for my confusion.

[Wingnut]

Hi gang. 

Well, I hoping for a pile of new responses and information here... when I awoke this morning.  That didn't happen.  But, just the same, I want to thank everyone for all the great comments that happened yesterday.  I learned tons.  It was wonderful!

One thing I want to point out.  I am almost 100% sure that the ts-to-class.md conversion (possibly using a typedoc module)... IS done in a separate batch run.  The docs repo and the framework src repo... are separate repos (duh, Wingy).   When I home-clone the docs repository, I don't need to clone the .ts files also... in order to do a docs build.  The class.md files are pre-built.  (Wingy awakens in more ways than one.)

Two posts really "hit-home" with me... one from SatGuru, and one from Nockawa.  Thanks guys... both posts were full of Wingnut-fixing points.

Considering all this, I have a NEW idea, inspired by JohnK's idea.  Three (3) "clickable icons" near each property/method on the class web pages:

   #1 - Search the source code for all occurrences of this property/method
   #2 - Same... except search the forum
   #3 - Same... except search our playgrounds database (there was once an issue with PG search for strings with periods in them - maybe fixed now)

There are some problems with this (possibly MANY, but MY limited brain-power can only see some, so far.)  These link-icons and their urls... would need to be force-inserted in the ts-to-md batch run that is done by the docs elders.  This could be trouble.  Not sure.

Let's take a look at one of our class docs... the base Light class...  http://doc.babylonjs.com/classes/2.3/Light

Mouse-over a few of the properties or methods.  Notice the cool link-icon that appears on the left?  Click on the link-icon, or on the prop/meth name itself, and its background turns gold and the URL in the browser address bar... changes to point directly AT that prop/meth.  You can also right-click and choose "copy link location" or similar... and then you can easily paste this URL into forum posts for helping fellow Babylonians. 

The problem?  If we put three more icons there, we would be using-up valuable screen space.  All three... COULD be put on a single link-icon.  Perhaps, click the single search icon, then a new window/page opens, and all three types of search are available there.  (Just thinking... and likely not very well.)  heh

Okay, I ONLY had the idea... NOT a way to implement it.  Nor do I know if this idea is wise, useful, or possible.  I just thought I'd toss it onto the floor of the Tutorial Talk thread, and see how dirty it becomes, and what feet kicked/stomped it.     Be well, thanks again.  Comments from anyone/everyone... warmly welcomed.

[Wingnut]

Hi gang...

Regarding this... http://doc.babylonjs.com/tutorials/Understanding_Shaders_with_Babylon.js_and_ShaderMaterial

Does anyone know who wrote the bottom part?

Does it need updating (the info)?  (links obviously need updating)

Would the original author wish to do that for me/us?  (thx)

I tried getting its git-history: https://github.com/BabylonJS/Documentation/commits/master/content/tutorials/02_Mid_Level/Understanding_Shaders_with_Babylon.js_and_ShaderMaterial.md

Not much info there... for THIS doc.  Any assistance that anyone can offer... regarding that block of text... would be welcomed.

[GameMonetize]

I wrote it and this is no more accurate. Good catch. How do you want to proceed here? I can update it to fix both links and text

[Wingnut]

That would be great, thanks.

[GameMonetize]

Done

[Wingnut]

Thanks DK!

Uncle Wingnut is learning about TOC (Tables of Contents) for tutorials, lately.

Check this out...

http://doc.babylonjs.com/tutorials/Position,_Rotate,_Translate_and_Spaces

Is that yours, JohnnyKakes?  What a nice-looking document.  Your TOC is perfect.  Yum!  I'm going to TRY to get all of our tutorials... to look as nice as this one.

There's LOTS of excellent tutorial writers/format-experts around this joint.  I think I am going to "borrow" a bit of their document-styling knowledge.

Aside: Is everyone waiting for Raanan's new Physics Plugin Docs?  What a hog THAT thing is going to be!  SO SO SO much to be explained, for that.  OMG!  I can't even imagine it.  Somebody check-on him from time to time... make sure he doesn't need emergency medical (or mental) services.