Contributing to documentation 101

[GameMonetize]

Hey all, this topic is to help you contribute to the documentation. This is where all newcomers will go and it has to be great (as far as possible )

 

Contributing - The easy way

 

To update an existing page, just head to https://github.com/BabylonJS/Documentation/tree/master/content

This folder is the root of all static content used by the site itself.

 

Then pick a page you want to update and select the edit button:

 

 

You can then use the great in-browser editor to do your update.

 

 

When done, just select "Create a new branch for this commit and start a pull request" and hit Propose file change. This will alert the admins who will be able to review or comment your changes

 

 

Going further

 

You can also go further by cloning the repo in order to work on your own copy before sending all changes that you did to the main repo.

To do so, you first have to fork it:

 

 

You will then see a new repo (a fork) on your own space. Please note the clone url just there:

 

 

Then you have to clone the fork on your disk. I'm using the great TortoiseGit to work with Git but you can use any compatible tool obviously:

- Install GIT: http://www.git-scm.com/downloads

- Install TortoiseGIT: https://code.google.com/p/tortoisegit/wiki/Download

- Install Node.js (the documentation site runs on node.js): https://nodejs.org/download/

 

Once everything installed, pick an empty folder, right-click on it and select "Git clone":

 

 

Use the saved clone url you just grabbed before and hit OK:

 

 

Your setup is now done. Congratulations

Please now open a Node.js command prompt:

 

 

You will have there exactly the same folder structure as the original repository.

To get all the tools used by the site, just execute the following command line: "npm install" (just do it once)

 

You can then start the server with "grunt serve". This will launch a local server and a bunch of tools that will "compile" the changes you'll do.

 

