Tutorial Talk

[pathogen]

Could we add a function to give names and tags to the playground demos?

This would be excellent! Being able to mark things as 'incomplete' or as a 'bug' could easily separate these PGs from ones we want to show off or PGs which are a particular step in a tutorial.

 

What about using the tags associated with a forum thread to classify the samples? For example, for a given thread with the tags "morphing", "shadows" and "animation", all PG references in it could have the same tags associated to them? That would be a first step.

 

I have no idea how to actually do this though...

 

EDIT: another idea: referencing as "solutions" the PG linked in posts marked as solved.

Oh! jahow beat me to my own reply.

I am happy to do some front-end dev if it is needed / wanted. HTML / CSS / Javascript type things.

Here is my codepen profile. I think that codepen could provide for some inspiration for functionality for the playground!

[gryff]

Update:  YAY!   I was able to re-read some instructions from DK and understand things better at Azure... and I think I can get the goods.

 

Wingy, I had been saddened by your previous post when I read it on Saturday :

 

I give.    I'm pooped.  [Wingy lays down in the dirt and falls fast asleep.]

 

And, I'm not quite sure where you are headed - but this could be brilliant!   (lost for the right superlative word )

 

cheers, gryff

 

 

 

 

[Wingnut]

Brilliant?  I wouldn't have chosen THAT word.  hah.  Maybe insane.

 

Well, it seems I have obtained permission to distribute, and DK was kind enough to provide all playground resource folders (/textures, /scenes, /scripts, and /sounds)... all are included... in http://urbanproductions.com/wingy/babylon/misc/bjs_pg_db_12JUL15.zip   yay!   SOME copyrights might still be in-force.  Do not assume that any files included in this zip... are royalty-free or cleared for reuse by their creators.

 

Three DB files (different versions of the same db)... all the playground /subfolders, and a small info file.  What a great box lunch, eh?!

 

If you grab a copy and make applications with it, please share them.  Did you make a webpage from one of the db files?  Share it.  Did you add a tags field to each playground and stock it with tags, and then re-make one or all db files?   Then share them, please.  Any apps and/or db-touring systems created, please show and tell.  Thanks! 

 

If nothing else, I'll have a basic web page done in... oh... a month.    Let me know immediately... if there is anything wrong with the archive.

 

Again... that url is... http://urbanproductions.com/wingy/babylon/misc/bjs_pg_db_12JUL15.zip 

 

Thanks DK!   Thanks supporters!   And a BIG THANKS to all you excellent playground demo makers!  Party on!

[Wingnut]

Hi again.  I am already having some fun with the new porta-pg db.  Notepad loads the json, JS says the .json is corrupt, .csv is just a text file, and xml... well... it's all good fun.  I have been torturing the online converters and viewers, making most of them start crying.

 

But, wanna have some fun learning xsl transforms/styles/templates... applied to the xml version?  I knew ya did.  First, grab this.

 

http://urbanproductions.com/wingy/babylon/misc/asXMLwithXSL.zip

 

Yep, its just the xml version of the db... WITH a xsl style sheet installed in its first line.  So, pgs3.xml... is "templated-with" pgs3.xsl... and you can see the results.  Just load pgs3.xml into a (FF) browser... but have pgs3.xsl open in a text editor nearby. 

 

FF only, so far.  It didn't work in IE for me.  Still figging.  It should show a list of the partitionKeys only.

 

See how the 'template' and the 'select' in the xsl... 'filters' and 'wraps' things?  Isn't that cool?  XSL has LOTS of power to "manipulate" the browser-displaying of pgs3.xml.  Do you think xsl could manipulate that xml SO DRASTICALLY... that it could turn it into a BJS scene?  I bet so, but that's just plain demented.

 

Believe it or not, by making the correct adjustments to pgs3.xsl, you can display the xml as a GORGEOUS web table... full colors... nice fonts... links, even include icons and widgets.  It CAN look just like a standard .html web page. 

 

