Documentation reorganization ideas (fwiw only)

Feature requests
1

I recently added to docs and it wasn’t clear where some information should go. Due to the ever evolving development landscape, some of the doc sections seem to now contain redundant information. That got me thinking about a possible future doc reorganization. These thoughts are simply FWIW.

I’ve been wondering if would make sense to refactor and update the npmSupport and treeShaking sections. Perhaps reorganized something like this:

  • Developing with Babylon.js
    • History - reasons/decisions for supporting multiple NPM packaging strategies
    • CDN
    • NPM(UMD)
    • NPM(ES6) - incl. notes on tree shaking
    • TypeScript
    • Using the Playground
    • Project Setup
      • Webpack Example(s)
      • Vite Example(s)
    • IDE Setup
      • VSCode

The current Develop With Babylon.js section contains a lot of information. Perhaps it could be separated in to:

  • Developing with Babylon.js
  • Contributing to Babylon.js
  • Deprecated - menu holder for doc items like “Workloads”?

Perhaps “Developing with Babylon.js” could be made a top level menu item (instead of being under “Diving Deeper”. i.e.

  • Development
    • Developing with Babylon.js
    • Building Babylon.js
    • Contributing to Babylon.js

Possible other more minor changes:

  • “Forum Help” moved to top level or under “Tools and Resources”.
  • “Create a material for the Material Library” moved under “Materials” or under “Contributing to Babylon.js”
  • etc
4 Likes
2

cc @JohnK / @PirateJC

1 Like
3

I like these suggestions! :smiley:

4

@kaliatech The ideas are much in line with discussions we are having about some reoganisation of the docs. Your ideas are useful, thank you.

2 Likes
5

Just a start to a draft, haven’t done much with develop with Babylon.js yet.

6

cool. Perhaps you already know this and it is expected, but afaict, there is no public view of this draft work yet. The link on your forked github repo points to https://documentation-six.vercel.app/, but that doesn’t seem to contain the latest work.

I had a local env for the docs so I pulled down your repo to take a look. For anyone else that is curious, this is some of the current WIP menu structure:

babylonjsguid-wip-20220228
babylonjsguid-wip-20220228432×1343 38.4 KB

I am not familiar with the Babylon project/team structure, so I am reluctant to add more opinions of my own. There are likely already more than enough. :slight_smile: I will say this seems like a great start. Good documentation is so important for projects like this. It takes a lot of work and is sometimes underappreciated. It’s great to see continued work on it for Babylon.