# Good Practices when contributing to the documentation **URL:** \ **Category:** Questions\ **Created:** [December 6, 2019, 12:03pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416 "2019-12-06T12:03:36Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![Vinc3r](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/vinc3r/32/25340_2.png) [@Vinc3r](https://forum.babylonjs.com/u/Vinc3r)\ **Post date:** [December 6, 2019, 12:03pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/1 "2019-12-06T12:03:37Z")
I had the idea to add a mini-guide on [Improve Documentation - Babylon.js Documentation](https://doc.babylonjs.com/how_to/contribute_to_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](https://guides.github.com/features/mastering-markdown/) - 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](https://doc.babylonjs.com/how_to/contribute_to_documentation#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: ````markdown ```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: ```markdown # 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) ``` ---
**Author:** ![Deltakosh](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/deltakosh/32/26635_2.png) [@Deltakosh](https://forum.babylonjs.com/u/Deltakosh)\ **Post date:** [December 6, 2019, 2:57pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/2 "2019-12-06T14:57:43Z")
I’m alll in! This is exactly what we need: short and easy to read tutorials ---
**Author:** ![JCPalmer](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/jcpalmer/32/42_2.png) [@JCPalmer](https://forum.babylonjs.com/u/JCPalmer)\ **Post date:** [December 6, 2019, 3:51pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/3 "2019-12-06T15:51:41Z")
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 | ---
**Author:** ![Vinc3r](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/vinc3r/32/25340_2.png) [@Vinc3r](https://forum.babylonjs.com/u/Vinc3r)\ **Post date:** [December 6, 2019, 3:55pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/4 "2019-12-06T15:55:55Z")
Yep, great idea to encourage the use of tables when needed. ---
**Author:** ![Wingnut](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/wingnut/32/53_2.png) [@Wingnut](https://forum.babylonjs.com/u/Wingnut)\ **Post date:** [December 6, 2019, 5:16pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/5 "2019-12-06T17:16:34Z")
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](https://www.html5gamedevs.com/topic/4983-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. ---
**Author:** ![JohnK](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/johnk/32/26764_2.png) [@JohnK](https://forum.babylonjs.com/u/JohnK)\ **Post date:** [December 6, 2019, 6:20pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/6 "2019-12-06T18:20:20Z")
> [@Wingnut](#): > > 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. 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 [Home | Babylon.js Documentation](https://doc.babylonjs.com/#documentation_overview) 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. ---
**Author:** ![JohnK](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/johnk/32/26764_2.png) [@JohnK](https://forum.babylonjs.com/u/JohnK)\ **Post date:** [December 6, 2019, 6:23pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/7 "2019-12-06T18:23:51Z")
@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. ---
**Author:** ![PirateJC](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/piratejc/32/1003_2.png) [@PirateJC](https://forum.babylonjs.com/u/PirateJC)\ **Post date:** [December 6, 2019, 7:13pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/8 "2019-12-06T19:13:53Z")
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](https://doc.babylonjs.com/#documentation_overview) 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! ---
**Author:** ![Wingnut](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/wingnut/32/53_2.png) [@Wingnut](https://forum.babylonjs.com/u/Wingnut)\ **Post date:** [December 6, 2019, 10:18pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/9 "2019-12-06T22:18:51Z")
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. 🙂 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? 🙂 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. 🙂 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. 🙂 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. ---
**Author:** ![PirateJC](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/piratejc/32/1003_2.png) [@PirateJC](https://forum.babylonjs.com/u/PirateJC)\ **Post date:** [December 6, 2019, 10:40pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/10 "2019-12-06T22:40:26Z")
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 ---
**Author:** ![Wingnut](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/wingnut/32/53_2.png) [@Wingnut](https://forum.babylonjs.com/u/Wingnut)\ **Post date:** [December 6, 2019, 11:03pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/11 "2019-12-06T23:03:29Z")
> [@PirateJC](#): > > 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. 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. > [@PirateJC](#): > > So we’d need the community to create the glossary page with all of the terms and associated definitions/documentation links/etc. 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). 🙂 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. 😮 And without having that info, I am/We are… sort-of “feeling around in the dark”. ---
**Author:** ![Wingnut](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/wingnut/32/53_2.png) [@Wingnut](https://forum.babylonjs.com/u/Wingnut)\ **Post date:** [December 7, 2019, 12:01am UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/12 "2019-12-07T00:01:40Z")
> [@JohnK](#): > > 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. 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.” 🙂 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. 🙂 ---
**Author:** ![JohnK](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/johnk/32/26764_2.png) [@JohnK](https://forum.babylonjs.com/u/JohnK)\ **Post date:** [December 7, 2019, 9:51am UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/13 "2019-12-07T09:51:01Z")
> [@Wingnut](#): > > we might be clicking “actual”-ish trees, limbs, branches, twigs, and leafs. 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 🤪 🤪 🤪 🧠 💥 ---
**Author:** ![JohnK](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/johnk/32/26764_2.png) [@JohnK](https://forum.babylonjs.com/u/JohnK)\ **Post date:** [December 7, 2019, 10:19am UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/14 "2019-12-07T10:19:55Z")
> [@Wingnut](#): > > Sort of like “flash cards”… … It’s like having an automated dictionary of 3D terms… traveling-along with your docs-reading eyes. Let’s dream more; how about those flash card popping up when you hover over a term like happens in Wikipedia ![image](https://us1.discourse-cdn.com/flex024/uploads/babylonjs/original/2X/0/0c434e660ea1dcf4d95e122ceca3a010003d5af4.png) 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](https://doc.babylonjs.com/resources/documentation_category_map) 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. ---
**Author:** ![Wingnut](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/wingnut/32/53_2.png) [@Wingnut](https://forum.babylonjs.com/u/Wingnut)\ **Post date:** [December 7, 2019, 2:11pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/15 "2019-12-07T14:11:02Z")
[https://doc.babylonjs.com/how\_to/use\_hdr\_environment](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. 🙂 That’s a good hot topic that is up on the bleeding edge. 🙂 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. > [@JohnK](#): > > 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 🤪 hahah. Yuh. 🙂 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.) 🙂 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](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. ---
**Author:** ![JohnK](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/johnk/32/26764_2.png) [@JohnK](https://forum.babylonjs.com/u/JohnK)\ **Post date:** [December 7, 2019, 3:21pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/16 "2019-12-07T15:21:48Z")
> [@Wingnut](#): > > 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? 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. ```auto 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 ``` ---
**Author:** ![JohnK](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/johnk/32/26764_2.png) [@JohnK](https://forum.babylonjs.com/u/JohnK)\ **Post date:** [December 7, 2019, 3:24pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/17 "2019-12-07T15:24:41Z")
> [@Wingnut](#): > > HDR, KTX, IBL, ENV, RGBM, RGBD, roughness, MipMaps, blur dropoff, polynomials harmonics, artifacts, blocking quality, LogLUV, halfFloat. A few more than 2-3, sorry. 🙂 That’s a good hot topic that is up on the bleeding edge. Excellent example, lots there I don’t know. ---
**Author:** ![Wingnut](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/wingnut/32/53_2.png) [@Wingnut](https://forum.babylonjs.com/u/Wingnut)\ **Post date:** [December 7, 2019, 3:30pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/18 "2019-12-07T15:30:32Z")
> [@JohnK](#): > > the community could edit in descriptions and/or links and additions. 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.) 🙂 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 ac_count_ants and market trends. sigh. ---
**Author:** ![Vinc3r](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/vinc3r/32/25340_2.png) [@Vinc3r](https://forum.babylonjs.com/u/Vinc3r)\ **Post date:** [December 9, 2019, 1:04pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/19 "2019-12-09T13:04:15Z")
Wow, a lot of ideas here! 😃 Glossary sounds great, but as you already say, the first shot will be huge to write. (meanwhile, [Good practice](https://doc.babylonjs.com/how_to/contribute_to_documentation#good-practices) first version is online) ---
**Author:** ![Deltakosh](https://sea2.discourse-cdn.com/flex024/user_avatar/forum.babylonjs.com/deltakosh/32/26635_2.png) [@Deltakosh](https://forum.babylonjs.com/u/Deltakosh)\ **Post date:** [December 9, 2019, 4:03pm UTC](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416/20 "2019-12-09T16:03:43Z")
> [@Wingnut](#): > > Click-on or hover-over I prefer the click on version (or both) just for accessibility sake [Next page](https://forum.babylonjs.com/t/good-practices-when-contributing-to-the-documentation/7416.md?page=2)