But it's not one. It's styled xml data... and while making it, you will learn all about the power and speed of XSL.

 

Two good things in one!  Have fun!  If anyone "rides along" on my adventures into xsl, feel free to share your xsl with us.  They are small ascii files... and we can show and tell our templates to each other, right?  The best xsl template wins 13 cents and my left sock!

[gryff]

Wingy, I had a quick peak at the csv list. Tried various delimiters without  any success. Then just tried "fixed width" which allowed me to see the script text as a block.

 

I then copied the JsonPayload for one Partition Key (10C9RV) and pasted it into Notepad++, and removed all the \n\r\ s, cleaned out the "JsonPayload": '{"code":" stuff , then removed the \s used to escape text strings, and saved as a .js file.

 

Pasted the code back into the playground - my first test

 

It worked fine - although it might get tedious doing it in this manual way with some of the larger scripts.

 

Looking forward to the methodologies that you are talking about.

 

cheers, gryff

[JCPalmer]

Sorry to jump in at page 8 & only read half that page. Wingnut's threads usually have more words than a slow reader can manage.

Just one thing to remember: some people may have used the playground, never thinking their scenes might become publicly searchable. On my iPad, so I did not check for a use agreement. They probably should not have saved, but they did. Probably no cases, just a reminder.

[Wingnut]

Interesting point, jc.   Are they "their" scenes?  Who owns each of our forum posts?  *scratch scratch*.

 

But yes, I know what you mean, Jc, and thanks for the reminder. 

 

Let's hope nobody has an issue, and if they ever do, see if they can prove ownership. 

 

But, likely, at the first sign of an issue, we would just delete the disputed PG demo from all future distributions of the db.  What else can we do?  I guess we do our best to resolve it, should a situation arise.

 

@gryff... hehe... a good old fashion PG hack-out with a machete, eh?  Too fun.  Nicely done.  The "goods" are not far from reach anymore, are they?  I can smell them.  I love it.  I think we will see a few more "code extractor apps" show-up soon.  I know there are some VERY GOOD data wranglers hanging around here... maybe some of the best in the world.

 

Here's my latest XSL (not the one included in my most recent zip - but a newer one)... http://urbanproductions.com/wingy/babylon/misc/pgs3.xsl

 

Active here:  http://urbanproductions.com/wingy/babylon/misc/pgs3.xml   Still no IE.  Urls and files subject to change without notice.

 

Apply that xsl to your home xml db... for faster render.  Put the pgs3.xsl file into the same folder as your pgs.xml, and make sure the top three lines of the xml... are:

<?xml version="1.0" ?><?xml-stylesheet type='text/xsl' href='pgs3.xsl'?><Entities xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

The second line includes-in the XSL, as you can see.  Easy.

 

Currently, it's just a giant, slow-loading, tags-free, CLICKABLE list... filtered/munged via XSL.  It's been a while since I wrote XSL.  I'm slooooow (actually stupid).  More soon.  Are we off-topic?  :/

[jahow]

Hey guys,

 

I was thinking about this and thought: is it possible to design a better classification & search system for the existing playground demos than this forum already is? I mean, 90% of PG demos (at least the ones holding valuable knowledge) must be referenced in a post somewhere in here. Forum threads are easily searchable, sometimes classified with tags. The 10% left would be referenced from another place, StackOverflow maybe, which is still easily accessible.

 

Why try to beat that?

 

On another hand, I agree that a "user profile" system for the PG would be great, as pathogen suggested: being able to save demos and access them later, classify, add explanations maybe... Although that would sure be some heavy work.

[Wingnut]

Hi J (and everyone).  The reason to try to beat that... is to beat it... speed and ease-wise.

 

By hacking these offline DB's, folks can do all sorts of things.  One thing, is batch-process all the playgrounds and actually add a field in your home db... for found keywords per playground scene.  Not only that, but each user gets to pick WHICH keywords are important to THEM... and not what someone else decided was a good tag to add.  And, these tag-finding batch runs... can be done many times, using different keywords, adding even more metadata to your home db, etc etc.

 

