Good Practices when contributing to the documentation

I had the idea to add a mini-guide on Improve Documentation - Babylon.js Documentation, do you think it’s useful, and of course are there any rules which are wrongs? (i’m thinking about the link section for example)

Below is my first drop:


Good Practices

General

  • if you’re not familiar with markdown, you can read this short Github guide
  • even if you’re seeing just a tiny typo, feel free to do a pull request dedicated to it
  • do one commit per tasks, a pull request can take into account multiple commits if needed
    • example: if you have two pages to modify, once the first page is edited, do a commit
  • tables can be a great help for readibility

Images

  • use and store images from the documentation FTP as much as possible, read Adding new images
  • be careful about image size (tip: Photoshop have a “Save for the web” export)

Code

  • when showing a javascript bloc of code, tell to markdown that it’s javascript to be sure having syntax highlight:
    ```javascript
        var myWonderfulCode = this;
    ```
  • when quoting a property in a sentence, you can use single ` char
    • example: You can set the roughness of a PBR material to 1.

Links

  • use lowercases on your url
    • example: /how_to/ in place of /How_To/
  • use relative links
    • example: [Load Files with Assets Manager](/how_to/how_to_use_assetsmanager) instead of [Load Files with Assets Manager](https://doc.babylonjs.com/how_to/how_to_use_assetsmanager)

Further Reading

  • try to always add a Further Reading section
  • sort Further Reading using main documentation sections (Babylon 101, How to, etc)
  • use markdown list
  • do not hesitate to link API relative to the article

Example:

# Further Reading

## Babylon 101

- [How to get Babylon.js](/babylon101/how_to_get)

## How To

- [Use the glTF File Loader Plugin](/how_to/gltf)
- [Use the OBJ File Loader Plugin](/how_to/obj)
- [Use the STL File Loader Plugin](/how_to/stl)
- [Load Files with Assets Manager](/how_to/how_to_use_assetsmanager)

## Resources

- [Available Meshes for Importing into Playground](/resources/meshes_to_load)
- [Using External Assets in the Playground](/resources/external_pg_assets)

## API

- [SceneLoader](/api/classes/babylon.sceneloader.html)
7 Likes

I’m alll in! This is exactly what we need: short and easy to read tutorials

2 Likes

Tables are much more readable than a lot of pros.

header col 1 col 2 col 3
item 1 Yes No Only attempt when there is a full moon, on a leap year in a time zone which has a population under one billion termites. Making this excessively long to show wrapping.
item 2 Yes Yes Maybe
1 Like

Yep, great idea to encourage the use of tables when needed.

Hi girls. Um, is anyone “on the inside”… reading here? Anyone paid… who could build the glossary system? I think that is important… terminology. The less hand-holding of term definitions inside docs, the briefer they get. With auto-linked hot-click glossary system, docs authors can use precision/perfect terms… and if user doesn’t know the term, click on it to open the definition in a new/popup window.

Could be used for forum, too… but it would be a custom forum plugin, and last I heard, admin wants vanilla or near. But, having certain terms… LINKED to “click this term to see definition”… within forum posts… would be nice. Same glossary DB/autolink system used in docs. Glossary building is lots of work… and should have a “boss”… I suppose.

Like all docs-based pros,they should speak, write, and punctuate English reasonably well, should spell-check, should proofread, and should send puppies thru the docs… to make sure they can understand/learn it. (heh - yeeeah).

We should ask @JohnK what HIS definition of a 101 doc is, and what a How-To doc is… and if there are also other categories in his mind.

If there’s budget for a paid 3d-nut English teacher glossary-maker/maintainer (who loves making diagrams for beginners, too)… then things… open-up. JohnK can brief this person on “the game plan” and we can all make added suggestions… but later… this person is “the final approver” with full editing/rejecting powers… and JohnK having a reduced workload, yet powerful supervisory/advisory input to this new paid person.

sigh. We talked about some stuff in the old Tutorial Talk thread, didn’t we (I)?

I guess, for now, if Vinc will entertain it in his thread…

What are the thoughts of having a Docs Czar… and shutting off all docs PR’s for general public, but opening a wide and friendly door to “Request a docs mod from the Docs Czar”?

And this is highly related to if/not Team Babylon has budget and gumption to afford/justify/substantiate a full-time Docs Czar.

Is the “foyer” to Babylon Palace… worthy of a full set-dressing… doors for advanced programmers, doors for adult hobbyists, doors for artists, doors for busyness, and doors for kids (and maybe doors for weak English speakers/readers). Do we want to “shopping mall” the entrances to BJS? Something for everyone?

Scary thinkin’s, huh? nod. “The Faces of Babylon”… the interface unto the people of the world. Should it try to form-fit and/or flex-to-fit… the type of person that comes a-visiting? It seems to me… that terminology (the BJS Glossary of Terms)… is an early step… in that endeavor. Common terms, good step one.

Sorry for going so deep, but there was no mention… of some pertinent things, so far… like good English, spellchecking, proofreading, diagrams, and whether there was budget, including why & why-not.

We should probably close the docs-editing to everyone except folks on Team Docs, as uppity as that may sound. It’s likely that all these “suggestions” will already scare-off most people who are not paid-to-document. thoughts? Thanks for the thread, Vinc… it’s a sign of caring… a good thing.

From time to time I do think that the docs could do with a consistency overall. Trouble is I a bit of a that’s good enough type and a bit lazy.

The picture on the home page more or less gives my thoughts on the overall structure Babylon.js Documentation but it can be difficult to decide what goes where.

My thoughts are that Babylon101 should give start tutorials to the basic features of BJS and the How-To section goes into more depth. The features section should be a partitioned listing describing what BJS can do with links to relevant parts of the docs be it 101, How-To, API etc. In parts this does happen but in many parts pages do the work of other sections.

What would be really good would be further menu divisions so that you would have How-To > Mesh > Create and How-To > Mesh > Edit menus.

The API should have more links to the docs and vice versa (but here I am the kettle calling the pot black. I know I have added code to BJS and then never got back to adding @see comments to the code)

Also the playground links in the API do give some help but they are not specific enough, especially due to the unstructured form of PGs. It would be good to have a link to specific PG.

Whilst it is good to have a template for a page in the docs as it is open sourced I agree @Wingnut you will never get everybody to follow it. Hell even I don’t always follow the template I laid down for me.

The docs are generally liked and relatively good compared to many but to be really great they would need a paid docs guru.

I suppose its a question of would the improvements made by a paid docs guru be value for money and how would you judge this.

1 Like

@Vinc3r Given my long post above the answer to your original question is yes I think that a page outlining a structure for a docs page along the lines you suggest would be good and they are good suggestions.

Hey All,

Chiming in on this thread. First thanks for all your passion and interest on this subject.

Keep in mind that everything that follows is mere opinion…totally open to other thoughts on the subject.

When I think about our docs, there are 3 things that I consider as important

I think our docs should be:

  1. Open
  2. Well Organized
  3. Simple

Here are some extended thoughts on each one:

  1. Open - I personally would like to see contribution to our docs continue to be be as open as possible to everyone. Any time anyone would like to make a change, from a small grammatical edit, to a full page and feature doc…I believe anyone should be able to do that. This has always been an open community and I’d love to see our docs continue to embrace this “priority.” That said…

@Wingnut and @JohnK, I totally understand the appeal of the idea of having a gatekeeper or a team of gatekeepers to maintain a degree of quality, consistency, and organization to our docs. This is definitely an interesting idea and something that we should continue to chat about, but I do believe it should still allow the contribution to the docs to be open to all.

  1. Well Organized - Perhaps self explanatory, but I’m aligned with @JohnK on this one. As pointed out earlier, this image is indeed a solid organizational structure and has served us well.

Deciding what goes where isn’t always easy…agreed. This could be another solid benefit from having a gatekeeper or gatekeeper(s) agree to help people figure this out…make themselves available to help, and be willing to reorganize if things go into the wrong spot.

  1. Simple - This is subjective…what is simple for one person isn’t always simple for another. We all have different experiences and knowledge about different things. For docs, I think about ways that we can appeal to all knowledge levels. Personally I think the Babylon101 course is a great start for folks just starting their Babylon journey. However we have lots we could do to make it even more simple. For those who are further along in their learning…How To’s, Classes, and Samples, are great resources and areas that can go deeper. Overall no matter what we’re writing for documentation, I think it would benefit us all to ensure we are NOT assuming our audience/reader has all of the knowledge that we have.

Finally on the subject of an occasional consistency overhaul…I couldn’t agree more. Any time you have a vibrant community of folks all working together, things won’t always be perfect and that’s ok! We absolutely should feel empowered to occasionally go through and reorganize, re-categorize, and redo anything that we feel would be helpful to the community at large.

I love this topic and will gladly volunteer to help drive this effort for us all.

Sorry for the long post, just very excited about the topic!

Helping people learn about Babylon is a true passion of mine!

Thanks!

3 Likes

Cool replies, guys. No talk of glossary-of-terms, though, huh? To me, having links to definitions of terms used in a doc… is the “learn more about this” for the noobulites, yet an easy “read past it” for the pros who already know what a “render target texture” is. :slight_smile:

BUT… to make a docs build… automatically insert links to our “Glossary of Terms” database… the terms always have to be spelled correctly and used consistently… or else the “look-up” and auto-linking won’t find the term in the database.

The Glossary would also have it’s own webpage… for general “terminology used in BabylonJS” page-touring. But the real magic… would happen during the docs “build”. Maybe we extend G-markdown a bit… so that any time during the build… &&dot product&& or similar… would be checked against the glossary to see if a link-to-a-definition is available. Ideally, the same action could be used in the forum posts. Insert &&render target texture&& in a forum post, and at post-time, a lookup in the glossary DB happens, and if “render target texture” is found, a link to it’s definition… is inserted in the post… auto-magically.

Failed glossary look-ups would fall-back-to removing the leading and trailing &&, and inserting the term without an auto-link-to-def.

Ok, I’m dreaming, right? :slight_smile: I just remember the old days (yesterday)… when I would be reading a doc about something, and I would hit a term that I didn’t know it’s meaning. Often, I would have to “take a tangent” to go lookup what the term means, and THEN return to the doc… and read–on until I hit another. With “click it to get its definition” feature… that tangent is faster/shorter… not interrupting the “learning flow” so much. shrug

Sort of like “flash cards”… remember those? 3x5 recipe cards with term written on front, and definition of that term… written on back. And those wanting to learn fast… paired-up, and flashed those cards at each other… helping each other learn quickly. It’s like having an automated dictionary of 3D terms… traveling-along with your docs-reading eyes.

If we COULD accomplish this… we have made our docs for multiple-expertise levels. But instead of links to dig deeper for more advanced stuff, this would be links to dig deeper for more explanation (dig for additional ‘simple’). A slightly different approach, which COULD lead to smaller docs… and smaller docs are also simpler docs, from a certain perspective. Simpler, because we never need to hold a reader’s hand along the way, explaining what a render target texture or a dot product… is. We just use the term, and the docs build makes it a link, and noobs can click’n’learn, and wizzies can read-on, without sitting thru definitions of terms they already know.

It might be pretty big… and likely will evolve and grow for years. It probably can’t be realized… without a budget. HAD this idea/feature been entertained and started way back when we first proposed it… we’d be half-done with it, by now. And, it COULD add perhaps 3-4 minutes to a docs build… depending upon how heavily used. There could be all sorts of problems with it, many unforeseen by my short-sighted view. But IF we could make it happen… we’d be famous. :slight_smile: Khronos would be knockin’ on our door… asking if they could have a copy of our glossary db… for a starter DB on THEIR site. :slight_smile:

They know. They know that bringing-in “fresh meat” to webGL… starts-with “friendly” and “thorough”. But the question is… do we WANT “fresh meat”… or do we want programmers? The lack of girls in webGL land… is an indicator of something. Likely, it is an indicator that something is unappealing.

1 Like

It’s a super rad idea @Wingnut. It could be really powerful to help people who are just starting out.

If I’m understanding this idea correctly, you’re thinking that we’d automatically search through our documentation any time there’s a PR, and we’d do a search against a glossary. Then any words found in the glossary would be automatically turned into links that take you to perhaps the glossary of terms page, or maybe link to a different piece of documentation or even wikipedia in some instances? Does that sound right?

If I’ve got that correct, we’d need 2 things:

  1. a glossary of terms and a definition or link associated with that term…basically the lookup table.

  2. build the system to parse the documentation and insert links with glossary terms.

To put this into action, I’d say this…if the community can collectively accomplish the first thing, then the dev team can handle the second piece.

So we’d need the community to create the glossary page with all of the terms and associated definitions/documentation links/etc. As you said above, perhaps any time we don’t have a documentation page, but we DO have a definition, then we simply take you to the glossary page.

Hope that all makes sense. It’s definitely a rad idea, but we’ll need the community to help by pulling together the first part.

-PirateJC

1 Like

Yep, super noob helper, and thx for the kind words and interest, JC. This might not happen at PR time, but COULD. I was thinking… just let the docs author insert &&term&& whenever THEY felt like it. They could check the glossary main webpage to see if that term DOES have a record in the DB… before inserting the &&term&&. In this case, nothing would happen at PR time… but the insert would happen at “build .md into .html” -time.

But yeah, at-PR-time is an interesting approach, too. More work, perhaps, because the PR action would search every word in the .md… for hits. Maybe still use the && trigger chars? not sure.

Actually, this is where ‘the czar’ would come into play. The glossary czar decides what terms are allowed in the glossary, and which aren’t active enough to warrant inclusion. To try to get “the community” to build that… hopeless, I think. In this case, I think it is wise to allow any user to submit any term/definition as a candidate for inclusion… but the glossary czar has the final say.

As soon as you let “the community” have a say… we lose cohesion and adherence to rules/criteria. Goofy additions… arguing… discussing things to death (I’m a pro at it)… it turns into a giant decision-by-committee festival, and often that causes a Purina Gravel Chow face plant for the entire project.

Nope, I think it has to be the other way around. “Authorities” determine what terms, and what KIND of terms… are allowed in the (multi-categoried) glossary of terms.

@nasimiasl has our old forum… in a “form” that is “glean-able”. We once talked about “harvesting” the old forum… to derive a “most used terms” list… but I don’t know what he tried.

How about the community gathers “candidates” for the glossary, but The Council of Glossary Chiefs decides which are good ones, and which are bad… and somebody has to keep listening for more candidates… for years… and somebody has to write the definitions or borrow them from wikipedia or Khronos or whatever. Sometimes, a definition of a term… could be near a full page of text… erf. it might require multiple diagrams, too.

I think… we need one paid, dedicated to docs… full time employee… who is an English teacher and 3D expert… in one package (who loves to type). :slight_smile: Would adding a team member to do ONLY docs and docs-related work… take-away potential raises/employment-longevity… from others on the team? Or is there plenty of room for expansion? Perhaps someone who is already an MS employee but could dedicate 50% time to our cause? hmm. I don’t know much about how the BabylonJS Team at MS… operates… or how stressed it already is, financially.

I don’t know if we “littles” are ALLOWED TO know that info. :open_mouth: And without having that info, I am/We are… sort-of “feeling around in the dark”.

1 Like

Yeah, branches/trees. Yum! (hi5). Lots of work/maintenance… like all docs structures.

Later, when we make the 3d interface to the docs (using popup GUI 2d panels in the scene)… we might be clicking “actual”-ish trees, limbs, branches, twigs, and leafs.

Docs3d… using MeshWriter flyable fonts or GUI-2d panels… “Your one-stop for a VR head-gear migraine headache.” :slight_smile: Arriving - 2022.

(SOME will even code JS… inside the scene… while wearing the VR head gear! Crazy, man! They say they would rather work inside skyboxes… than inside cublcles.) hmm. :slight_smile:

1 Like

Yes then the leaves would be the descriptions and you could have fruit for API part and the seeds the particular playground. Then you would need docs to instruct how to use the 3D docs which themselves could be turned into 3D docs and so on ad infinitum :crazy_face: :crazy_face: :crazy_face: :brain: :boom:

1 Like

Let’s dream more; how about those flash card popping up when you hover over a term like happens in Wikipedia

image

The pop up could then have links which, where appropriate to further (internal or external) explanations, to the API, and a specific PG.

@Wingnut could you point us to one page that could benefit from having terms needing ‘flash cards’ naming two or three of those terms.

The starting point would as @PirateJC suggests a glossary of terms. I could take the index I started but which is rarely kept up to data and create a list of potential terms for the glossary. As they say the longest journey starts with a single step.

1 Like

https://doc.babylonjs.com/how_to/use_hdr_environment

HDR, KTX, IBL, ENV, RGBM, RGBD, roughness, MipMaps, blur dropoff, polynomials harmonics, artifacts, blocking quality, LogLUV, halfFloat. A few more than 2-3, sorry. :slight_smile: That’s a good hot topic that is up on the bleeding edge. :slight_smile:

Click-on or hover-over. Those who highlight text for some reason (often in prep for a paste-into web search page)… would likely prefer the click to the hover. And, does hover exist for touch screen users? I don’t think so. shrug. Thx for interest in this, JK.

Maybe we should branch-away to a different thread. Vinc/others… do you guys have some preferences on that? Maybe “Ideas for Advanced Docs”? shrug. I’m easy… any decisions others/admin make about that… is fine with me… if okay with others. Freely move my posts.

hahah. Yuh. :slight_smile: FUNNY! Tangled in circular drilling.

Also on the 3d-docs subject, I wonder how near we are… to putting a SMALL advancedDynamicTexture-for-a-mesh… atop an already-textured mesh (compositing). ADT’s as decals. Yeah. “Weighted Composited Materials” (Wingy nudges @Pryme8). Up to 10 overlayed materials on a mesh… with “priority weighting”. heh. (My GPU is shaking a scolding finger at me, right now.) :slight_smile:

We want the trees, limbs, branches, twigs, leafs, fruit, nuts, etc… to maintain their correct texture… yet paste a clickable text-label atop. GPU labels 1.0? hmm. Nah, GPU probably won’t allow us to have powerful JS control over the offset/scale/wrap/ang… of the ADT-decal.

Way gone side-note: How about… each vertex of a model… CAN hold a setting… of material10 weight-priorities? In other words… when a mesh has a 10-pack of materials applied… each vert is allowed to set WHICH of the 10 materials… has priority… when the 10 materials is mapped “across” it. WOW! It does automatic material-dithers like our color-per-vertex colorKind system often produces… but they could be texture-to-texture dithers, or color-to-texture… etc. That’s just crazy… but @nasimiasl proved to us… that texture-to-texture dissolve/dither… rocks! https://www.babylonjs-playground.com/#1IAR36#15 (Hey, I didn’t invent CorelDraw, I just learned about the fun with its layers-o-composites)

Anyway… labeling in 3d… still has much advancing to do. Mouseover popup labels probably don’t work on touch, but COULD work on VR gaze… maybe annoyingly. For VR, probably glove/thimble/air-mouse… to feed standard mouseover/click systems.

How about both, hover when available gives a short summary, click to a page.

Here are 344 words taken from the index page. The list contains plurals and some unnecessary words. Still an awful lot to deal with. Perhaps a JSON file on github would be needed where the community could edit in descriptions and/or links and additions.

About             	Field             	Optimization      	Shadows           
Actions           	Fieldset          	Optimize          	Shapes            
Advanced          	File              	Orientation       	Show              
Ambient           	FileFormat        	Overview          	Side              
Anaglyph          	Frame             	Own               	SideOrientation   
Angles            	Framework         	Panel             	Simple            
Angular           	FresnelParameters 	Parallax          	Skeletons         
Animated          	Gamespads         	Parent            	Sky               
Animation         	Generator         	Particle          	Skybox            
Animations        	glTF              	Particles         	Slider            
Applying          	Gradient          	Path              	Slow              
Approved          	Gravity           	Path3D            	Snippet           
Arc               	Grid              	PBT               	Snippets          
Art               	Ground            	Physically        	Solid             
Ascii             	Group             	Physics           	Sounds            
Assets            	GUI               	Picking           	Special           
Axes              	GUIs              	Picture           	Sphere            
Babylon           	Height            	Pine              	Spinner           
Babylon.js        	Heightmap         	Pipeline          	Spot              
Back              	Hemispheric       	Pivot             	Sprites           
Background        	Highlight         	Placing           	SPS               
Baking            	HTML              	Plane             	SSAO              
Behaviors         	Importer          	Play              	Standard          
BJS               	Incremental       	Playground        	Start             
Blend             	Individual        	Playgrounds       	Started           
Blender           	Influence         	Plugin            	Starter           
Bone              	Inputs            	Point             	STL               
Bones             	Installing        	PointsCloud       	Studio            
Box               	Instances         	Polygon           	Study             
Buffer            	Integration       	Polyhedral        	Sub               
Build             	Introduction      	Position          	System            
Builder           	Ionic             	Positioning       	Systems           
Bump              	Issues            	Post              	Tags              
Button            	Joysticks         	Post-Process      	Targets           
Cached            	Knot              	Probes            	Template          
Camera            	Label             	Procedural        	Terrain           
Cameras           	Lathe             	Process           	Text              
CastorGUI         	Lava              	Processes         	Textarea          
Cell              	Layer             	Programming       	Textfield         
Checkbox          	Layermasks        	Progress          	Texture           
Cheetah3D         	Legacy            	Quaternions       	Texturel          
Cinematic         	Lens              	Queries           	Textures          
Cloner            	Library           	Quick             	The               
Code              	Light             	Radial            	They              
Coded             	Line              	Radio             	Tiled             
Collisions        	Line2D            	Rain              	Tiling            
Color             	Linear            	Random            	Tips              
Combine           	Lines             	Raycasts          	Torus             
Compressed        	Loading           	Reactjs           	Transform         
Cone              	LOD               	Realirty          	Transformations   
Constants         	Logarithmic       	Realism           	TransformNode     
Conventions       	Manager           	Realtime          	Translate         
Coordinates       	Managing          	Reduce            	Transparency      
Create            	Map               	Reference         	Transparent       
Creating          	Mapping           	Reflection        	Tree              
Creation          	Material          	Refraction        	Tri-Planar        
Culling           	Materials         	Regular           	Tube              
Curve             	Matrix            	Render            	Tutorial          
Curves            	Maya              	Rendering         	Tutorials         
Customize         	Merge             	Resources         	Understanding     
Cylinder          	Mesh              	Ribbon            	Unity             
Decals            	MeshBuilder       	Ribbons           	Universal         
Default           	Meshes            	Road              	Update            
Depth             	Meter             	Rotate            	URL               
Device            	Method            	Rotating          	Using             
Dialog            	Minified          	Rotation          	Vectors           
Digital           	Minimise          	RTS               	Version           
Disc              	Modes             	Samples           	Versions          
Display           	Morph             	Scaling           	Vertex            
Dynamic           	Mouse             	Scattering        	Vertical          
Edges             	Moving            	Scene             	Vertices          
Effector          	Multi-Camera      	SceneOptimizer    	Video             
Effects           	Multi-Materials   	Scenes            	Virtual           
Emitters          	Multi-Platform    	Screen            	Visual            
Engine            	Multiple          	Screenshot        	Volumetric        
Engines           	Multi-Scenes      	Select            	VR                
Environment       	Multi-Views       	Selected          	Water             
Euler             	Normal            	Sequence          	Wave              
Events            	Normals           	Server            	Web               
Exporter          	NPM               	Setting           	WebGL             
Extruded          	OBJ               	Setup             	WebGL2            
Face              	Object            	Shader            	WebVR             
Faces             	Observables       	ShaderMaterial    	Window            
Facet             	Occlusion         	Shaders           	Wood              
Facets            	Octrees           	Shading           	Work              
Features          	Opacity           	Shadow            	World             

1 Like

Excellent example, lots there I don’t know.

Scary. Who’s checking accuracy, thoroughness, English, punctuation, length/brevity, etc. One way to get instant inconsistency… open it up to the unqualified. (sorry, there might be some lingering “rigidity” from my 9 yrs of US Air Force… too much marching/rules… regimentation.) :slight_smile:

We need to stare-at that MS budget allowance for BabylonJS Team, and see if it will leak (reveal) its flexibility. I think the project is doomed… if not budgeted… BECAUSE it IS very big, and because we need it done right… no slop… no mis-steps. Too big… too much lost work if it flops. It needs a sure-footing, me thinks.

Yeah, I hear your thoughts. Corporate budget allowances are rarely “sure-footed”. It’s somewhat wiser to count-on volunteers… than counting-on accountants and market trends. sigh.

Wow, a lot of ideas here! :smiley:

Glossary sounds great, but as you already say, the first shot will be huge to write.

(meanwhile, Good practice first version is online)

3 Likes

I prefer the click on version (or both) just for accessibility sake