To change any file just head to /content and make your changes on .md files (I'm using Visual Studio Code which is a great editor that works on Mac/Unix and Windows).

 

You changes will be automatically done and visible on http://localhost:3000

 

 

Adding new content

 

Now that everything is working well, you may want to add new content. To do so, please open /data/statics.json:

 

 

This file is a catalog where you can reference new files added to the repo.

 

Sending pull request

 

Once you're done and ready to send a pull request, just right-click again in your "documentation" folder and do the following:

- Git Commit->master:

 

 

- TortoiseGit/Push (still on the right-click menu):

 

 

- Create a pull request:

 

 

Now you did your job It is then up to me (or any admins) to validate it

 

 

If you have any issue, please use this topic to ask your questions.

[JCPalmer]

documentation on documenting.  Holy recursion batman!

[JohnK]

Forked Documentation - Success

 

Aptana Studio 3 File-->Import-->Git Reposistory as New Project-->URI:"https://github.com/Cubees/Documentation.git" - Success

 

Node.js path to Documentation - Success

 

npm install - Success

 

grunt serve - Fail  "grunt" is not recognised

 

Screenshots from node.js to show successes and fails. What did I do wrong?

 

 

 

Second Question

This is a trial run. It may be a month or so before I do any actual editing by which time my fork will be behind the original. What will I need to do to synch the fork to the new original?

[Temechon]

You need to have grunt installed. In your node.js console, type this:

npm install -g grunt-cli

[JohnK]

Have done this and now get further error messages stating that I need Ruby and Sass installed.

 

[Temechon]

We are currently fixing this point Actually, the documentation style is built upon SASS (http://sass-lang.com/), whichi needs to be compiled with Ruby.

I'll post here when this bug will be solved.

 

Edit: This bug has been solved: you don't need to have ruby/sass installed on your machine.

[Wingnut]

Thanks for the docs on this, DK... and as far as the silence... I was sort-of hoping that Temechon had some words about it, as it was he who started the fire. 

 

I hope he didn't think that there would be no massive fallout and Wingy whining to pacify.  My main concern was whether (or not) the EDIT button would ever turn-on for us again... at https://github.com/BabylonJS/Documentation/blob/master/content/tutorials/01_Play_Pen/01._Creating_Basic_Scene.md  . 

 

But direct-editing kills some of the management power, and can lead to potential "issues", correct?  Team BD2 would REALLY like it best if folks used the method that DK has outlined above, I suspect. 

 

Sigh.  I was SO hoping for a super-powerful web-based application... a true BabylonDocs 2.0... more web.  Lots more web.  Friendly friendly friendly.  Instead, it went the opposite direction... and the docs are now officially harder to edit... than putting toothpaste back into the tube. heh

 

Oh, how I wish BD2 would have adopted the same "It MUST be simple" policies that were applied to the framework... for the documentation.  Yes, in one way, the docs system became much simpler... much like cave paintings are simpler than Photoshop. 

 

I dunno.  Interesting decision, that's for sure.  *scratch scratch*

[GameMonetize]

Please try it and then we could discuss There is NO direct publishing. Everything will be validated by admins before going live. We have BETTER management power now (thanks to the better comparison tool embedded with Github)

[Wingnut]

nod... thx.  Yeah, we have essentially reverted to the previous methods, as far as the tutorials are concerned.  All changes (and creates) need to be validated, like the old days.

 

Lots to learn. 

 

I guess I'll ask this: 

 

#1 - CREATE a new document at the github doc site.  Then admin uses a doc comparison and validates, if wanted.  Certain loggings/timestamps happen... etc.

 

or...

 

#2 - CREATE a new document using the home-gardening methods described above.  Same validating actions?  More?  More loggings? (pull times, etc?)  I bet so.

 

I don't even know what I'm asking.    Those who have chosen to "sync" to the repo... will somehow receive that new document for their home repo... (after being validated/ published)?  (I should just view a few git tutorials, eh?) 

 

This feels SO MUCH like Algebra... which I failed 3 years in a row!  Yay! 

[GameMonetize]

Please leave a chance to the system.

 

Once Temechon will have fixed remaining issues, please follow my tutorial and let me know what do you think AFTER trying it

[JohnK]

How about this for an idea. It does all depend whether conversations between Github and Azure are one way or two way and my knowledge of Github is limited and Azure none existent.

 

First of all I am talking about contributing 'the easy way'.

 

Let me use the term pending tray to mean to mean those edits that have been made and are awaiting approval as described in guide that leads this topic by the publishers. The publishers being those people who own the Documentation repository, the Document.

 

As before there is an edit button on the pages of the documentation site which exposes the page for editing within Azure. Once edited the page is submitted and then by some clever coding the edit is sent to the pending tray.

 

Perhaps there could be an intermittent stage where an agent could have access to the pending tray though not the Document. The agent could either have full rights to accept or reject edits or perhaps just the ability to advise the publishers to accept or reject. Though people would only be given agent's status if the publishers already trusted then enough to take their advice. (I had made the assumption that Wingnut had a similar role under the old documentation system). Of course all publishers are automatically agents.

 

With even more clever coding it could even allow the submission of new single pages of content.

 

For those people that wish to completely re-write or re-structure the Document or produce and put online their own version or even just make a simple edit using Github the new system allows them to do so.

[Wingnut]

Part of Wingy's comment moved to http://www.html5gamedevs.com/topic/2571-the-wingnut-chronicles/#entry92660  ...too gruesome for this thread. 

 

John, I agree with the clever coding ideas.  That's exactly what is needed.  Allow "the github dance" underneath, but give users some kind of layer atop that is much less scary and lots less complicated.

 

Previous role:  I never validated docs... because we didn't have an on-site document compare.  DK used an off-site compare tool.  All I ever did... is clean-up the English, fix broken links, and I made a few menus and hotlists.  Often, if I knew who the author of a document was, I would make suggestions to them... in PM's... and they could do some changes themselves, if wanted.

 

Sometimes folks add things to docs... for systems that I don't understand.  I cannot validate those docs, because the edit could contain some information that is wrong, and I wouldn't know, but DK would.  Sometimes I ask DK what he thinks about wordings and statements folks make... and he always kindly verifies and sometimes helps me with wordings and clarifications. 

 

I'm good at moron-proofing docs... finding things that would confuse a moron... because I'm very qualified in that dept.  heh

 

My curating power is/was pretty limited... due to my newbie-ness.  It's the same reason why the new system scares me.  Wingy hasn't learned enough yet. 

 

It seems to me... that version manager folk are one thing, and librarians are another.  I think they should be two different jobs.    I really don't want to BE a version control manager.  I'm pretty sure I'd suck at it. 

 

But, its not about me... it's about everyone... and I need to quit being ego-centric (self-absorbed).  Other people have issues bigger than mine... and I need to cope... somehow. 

 

That's kind of a pretty user interface on the front-end of the new BD, though, eh?  I just wish a toolbar was there... edit, create, move, rename, and Curator Control Center choices. 

[TheFrenchieCake]

Hey guys!

 

I added a section in the README of the github repo to explain how to structure your document in order to have a valid and usable table of content ;-) you can already see it in the branch "master" of the repo. To give some examples, I went through EVERY documents from the "generals", "tutorials", "exporters" and "extensions" sections, and modified them in order to have valid TOC everywhere on the current documentation.

[TheFrenchieCake]

Documentation for BabylonJS 2.2 is live :-) you can see the list of changes on the what's new page, as usual.