Once you build these various db-with-tags and save them back to disk, the value of the DB has what... doubled?  Now let each user delete PG's that THEY think are not worth keeping.  Everyone gets to decide for themselves... what is hot and what is not.  Cooooooool.

 

Should someone add a tags field to all the current playgrounds in Azure... derived from a many-keyword search of each playground stored there?

 

I think so.  But by doing that, someone else decides what keywords are important, taking that decision out of the hands of each user.   Conversely, with this "hand-out 3-types of db every two years" situation like we just did, we all get MUCH more db-adjusting/searching power... and we put the load... on our home computers.

 

(Wingy offers doobies to everyone.)  Yuh, yuh, yuh, we got the goods.  Now WHO can show us the coolest things to DO with those goods?  C'mon, let's hack db!  I'm expecting a Java applet Babylon JS Playground StaticDataBase Explorer v .001 by month-end.  Let's GO!!! 

 

If you're REALLY hot... your PGDB explorer... is a BJS scene.  Wow!  Walk over to your "Playground Box" in your scene, lift it's lid, and see a playground scene inside.  Its code was put into your computer's copy'n'paste buffer... when you opened the box. 

[jahow]

Wow, you obviously are inspired by all this well, my data-related proficiency is close to zero, and I don't have any skill point left to spend so... good luck with that! I'll keep an eye on this thread

[Wingnut]

I just get excited easily, you've seen it before, J.  I have little purpose in my life, so I blow almost everything out of proportion with over-spirit. 

 

It's just like drama-queening, only in a different direction.  Goofy-queening, maybe?

 

@gryff... do you know that highlight.... then TAB or SHIFTED TAB in the playground... adjusts indenting of the highlighted code?  If you didn't, now you do.  Control-z and shift-control-z for undo/redo?   Bet so.   Control-a, control-c, control-x, control-v, SO many things to remember. 

 

But ONE thing to ALWAYS forget... control-r.  It will ruin your day.  I asked Deltakosh if he would install a "Are you sure you want to ruin your day? Y/N" alert, but it hasn't hit the top of his todo list yet.  (Control-r reloads a web page, and if you do that in the playground and you haven't first SAVEd your edits, you will lose them.)

 

WHO will write the "Everything you ever wanted to know about the Monaco playground editor" docs, and append them into the playground docs?  Huh? 

[jahow]

I've got a nice one: CTRL+/ comments/uncomments the line. Too useful!

[JohnK]

Thank you Wingnut for the downloadable playground files. Today I needed to know how to use onkeydown events in the playground so having previously imported the pgs.xml file into MSAccess I did a quick search for onkeydown in the JSONPayload field, found a couple of examples and was able to work out what to do and put it into the playground I was creating for a post in the forum.

 

Saved hours of work.

 

Any more bright ideas coming up?

[Wingnut]

None from me, John.  hehe.  I don't like the weight of responsibility that comes with having a reputation of "bright". 

 

Ok, but, let's see... here we are in tutorial talk... and Mr. Wingy is about to start causing trouble.

 

Today (and for a while), let's do some tutorial talk about our basic shapes tutorial.  It needs some general updating... but... soon, we will need to include Jerome's {options} option of creating shapes. 

 

Let's give this powerful new feature... an acronym/abbreviation... OOPS.  Options Object Parameter Substitution?  Maybe "stocking" instead of substitution?  *shrug*   Okay okay, that might suck, but I am going to use that term... temporarily, at least.    It saves everyone's fingers.

 

Our good friend Jerome and his team have been working diligently to activate the oops feature for most/all of our basic shapes/elements... yet trying to keep it all backward compatible with our non-oops shape creation.  Not an easy task.

 

My primary concern... is how to integrate Jerome's oops information into our basic shapes tutorial... at least some links.

 

