Help wanted!

[GameMonetize]

Hey team!

we were clearly heads down working on 3.0. Now that we successfully shipped it I would like to get the help of our wonderful community.

I would like to improve the content of our documentation.

If you go there: https://github.com/BabylonJS/Documentation/issues you will find a list of issues related to the doc.

There are 2 kinds of issues:

• Missing documentation: These issues are used to flag a missing tutorial / documentation / overview
• Incomplete documentation: These issues flag articles / topics where we consider we should add more info

If you want to help, you can:

• Create more issues to help identify what is missing / incomplete / unclear / using bad english / whatever could be wrong
• Take one issue and fix it: My favorite one  Pick an issue, read this small tutorial and contribute to the best doc ever made for a 3d engine

One of the goal of the 3.1 will be to add helpers everywhere to make common tasks even simpler. And I'm convinced that doc will be an important part of this simplification as well.

 

Thanks a LOT

[inteja]

Happy to help, but see my post here 

 

[JohnK]

On 14/07/2017 at 7:00 PM, Deltakosh said:

I would like to improve the content of our documentation.

This is a bit cheeky as I have not tackled any of the issues given. However I have never been very happy with the organisation of the documentation, what is an overview, what is a tutorial, what is general.

So when you are not happy with something then the person to do something about it is you. So I made my summer project to do it. I am hoping that my re-organisation will meet with approval and be accepted. However whilst I knew there were some issues arising I did not expect the first one I came across.

Having done the re-organisation which can be found at this branch https://github.com/BabylonJSGuide/Documentation/tree/master170823 and successfully done a grunt build and grunt serve and have a local copy running I was then naive. I thought by publishing what was in the public/html I would have a running version in github to demonstrate the new organisation.  I get something but not a proper working copy at http://grideasy.github.io/index.html

Possibly something to do with using / for root?

So question 1 is what do I have to do to get a version that is live.

Other issues still outstanding are

2: Having moved files into different folders  I have retained copies in the original folders but hidden so that links from the forum and elsewhere should still work when root url is http://doc.babylonjs.com

 is this the best way to do this?

3. Can see in the scss folder what changes need to be made to styles so coloured numbers still work but having tried it out the changes do not go over to main.css. How do I deal with this?

4. The search database would have to be totally remade and I have no idea how to do this.