[TheFrenchieCake]

Hey people! New feature for the documentation has just been pushed to production :-) you now have a possibility to filter the list of classes/tags on the classes pages and in the sidebar of any class page displayed in desktop mode. 

[Dad72]

Cool, thanks TheFrenchieCake.

[Wingnut]

Hi guys!  I heard a rumor... that our docs team did a HUGE repair of stale links in our tutorials and class docs... within the last 24 hours.  I think it was over 200 files and it was done manually, as automation was not apropos.

 

Hats-off to you guys... what an amazing job!  To me, the task looked ridiculously overwhelming.  DK and the boys kicked its butt, with authority.  It is my opinion that we should give these guys some special hugs this week.  It was an ugly task... that was done beautifully. 

 

Someday I hope to attain that same GitHub and file-wrangling proficiency level.

 

Thanks again, docs team!  I dedicate this post to ALL of you guys.  LIKE THIS POST to give them a pat on the back for a job(s) well-done.

[Wingnut]

Well, this thread hasn't budged in nearly two months.  Nice.

 

Umm, lets see...  remember this... my one and only contribution to docs since... who knows how long?   https://github.com/Wingnutt/Documentation/commit/6295d0e5be865624790fd4b2729d8383c3da8025

 

This was Wingy removing 98  's from a tutorial.  At first, I didn't understand how they got there... but after seeing more   and & in quite a few other .md files (mostly tutorials), I think I'm starting to see the light.  These files were processed by someone... to "metachar" all the things in the .md files... that would cause bad formatting when the html was generated.

 

So if there WAS 6 spaces in a given line of .md, it was converted to         (3 single spaces and 3  ).  And these need to stay in the .md files because the html generator depends upon them, yes?  I made a mistake by removing them in my lone PR, didn't I?  I actually damaged the docs... on my first attempt (since they went git-gone) to improve them.

 

*sigh*  They are not standard .md docs anymore, are they?  They are actually website generation templates, it seems.

 

Am I wrong to feel discouraged about this type of "kludgery", if you'll pardon my terminology bias?

 

All in all, sorry for the screw-up.  I guess tutorial #2 will need to be metachar re-processed.

[Wingnut]

Do users KNOW not to fix the seemingly broken links in a file such as... oh...  https://github.com/BabylonJS/Documentation/blob/master/content/classes/2.2/CubeTexture.md  ?

 

Do any of us know what would happen if someone DID fix those broken links?  Would the links on the BabylonDocs website go broken after html re-gen?  hmm.

[GameMonetize]

Which broken links?

[Wingnut]

CubeTexture (5), BaseTexture (1), Scene (2), Matrix (1).  Nine 404 errors total.

 

content/ is missing from the paths of all the in-document links, as is the .md suffix.

 

For example... link url to 'Matrix' is https://github.com/BabylonJS/Documentation/blob/master/classes/2.2/Matrix

 