Our basic shapes tutorial is a little crowded, and might need splitting into two tutorials... possibly Basic Shapes and Advanced Shapes.  This would possibly require adjusting of our current Basic Shapes PLAYGROUND, and the need for ANOTHER Playground demo... for advanced shapes. 

 

Possibly, TORUS would be the last shape in Basic Shapes.  Lines, knot, ribbon, tube, spherical harmonics, and static shapes... would all be in Advanced Shapes.

 

By doing this split... we have space to grow, and we have space to "fortify" BOTH tutorials with a good amount-of "How to create this object with oops" talk.

 

If anyone has comments about this, let's hear them... even if they seem strange. 

 

One other possible issue.  As we grow like we are, we MIGHT need to re-think the pulldown "select-o-demo" menu on our playground.  I would love to see us "abstract-away?" one layer.  In other words... I would like to easily change the order and amount of items in that menu... without breaking many links in our tutorials.  And maybe that pulldown menu could be a drill-able tree-o-demos.  For example, there would be a new choice called Parametric Shapes and maybe Static Shapes, and they both could open a submenu of demos... when drilled/clicked/mouse-over'd.  Just a thought.  Comments welcomed... encouraged... begged-for.    Party on!

 

PS:  Ain't it cool that we FINALLY get to see Dad72's handsome face?!   Hi Dad72!!!  Good to see you! 

[GameMonetize]

for the playground we are working on integrating search

 

For a select-o-demo, why not creating a dedicated page in the documentation instead?

[jerome]

I agree : two parts (or more) for the BJS shapes would be nice in the tutorial 

1. discover them... our current tuto, setting apart exotic stuff like ribbons, etc
2. go further, with options 
3. go even further with parametric shapes
4. go to hell with morphing

[JohnK]

Well I do have some thoughts but the danger of giving them on this topic is that people can quite rightly say that the documentation is fully editable so why not make the changes if you have some ideas. From time to time I do think about doing some editing but then get distracted by other interesting aspects of BJS _ my project is ongoing, I am enjoying playing around with polyhedra and tackling the monthly challenge.

Something I cannot tackle would be the drop down menu of the playground a drillable tree of useful demos would be good as a way of quickly looking at examples. It would be very good if this matched the hierarchy of the tutorials after they were edited. Oops back to where I started.

[Wingnut]

Oh John, I am sorry to hear that you feel danger in making suggestions about how our docs system should look/work.  Did you know... that YOUR suggestions about TOC and other things... was heavily-considered and used... for the making of the new docs site?  

 

Want to see how often?

 

http://www.html5gamedevs.com/topic/11844-official-documentation-site/?p=91952

http://www.html5gamedevs.com/topic/11844-official-documentation-site/?p=91766

http://www.html5gamedevs.com/topic/16295-new-documentation/?p=92355

http://www.html5gamedevs.com/topic/4983-tutorial-talk/?p=88406

http://www.html5gamedevs.com/topic/14697-mis-understanding-rotations-and-translations-local-and-world/?p=84723

http://www.html5gamedevs.com/topic/14861-strange-results-when-transferring-meshes-between-scene/?p=84334

http://www.html5gamedevs.com/topic/14697-mis-understanding-rotations-and-translations-local-and-world/?p=83529

 

And you gave us Cubees... and this cool chair!  If anyone has caused this "danger" feeling... you just give me their name... and I'll have a little talk with their mother.    You are a major influence on our documentation, John, and you've written some fine documentation yourself. 

 

These POSSIBLE changes that I propose... are large ones.  I could use everyone's input... because others could have better/different ideas... or fix me when I'm thinking goofy/wrong (often).  Please don't be gun-shy about making edits... or telling me/us what you think.  We're watching ALL the suggestions and weighing them for wisdom.  YOUR suggestions are very important... and so are the suggestions of ALL others.  A VERY IMPORTANT part of commune-ities... is hearing and weighing everyone's "say", and taking those into consideration.  (imho) 