If you think it is easier to continue (or don't want to continue) DK with this via PMs or any other method please let me know.

 

[GameMonetize]

hello, and thanks a lot for your help!

 

1. just go to netlify.com, create an deploy using this config:

2. You are right, we need to make sure all links still work. The good news is that we have a redirect file here: https://github.com/BabylonJS/Documentation/blob/master/public/html/_redirects Just add any redirect you need

3. This ones if for @Temechon or @brianzinn

4. Search index will be rebuilt automatically. No worry about that

 

[JohnK]

On 8/23/2017 at 6:53 PM, Deltakosh said:

just go to netlify.com, create an deploy

Just had a fun day doing this. First of all wondering why grunt build worked locally but not on Netlify. Eventually working it out that I had a couple of folders starting with an upper case letter but referenced elsewhere as all lower case. Then spent the rest of the day working out how to get git to recognise a renaming to lower case. But got there in the end.

To check out the re-organised docs site and see what you think its at http://guide-calvin-50377.netlify.com/

Please let me know, DK,  if this would be a worthy replacement for current documentation and I will sort out any remaining issues

Issues

Still has repeats of moved files in old folders but hidden, including Canvas2D, and will look into the redirects file and remove them.

CSS issues also not yet dealt with.

Already spotted one link not correct.

EDIT Documentation updated

 

[GameMonetize]

Hello!

some feedback:

-  I think overviews is too big: we find "available textures in PG" at same level as behaviors. To me they are not of same magnitude.

- There is a <<<<<HEAD in the what's new

- Really like the 101

- "Porters" seems weird to me

- Samples is also a really good idea

[JohnK]

 

Initial reactions are just to clarify why I did what I did. Will have a long think about each of these points and see what I can come up with. Also take on board any other ideas anyone may have.

Was trying to keep number of menu items in top header to a minimum

1 hour ago, Deltakosh said:

I think overviews is too big: we find "available textures in PG" at same level as behaviors. To me they are not of same magnitude.

Difficulty in finding a good place for 'reference' material. Idea of Overviews is to give complete overview for any aspect.

1 hour ago, Deltakosh said:

There is a <<<<<HEAD in the what's new

Will sort this.

1 hour ago, Deltakosh said:

Porters" seems weird to me

Trying to keep export and import methods together and just one menu item, but it is weird and just made it up. Perhaps we could get used to it?

1 hour ago, Deltakosh said:

Samples is also a really good idea

Good.

 

 

[brianzinn]

DK, if you really meant me for #3 I'm happy to lend a hand on CSS.

[GameMonetize]

Just let us know how to compile the scss

@JohnK : for porters I would prefer something like "importers and exporters": if we have to get use to it it won't work as we want to improve the doc for easiness and readibility

Overviews was for me a place where we can present the important things (like webvr, physics, etc..) We may need a place for less important topics

[JohnK]

8 minutes ago, Deltakosh said:

for porters I would prefer something like "importers and exporters

Could be a bit long for menu heading. How do you feel about "resources" and move the reference section into this from Overviews.

We obviously have different views on the meaning of overview. 

What makes topics such as physics or webvr important and have their own area, ie what makes them different to other topics such as "Using depth-of-field and other lens effects" for example?

If I understand what places one topic in one category and another in a second category then it will help with the categories. 

Should all tutorials be "How to" as opposed to a description.

23 minutes ago, Deltakosh said:

we want to improve the doc for easiness and readibility

Agree, so need to get the right category names and a good definition of what belongs in what category. Will continue to give it some thought over the weekend.

[GameMonetize]

the Ui should not be a problem Import/Export could be short enough for instance

Agree with you: I prefer "how to". Tutorials was not a good name

 

Overviews must focus on large chunck of code. Something that can be listed on a "what can babylon.js do?" Depth Of Field for instance could be a how to while "using postprocesses" could be an overview (and we should have links between both)

[JohnK]

Understand your division. In which case the separation between exporter and loader makes sense. Loading a file is something BJS can do but an exporter is external not something BJS does. Would you accept features rather than overviews?

[GameMonetize]

Sure thing!

[brianzinn]

@JohnK I can get the scss compiling no problem on the main documentation repo.  Running 'grunt build' did not update the CSS or give any warnings.  I looked in the grunt.js file and found the sass task.  So, I ran 'grunt sass'.  It gave me this error:

Warning:
You need to have Ruby and Sass installed and in your PATH for this task to work.
More info: https://github.com/gruntjs/grunt-contrib-sass
 Use --force to continue.

Aborted due to warnings.

So, I installed ruby then ran this command:

gem install sass

Now when I run 'grunt sass' (you need a new window or to update your environment vars).

grunt sass
Running "sass:dev" (sass) task

Done, without errors.

And main.css was updated with the changes I made in the .scss So, maybe you just need to install a couple of things?  Otherwise if you have made other changes I can look at your repo?

[JohnK]

4 hours ago, brianzinn said:

look at your repo?

Certainly, however after suggestions from DK I am starting my reorganisation from scratch and it might be a couple of months before I am ready to update the scss.

repo at https://github.com/BabylonJS/Documentation/tree/master all changes in development branch.

However as I said already it is now early days. When it comes to it I will contact you again if I have problems with scss.

[Wingnut]

(Wingnut power-hugs John... just cuz John is so cool, and he seriously gives a crap about everything!)  You're just the best, JK!  Always thinking about how to improve and flatten the BJS learning curve.  You too, Brian... thx for helping/caring.

When writing docs, often I come across places where there are 5 ways to do the very same action.  In fact, let's use "label a mesh" as an example... which now, officially, there are 7 ways to do it.  Which do we teach?  One side of me says "Wingnut, pick the way that you like the best, and keep it introductory"... but that's not fair to the reader/user. 

Another side of me... then says "Wingnut, you need to show all the ways, and tell of the advantages/disadvantages of each way.  Also tell of the cool properties and methods available to each way."

The doc now grows to 17 pages long, and it scares everyone... due-to SO MUCH TEXT.    Yeah, we wrote a "comprehensive" (covers all tiny details) doc, and we are proud of it... until we visit it later and notice how scary a 17 page doc... is.  heh

You can't win.   It's an impossible situation.  Goofy.  This gets back to our "categorize by skill levels" stuff... which is also a miserable job to accomplish.  *sigh*  It makes me laugh... because it is SUCH an impenetrable concrete wall of a dilemma.  Sort-of tumor-causing. 

Still, you're the best, J!   I'm sure glad you hang around with us.  We can all compare brain tumors. 

[Wingnut]

Okay, so, I thought up another kind of doc.  "Pasties"    It's not as cutesy as "porters", but it's still pretty la-la.  (Wingnut pats John on the back for being both storyteller and teacher).

These "pasties" would be... all code examples... easily highlight-able and copy-able... for quick copy'n'pastes.  30 most-used camera activation code lines. 30 most-used light activation lines.  30 most-used make-mesh-with-material code-chunks.  Top 10 "get me animated" code chunks!  10 fast'n'easy skyboxes. 

Then again, I guess playground searcher already does that for us.    And I should be over in Tutorial Talk, and not cluttering-up DK's plead-post.