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.
- example: You can set the
Links
- use lowercases on your url
- example:
/how_to/
in place of/How_To/
- example:
- 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)
- example:
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)