[JohnK]

Major reluctances on my part to give opinions in this instance are because the changes are going to be large and I have only a vague idea of what they should be. So I'll jump in anyway and splash around with my woolly thinking.

 

The introduction could be briefer along the lines of

 

how to

• set up a scene with a camera and a light;
• put simple shapes (box, sphere, cylinder, plane, line and ground(?) in a scene;
• add colour to a shape
• add texture to a shape
• position a shape and set its rotation

Each of these pages would branch to further ones such as

• scene to cameras and lights
• simple shapes to additional shapes and to altering your shapes appearance
• colour to materials and colour
• texture to materials and texture
• positions to transformations

and these would branch out to further detailed explanation. It could also be profitable if some of the questions answered within the forum were incorporated into the tutorials.

 

The thing is that these extra branches would be best if they were also included in separate tutorials. This is much like the structure as it is now but somehow the organisation of this structure would, for me, be better if the organisation was clearer and more coherent.

 

As I said this is a major piece of work to undertake and it could not be undertaken by a team of people unless the underlying structure and its organisation was specified in detail so that individuals in the team knew exactly what was needed and what they could do.

 

This I think would help newcomers to BJS.

 

On the other hand if I look back to when I first came to BJS I came with a certain set of expectations and read the tutorials with those expectations so misunderstood some of the terms. Even with re-structured documentation newcomers will still do the same thing. With the old set of documentation and the help of everybody in the forum I was able to learn and am still learning with the new documentation and the forum. Now I can go to the new documentation and search for what I need and still when I do not understand come to the forum.

 

So I suppose the question is given the amount of work needed to restructure the documentation what would be the benefit to newcomers, existing users, the forum and the authors and other experts and extending the use of BJS. In other words does the cost justify the benefits.

[Wingnut]

  I was only looking for comments on the changes I proposed.  But yeah, these are all good points.  Some of the things you mentioned... are covered by the Babylon Primer.

 

Yep, yep, yep... I once spoke of "layers" of documentation with the docs team, but I was peddling XSL's abilities to "filter" things from a really fat XML document.  In this case, one giant XML document would contain everything on a given subject... and users could select WHICH XSL transformation they would use...

 

1. Give me minimum details

2. Give me medium level of details

3. Give me ALL the details

 

But that system would have been a nightmare to make edits-to, causing editing people to need to know our XML tags, and be able to properly format the XML, so it validates.  Thus, it would have required a special "smart" document editor that had strict rules.  It was deemed too difficult to maintain or implement.

 

In that same breath, you HAVE touched-onto the subject of my proposal.  In a way, you are suggesting that BOX have its own tutorial.  And plane.  And ground.  Each of those tutorials... can "unfold".  They each start by showing JUST the constructor and simple parameters table.  Click something, and then the page "unfolds" to show more details.  Click again, and you get "Everything you ever wanted to know about a box shape".  *nod*.  That would be sweet. 

 

This is akin to your "branches" except the branches would be kept in the same document and not part of another tutorial.  What MAYBE could be done after that... is to concat a document together into one webpage... using the pieces.  In other words, if the user wanted to see ALL the shapes in MAX details... in a single webpage... our system could place all those individual shape docs into "max details" mode, and then concat them together into a single webpage.  To the user, it would APPEAR as one big document about all shapes in maximum detail, but it is really a concat-o-thon... lots of little pieces put together at browse-time.

 

Yup, good thinkings... John.  hmm.  I don't think we have the "system" in-place that could do that, yet, but it's certainly worth pondering.  The HTML for our docs/tuts... is pre-generated from .md files, and these .md files would need to "hold" information about WHAT information is for simple view, what info is for medium-details view, and what info is for MAX DETAILS view.  Currently, .md files cannot do that easily, I don't think.

 

Markdown files (.md) CAN contain html these days, which means DIV's can be created within the markdown... with attributes such as detail="medium".  But the more html we put into the .md files, the more difficult they are to edit.  Let's say a user wants to add a sentence to a section of the BOX tutorial.  When they edit, they would need to make a decision as to WHICH detail-level the new sentence should belong, and make sure they put it into the correct detail-div.  And, they would need to know enough html to format correctly and html-validate nicely.  Plus, CHECKING these new docs for correctness by the curator trying to commit/merge the new doc... would be a slower process, I suspect.

 

Yeah, there's good and bad in allowing anyone/everyone to do edits, eh?  Just like the framework, we want to keep doc editing as simple as possible, and in doing that, we must avoid some advanced features and the potential complexity that comes along for the ride.  hmm.

 

I am definitely going to keep your ideas in-mind, and keep mulling it over.  I hope others do, as well.  Thanks John! 

[Wingnut]

Hi guys.  Today, I mark this thread as closed.  I've been kicking it down the road long enough.  Please use the pinned documentation thread at:

 

http://www.html5gamedevs.com/topic/16365-contributing-to-documentation-101/

 

(although it, too, is stagnated/stalled)

 

Thanks to everyone who participated in this thread.  Party on!

[StarTrekCafe]

ehi. wondering. doing a web based audio game, and using a screen reader, jaws for windows http://www.freedomscientific.com, and now, how to install it and to use it. also how to use the more human soundign voices. did do a hangman text based game in vb 2010 in 2012, but first time doing a web based space invaders gamefor my programming course. so hit a bit of a roadblock. looked at different tutorials, typed up the code, found free gpl images, sounds, sound effects, libaries. so can any one help me out and mentor me, and point me in the right direction. also need to have regions for game updates, multiplayer and play over the net . can any one help me out. marvin.

[Wingnut]

Hi STC!  Well, I hope you found some answers, because Tutorial Talk was on hiatus.  But now it's back!  If you still need answers to those questions, you should start a fresh topic on the forum.  The purpose of this thread... was/is to talk about how/when/where to write tutorials, and all sorts of other documentation issues.  Here, I hope to discuss teaching objectives and methods.  I hope that's cool with you, STC.  You're certainly welcome to join-in.

Hey everyone!

Welcome back to Tutorial Talk! 

Whooda thought... ahh nevermind.

Eric McG, a college teacher of BJS webGL... recently reminded us of some weaknesses we have in our class-file documentation, and other places.  Thanks Eric!

A tiny amount of enthusiasm toward repairing that situation... ensued (in that thread).  Yay!   But...

There are some nut-wrenching issues involved in documenting class statics, properties, and methods.  Let's pick an example:

scene.ambientColor - This sets/gets the scene's ambient color.

The problem with this line... is obvious, literally.  It says something obvious.  It barely says the dataType (a color, but nobody knows color3/4/any).  It doesn't have a demo code line.  Lastly, it doesn't have the "Deltakosh Big Picture"... which we will refer-to as DBP from here onward.  (And to be fair, datatypes and parameters ARE shown in our current class docs... pretty nicely.  The parameter tables for methods... are sweet.)

DBP is not easy to document, because we cannot crawl inside Deltakosh's brain and its memories.  Scene.ambientColor affects all other mesh colors.  It is averaged-into the final colors of all colored mesh (as best I understand it).  But does it affect textured mesh, too?  Does it affect light.diffuse?  Does it affect material.emissiveColor?  Is it averaged-into ONLY all material.diffuseColors and no other material properties? 

Sure, we dockers could "grind" those answers out of the source code, but doing that will quickly discourage us from future enthusiasm for documenting classes.  Still, a certain amount of that... MUST be done.

Rough call, eh?  Too much info/text in the webpage for a class... will make it difficult to find information.  They will become cluttered with text.

But... what if... there was a "more info" link next to class items... on their webpage?  What if we "branched-away" somewhere... to a "class_descriptions" (md/json) file that was included-in during our docs build?  Would that be a wiser way?  My intuition says "yes", but I've learned not to trust my intuition all that much.    MD files for a class... would no-longer present ANY text on a class's web page (initially). 

With this system/way, ALL descriptions... for every static/prop/method... would ONLY be available after clicking a "more info" link adjacent to each.  If clicked, it presents the description and a potential crap-load of DBP... somehow.  Class web pages would (by default) present/maintain a very "clean look", by doing this. 

This method might also be a nightmare for the folks who coded our documentation system.  So, let's not go crazy over this idea... until we speak with the elders.

I think we all (both people reading this) understand the issue.  This is what Eric McG was asking with "is there a plan?"  Well Eric... there is not, because the framework is growing and changing at such a high rate of speed... that the documentation got away from us.  The system didn't.  Deltakosh and Temechon and the team... did a GREAT job at building a wonderful documentation "engine"... I love it (though it scared me at first).  The rest of us... simply have not utilized that new, wonderful system very much at all.  We have a gorgeous documentation system... but it is sorely low on content.  Part of that is my fault... I apologize.  Real life circumstances get in the way (even though this is also real life).

ANYWAY... welcome back to Tutorial Talk... I hope we get some participation.  Let's hear your opinions, gang.

[GameMonetize]

Agree with you. Community is not really "motivated" to help on the doc:)

