[Babylon.js] Open-sourcing the documentation

While working on Babylon.js 2.2, I have to admit that the framework is becoming a really important piece of software with a big number of APIs.

With David Rousset, our first priority when designing the API is to keep things simple. A good framework has to be easy to understand and extremely easy to use.

In the same way I consider that a big part of the quality of a framework comes from the documentation itself. That’s why we spend a lot of time writing tutorials and articles for https://doc.babylonjs.com

However and mostly for an open source project, keeping the documentation up to date and accessible enough is a real challenge.

I often refrain myself from writing a new feature while the previous ones are not well documented (And I can assure you that this is tough).

The first quality of Babylon.js is not the code or the easiness of the API but its community. These folks are doing a tremendous work helping developers on the forum (https://www.html5gamedevs.com/forum/16-babylonjs/) or providing samples on the playground (https://www.babylonjs.com/playground).

So we decide to rewrite our documentation site in order to let the community works on the documentation as well.

Why reinventing the wheel?

The first version of the documentation site we did was an autonomous site where we had to handle users rights, validation, history and so on. it was a failure because we were not able to dedicate enough time to make it great.

In the other hand we have Github, a fantastic site with integrated users management and all the great tools that we need to handle contributions.

So we decided to open source our documentation through Github. The basic idea was simple: People will be able to submit pull requests for .md files that will then be processed to generate html files used by the documentation site. Then thanks to Github, we (as administrators) can merge, comments, accept or reject changes.

Why markdown files?

We chose markdown files because the syntax language is extremely simple allowing you to focus not on the style but on the content. This is the job of the documentation site to present your content. You do not have to worry about visual styles when writing a sample or a tutorial. API documentation look should be very clean because readability is the most important aspect of the look-and-feel.

Furthermore due to its simplicity, markdown files can be easily processed to generate HTML files.

Node.js, grunt and Azure

The documentation is hosted on a node.js thanks to Express. Nothing really fancy here. And this is what I like. Node.js works on all operating system so developers can easily host the documentation on their computer while working on updates.

Because we wanted to work with .md files, we decided to rely on Grunt to provide a clean integration process:

• After forking and cloning the repository, developers just have to run “grunt serve”
• This will automatically launch a webserver and a watcher
• The watcher will take care of recompiling everything when you update a .md file
• So from the point of view of the user, you update a .md file and then you can go to your browser, navigate to https://localhost:3000 to immediately see the result
• You can use Visual Studio Code or SublimeText to edit .md files but you can also edit them online directly on GitHub site.
• When you’re done, simply submit a pull request from your fork to the main repository

 

After a pull request is validated on the repository, administrators can merge the master branch to the production branch to automatically publish to Azure. This feature is definitely huge: you can configure your Azure website to point on a specific GitHub branch and have it directly deployed:

Conclusion

As you can see, Azure integration with Github allowed us to have a complete and clean pipeline for Babylon.js community to contribute to the documentation site. Thanks to Grunt, the editing process is straight-forward and can be done on any operating system supported by node.js.

If you want to try it, please go to  https://github.com/BabylonJS/Documentation and let us know what do you think about it!