That doesn't work... 404

 

The working path to Matrix is...  https://github.com/BabylonJS/Documentation/blob/master/content/classes/2.2/Matrix.md

[Temechon]

Hello Wingy,

These links are supposed to be open in the documentation, and not within github. 

I think there is no broken link here : http://doc.babylonjs.com/classes/2.2/CubeTexture

[Wingnut]

Hi Temechon (and all others).  Right, I understand this.  That's why I say that the md files are no long "normal" md files, but they are templates (data models?)... little databases, specially customized to properly generate the website html.  We, as a team, try to get users to help with documentation... by asking them to edit these md files.

 

Do the users know NOT to "adjust" the links to work properly when viewing/using the md?  Has anyone told them/us?

 

Do the users know NOT to remove any  , ", &, etc... from the md files?  Has anyone told them/us?

 

https://github.com/BabylonJS/Documentation/search?p=2&q=%26nbsp%3B&utf8=%E2%9C%93

 

(Sorry for including the html files in that search.  I couldn't figure out how to ONLY search in our content folder or ONLY search the .md files)

 

How about the curators?  When TheFrenchyCake said...

 

 

TheFrenchieCake commented on Sep 8

Seems fine to me. I'll merge this, compile the whole thing and push to production in the morning ;-)

 

[ https://github.com/BabylonJS/Documentation/pull/11 ]

 

...should he/she have rejected this commit, and informed me that all those   should remain in tutorial #2 ?

 

If a helpful user DOES try to adjust the links so that they work properly when clicking them while viewing the md file, do the curators know to reject that commit?

 

Will the user be a little discouraged (or possibly just plain pissed off) when they realize that they worked for 2 hours removing metachars and adjusting links... and then the merge is rejected because they didn't know that they were NOT supposed-to adjust the links or remove the metachars?

 

And if a user DOES adjust the links so that they work in md view, and a curator commits it accidentally (sounds familiar), then those links will fail on the website after the next build, right?

 

Sorry, I'm not doing so well at explaining this.  There might not be any other/better solutions when using md's as "data models" for genning a website, but I think the users need to be told (over and over) about this, and so do the curators.

 

As an example, can MY lone waste-of-time documentation-damaging commit/merge... be reverted?  I made a mistake removing the  's, and Frenchie made a mistake in merging it, right?  Does anyone have any ideas on how to prevent such things in the future?  Do we care?  Should I care? 

 

Do periods ALWAYS get two spaces after them, no matter what the browser software/html-spec has to say on that subject?    *shrug*

 

(After further research, it seems that a single space after a period... is the modern policy.  I feel old!  Maybe I am.)  

[Wingnut]

allllllllllrighty then.  hehe.  phew.  [Wingy gives himself a gold star in spurring conversational enthusiasm] 

[Wingnut]

2.5 months of "dead" here!  Wow.  I'm SO proud of my thread-killing skills.

Hey Temechon, thanks for the good info and kindness during my 2nd ever BJS docs edit (since moving to GitHub)... earlier today.  I was a little scared, but not too bad at all, this time.  Last time, I nearly died of anxiety/worry... about screwing something up.

Would you (or anyone) feel like doing a build?  Is there only one edit in the IN-basket?  (Folks, rumor has it... that it wears-out the build-bearings if we do too many one-edit builds.  It's like washing only one item of clothing. It makes the washing machine drum wobble severely during the spin cycle.) 

It's just that...  the subject of animations and animatables... is hot right now.  I'd love to see that link in the Animations Tutorial... start working soon.  Maybe you or somebody would want to manually edit the HTML file instead of doing a build?  That would be fine, too.  I can do that myself, maybe, but... I'm not sure if direct-editing the HTML is wise policy.

Maybe Delta-K wants to slide-in a few lines about animation blending... before the build, too.

Maybe there's a "secret gulpfile" that does a one-file build?  Only processes that single .md and produces only the Animations tutorial? 

Maybe I sure ask a lot of questions?  Maybe I say 'maybe' a lot?  (thx)