New documentation!

[Temechon]

Hey guys,

 

I’m sure you already know it, but the new documentation is now officially deployed on doc.babylonjs.com!

This version is a total rework of the version you used to know, so let me present it a little bit.

 

Our main concern was (and still is) to create a documentation the community (YOU!) can update and modify at will. This documentation makes no exceptions, with a big new change: it is now based entirely on Github (https://github.com/BabylonJS/Documentation) (and automatically deployed on Azure).

This means you can :

•           fork the repo and create your own documentation
•           create pull request to fix bugs
•           create pull request to contribute
•           Clone the repo and have a local version of this documentation
•           Everything you can think of

 

Features:

•           All tutorials, exporters and extensions are now sorted. We tried to keep the same hierarchy the old documentation had, but FEEL FREE to update it, or create a new one. (Don’t forget it’s your documentation!)
•           All classes can now be tagged (example : http://doc.babylonjs.com/classes/2.1/AbstractMesh has two tags: Node and Mesh).
•           All classes are sorted by tags, and alphabetically (http://doc.babylonjs.com/classes/2.1).

o   This allows news users to easily find common classes (Camera, Mesh, …)

•           URL are now user-friendly. You can write http://doc.babylonjs.com/classes/<className>, and it will redirect to the last version of this class (if it exists of course). Example: http://doc.babylonjs.com/classes/Axis
•           Links forwarding to the old documentation (example: http://doc.babylonjs.com/page.php?p=22551) are now forwarded to the same page on the new doc.
•           This website is responsive, and the mobile version is awesome J
•           MIT license, do what you want!

How to contribute ?

This website is an big empty shell created to DISPLAY markdown files.

Each page is represented by a markdown file. To contribute, just clone the repo, update a markdown file (or create a new one if you want to add things), and do a pull request.

It’s that easy !

 

What’s next ?

My team and I and still working on this baby, so you can expect some QoL improvements soon.

 

Stay tuned! 

 

[GameMonetize]

You forgot to mention function level linking:

 

http://babylondocv2.azurewebsites.net/classes/2.1/Scene#addcamera-newcamera-rarr-void

​

 

(I'm pretty sure that Wingy will love this one:))

[Temechon]

Indeed, I forgot it  

[Dad72]

This new doc is really cool and much more convenient. It'll help the new members, but also old members. 

[jerome]

Awesome 

[Wingnut]

So, we need to speak DOS-prompt (nodeJS/Git) to edit a tutorial?  Nice.  How truly modern. 

 

Maybe I can sneak-in thru github and use its md editor... like the good ol' days.  Maybe not.

[jerome]

I think md files are directly editable from github like they used to be in the original documentation

[Wingnut]

The silence is deafening. 

 

Ok, yay for the new BD, nice job, dev team.  Now... Temechon and Deltakosh and the BD2 dev team have had the chance to comment-on whether or not anyone will be allowed to have direct editing perms at https://github.com/BabylonJS/Documentation.  I'm going to assume that the silence means "no".

 

Assuming this, is there anyone within earshot who knows how to program something that can smooth this NodeJS/git/grunt nightmare?  It doesn't need to be a universal app for dealing with any repository of .md... just our repoz. 

 

Besides hiding all the DOS-command-like crud, one of the things I really need it to do... is tell me if a pull request is pending, or if a document validation is pending... for the document(s) that I'm about-to submit a pull-request for.  I need to know if someone has edited a document... before I did my edit, and thus I started with a stale repository clone of that document.  In other words... was an edit accepted from another... SINCE I got my cloned repository?

 

It looks to me like we need to do this FAST.  Get the clone of the doc, hurry-up and get the edit done, submit the pull request, and pray that the pull comes quick before another person's PR makes your edit stale.  If another person's PR to edit that same document... beat YOUR PR, then your edit is now stale.  You didn't start with a current clone... because another person's edit was accepted and validated before yours got pulled.  But I won't know this, as an editor.

 

I don't know how this would work.  I guess the smart thing:  Don't edit anything IF there is a PR pending from another.  ANY PR.  We probably should always wait for the other person's PR to complete... and be validated... before we clone.  We must know that the repoz is up to date... before we do the clone.  Then work fast, real fast, so we don't tie-up other people's clonings with pending changes.

 

Yep, I would love to have a curator's tool for Windows... or maybe Java so we can get the general public back "into" editing our docs.  I got SOME money to put into it... not much... but it'll be better than peeing on your foot. 

 

I think github has isolated the users from the docs.  I know it has isolated me from the docs.  I feel like I just lost a pile of my buddies.  Help me find some ways to compensate for this, friends.  All further talk about this... by me... will be done in The Wingnut Chronicles... as this is the "YAY BD2" hoopla thread, and I don't want to be a party pooper.  Feel free to make comments anywhere, of course, but, I invite you to The Wingnut Chronicles... if you want to get out of the parade route.  Thanks!

[JohnK]

My thoughts on the editing of BD2 are split but if pushed would probably go with too many hoops to jump to get involved. Why is this? For situation my level of skills it was

 

1. Easy to submit edits and content
   • Find out about markdown
   • Go to the edit page, make edits and submit;
   • Go to new content, write content and submit;
2. Hard to submit a restructure

• Write a suggested outline structure;
• Put the suggestion into the forum;
• See what happens;

and it is

      

1.  Hard to submit an edit

• Learn about forking, cloning and pull requests;
• Learn about node.js;
• Learn what grunting is and how to do it;
• Learn what files to added to and what to add for new content;

       2. Easy (having done the learning curve) to submit a new structure

• Write new structure offline;
• Push to Github;
• Send pull request.

 

To put this in context what is my situation and what are my skills?

 

I am a retired teacher and am fairly time rich and financially poor, my interest in programming is amateur and a bit plodding. My understanding of BJS is basic and growing but are sufficient for the project I am writing and am very grateful for all the help I have got from the experts on the forum. Whilst I cannot help with answering questions, many are above my head, I think I can contribute by writing detailed examples for the seemingly simple  methods for meshes.

 

I do use Github as a free host for my projects, which I very happy to have as open source, along with Apatana 3 and can push from Aptana to Github but when I need to something different I need to do the research first. For example when RaananW sent a pull request to correct an error and I accepted it I put my offline files, which were ahead of the github files, out of sync and it took me half an hour to find out how to resync them.

 

A few weeks ago I downloaded node.js, mainly to see if I could use it for saving and opening created files. However having downloaded it and following the introductory examples I got it working but put it to one side as something I might use one day but really for what I wanted it seemed too much bother to learn any more about it.

 

As for Grunt, the mention in the read-me file for BD2 is the first I have heard of it.

 

The skills I hope I have is to recognise my limitations, not to be afraid to show them and to be clear and specific when I do. So working on the understanding that editing BD2 is not going to change in the near future what I would like is:-

 

Within the documentation a how to submit section that would contain a step by step idiots guide to

 

Forking the repository (ie does this create a new repository in my github or do I need to create one first?)

How do I clone the repository onto my computer to edit offline, is node.js and grunt sufficient. (Do I need an editor like Aptana that connects to github needed, is notepad++ sufficient?)

 

Having cloned it how do I read it offline in the form that it will appear as online documentation in azure?

What is the need for node.js and grunt, having downloaded them how do I use them in editing (or displaying) the documentation or for whatever they are needed for?

 

There are in fact two areas that I am thinking of editing and submitting

 

1. Adding a link for some methods in a class that take you to a playground example of where it is used (can find out which ones are relevant using the downloaded playground files that wingnut had done.) This was easier under the old document editing system.
2. Restructuring the tutorials into what I think would be an easier structure for newbies. Not possible on old documentation, hard on BD2 until I know sufficient about github

Though both would be done only when I was having a break from the project.

 

Anyway just my thoughts for what they are worth.

[GameMonetize]

Hey guys, my silence is mostly because of ..the week end

 

So, you can easily update documentation by going to github and just use the provided .md editor (there is a pencil to launch it on every page). Everything is now hosted there:

https://github.com/BabylonJS/Documentation/tree/master/content

 

Jump into any .md​ and do the edit you want. No more no less. I find it easy, don't you?

 

 

The next level ​implies to install node and to use 3 command lines (no more) which are described here:

https://github.com/BabylonJS/Documentation/blob/master/README.md

 

Doing this you will hav​e total control over the structure of the documentation itself (which was not possible before). Furthermore, thanks to GitHub I have an already setup users system which was just painful to handle with previous version.

 

I want also to add that​ with this new system all the data are local. There is no more hidden DB as all the files are static

[GameMonetize]

If the process is unclear, we can think about adding a doc for the doc

[GameMonetize]

@WIngnutt: You can see all pending PR on GitHub and it provides a unmatched tool to handle collisions (which was not really the case with previous version!)

[GameMonetize]

I started a new topic to help you guys:

http://www.html5gamedevs.com/topic/16365-contributing-to-documentation-101/?p=92445

[Sparky]

I'm not likely to get involved in the updating of the docs, but they certainly look better! Wish the main site had a menu at the top (read: not at the bottom). I'm on a Mac at work and the dock gets in the way!