For my part I'll start adding real example directly in the code to get more info in the classes section of the doc. Like this: https://github.com/BabylonJS/Babylon.js/blob/master/src/Debug/babylon.skeletonViewer.ts#L3

 

Once again, you may not feel good enough to contribute (which is wrong :)) but writing some comments / doc could then feels more easy to achieve !

[Wingnut]

Hi DK.  Actually, I am against documentation within the code.  Comments are good, but they could/should be for yourself and/or for other framework programmers.  Those in-source demo URLs and information... go stale, quickly and easily.  And, we probably don't want dockers (people who document) to mess-with the source code.  (imho)

Not only that, but, it is my opinion that core coders should not have to document much at all.  They already do lots of work, and battle many issues.  I think dockers should write the documentation... and ONLY inside the class .md files.  WE (dockers) would gather documentation from...

- info that framework programmers have already told us on the forum
- info discovered by studying demos and tests
- info discovered from studying source code
- info from sometimes asking questions to framework coders (we have done lots of this, already)

Ideally, framework coders COULD periodically scan our webpages, and make sure that the dockers didn't say wrong things.  Saying wrong things is one of my biggest fears, in doc writing.

Your intentions are wonderful, DK, but I believe the source code is the environment of the coders, not the dockers.  Comments in source code should be targeted-for the framework coders.

I don't know much about the docs builds, yet... but... it seems that some class web page information comes from source code, and some comes from the class .md file.  (I should go look-at what a class .md contains, eh?)  During a build (or possibly during a separate batch run), the info gathered from source code can change for every framework version.  The info located-within and gathered-from .md files... carries-through from version to version.

But, I think I heard Temechon tell me... that the class .md files are derived/created...  during a separate batch run (not done during standard build).  That batch engine might combine info found in source code... with info found in the previous version of the .md file.  If this is correct, class md's are not re-derived during our normal doc builds.  I think I remember hearing him say that.

My HOPE... is/was to remove workload from the code contributors, and add workload to the docs contributors (dockers).  Framework coders CAN be dockers, too  (particularly for systems they coded)...  but DK, in the forum... YOU have already told us LOTS about the code you have written, and provided many demos and videos  (Other framework coders have also talked about their coding well, too).  The dockers should be the ones to handle it... from here.  Our non-code-contributing forum users... are VERY intelligent, and we have the potential to form a very good, and very large... team of dockers.

In the same breath, I think that "team of dockers"... is somewhat scared of github.  I am not sure what to do about that, yet, other than telling my stories of building my own documentation workflow environment.

Just thoughts.  *shrug*