Three.js: Clarification on Docs vs Wiki (vs forum?)

[looeee]

Continuation of the discussion here which is a bit stale at this point: #5410

The docs currently have 4 sections

• Manual
  
  
  
  • This has two pages at present, a very useful "Creating a scene" page and a kind of orphaned looking page on matrix transformations
  
  
• Reference
  
  
  
  • This still needs some expansion in places, but should now be a complete API reference (as of r83). (ping me if you find mistakes, of which I'm sure there are more a few!)
  
  
• Examples
  
  
  
  • This is very incomplete
  
  
• Developer Reference
  
  
  
  • Also very incomplete
  
  

The Wiki is a bit of a mess at the moment but has

• TODO (things to be developed in Three)
• JSON reference
• link to migration guide
• code style guide
• FAQ section which largely link to github issues
• various manual type articles
• "On the Net" section with links to all kind of Three related info across the net (some broken and some out of date)

@mrdoob you mentioned here #10342 that you'd like the JSON reference to stay in the Wiki (although you also said in #5410 that everything should go in the docs :p )

I have two suggestions:

1. Everything goes in the docs. Get rid of the Wiki

1. Split like so:
2. Docs: Everything related to using Three
3. Wiki: Everything related to developing Three

Obviously there would be some crossover in 2. but in ambiguous cases the docs should be preferred.

[mrdoob]

I think I prefer 2 ✌️

[looeee]

Great, me too :)

So the first tasks would look like this:

1. Move Developer Reference pages to Wiki
2. Move manual type pages from Wiki to doc's Manual section
3. Create Useful Links page in doc's Manual section, check links in Wiki to see if they are still relevant and move them there
4. Move (or perhaps duplicate) Code Style guide to doc's Manual section
5. Move migration guide from Wiki to docs
6. Create FAQ page in doc's Manual section, move relevant questions there. Some FAQs in the wiki are related to development, they can be moved to a new page there

@mrdoob (or anyone else) thoughts?

[Fallenstedt]

@looeee I agree. The docs and wiki does seem all over the place. separating them would nice.

[looeee]

@mrdoob one thing that has occurred to me here is how useful the PR system is as review and record system for documentation (I mean, you are carefully reading over everything I submit before merging right? 😛 ).

But seriously, everyone that is actively involved in three.js will presumably get notifications for any issues or PRs made here, and will know when something has been updated. The wiki on the other hand, as far as I'm aware has no such notification system - lots of changes can be made without anyone noticing unless they think to check, and the people with the expertise to notice and correct mistakes probably won't need to check the wiki very often.

I'm still perfectly OK with the wiki / docs split, just wanted to raise this issue before implementing it.

[mrdoob]

I mean, you are carefully reading over everything I submit before merging right? 😛

Of course! 😉

I'm still perfectly OK with the wiki / docs split, just wanted to raise this issue before implementing it.

I guess we can start by moving things from wiki to docs and see what we end up with.

[looeee]

OK, sounds good! I'll leave the dev ref section as is for now.

[looeee]

I'll use this issue as a place to record changes I make to the wiki as well.

First changes:
Deleted "Getting Started"
Deleted "Using Matrices & Object3Ds in THREE"
These pages already have better counterparts in the docs

Removed Articles -> "build.py, or how to generate a compressed Three.js file" - page doesn't exist

Removed Components -> WebGLRenderer as it just links to the docs

[looeee]

Shall I delete this page? https://github.com/mrdoob/three.js/wiki/Using-three.js-in-C%23-with-SharpKit

It's not really related to three

[mrdoob]

Sounds good!

[looeee]

Deleted Articles -> Drawing lines (moved to docs)
Deleted Articles -> Text in Three.js (moved to docs)
Deleted Articles -> Testing with npm (moved to docs)

Deleted Articles -> Using three.js in C# with SharpKit (not related to three.js)

[looeee]

Will I delete this page? It doesn't say much that a user couldn't work out on their own pretty quickly and may be out of date anyway
https://github.com/mrdoob/three.js/wiki/Using-SketchUp-Models

[mrdoob]

Kind of tempting to do a page on the docs with a collection of those...

Like... Exporting from Blender, Sketchup, Maya, etc

[looeee]

Deleted Articles -> threejs-typescript-gulp-jspm-seed (Dead link)

Fixed link to three.js.org/docs and deleted second occurrence of link

Deleted Tools -> ThreeFab (hasn't been updated in 4 years)

[looeee]

Kind of tempting to do a page on the docs with a collection of those...

Yup, I agree - or rather a section with a few pages. I'm creating wishlist of manual pages that I'll link at some point that includes those.

I meant that that particular article doesn't have much useful info and can be deleted. A better version should be created in the future though.

[looeee]

Renamed Migration to Migration Guide
Renamed TODO to Developer's TODO list
Renamed Documentation to API Documentation and Manual
Renamed A Contributor's Guide to the Git Galaxy to An introduction to using Git

Created Introduction, Developer Guide and Three.js JSON format schema sections

Created Purpose of Wiki page to explain separation of Wiki and docs

Deleted page _GUI Tools with Three.js_ - it links to several tools that are very basic and haven't been updated in 4 or 5 years. I'll add an updated version to the docs later

Deleted page _performance improvement_ which had a couple of badly explained suggestions from 2012

Deleted page _Some patterns used in examples_ - info moved to pending FAQ page in manual

[looeee]

Moved page _Detecting WebGL and browser compatibility_ from Wiki to manual #10427

Moved page "How to run things locally" from wiki to manual #10428

Moved How to update things from wiki to manual #10429

[looeee]

Created a useful links page in the docs and moved nearly all of the links from the wiki there: #10433

[looeee]

Deleted FAQs:

• Which import format / exporter should I use?
  
  
  
  • linked to very old issue, an updated version should probably be created
  
  
• How to use Blender export script?
  
  
  
  • linked to very old issue
  
  
  • How to use OBJ converter script?
  
  
  • linked to comments in source code
  
  
• How to update things with WebGLRenderer?
  
  
  
  • moved to manual #10429
  
  
• How to run things locally?
  
  
  
  • moved to manual #10428
  
  
• How to use OpenGL or ANGLE rendering on Windows?
  
  
  
  • Moved to Developer guide section in Wiki
  
  
• Why do examples use requestAnimationFrame?
  
  
  
  • I intend to create a manual page on the render loop that will cover this
  
  
• Why are there meta viewport tags in examples?
  
  
  
  • Moved to pending FAQ page in manual
  
  
• How to change color of Fog?
  
  
  
  • It's in the docs...
  
  
• Are there tools to help me build a scene in Three.js?
  
  
  
  • The page was very out of date, and anyway better place for this is in the useful links section
  
  
• How Matrices work in Three.js
  
  
  
  • Linked to an old issue: #1188 and there is already a page on this in the manual
  
  
• How to preserve scene scale when resizing window?
  
  
  
  • Added info to pending FAQ page in manual
  
  
• Which default attributes / uniforms / varyings are available in custom shaders?
  
  
  
  • This just linked to code here - this info should maybe be added to the docs
  
  
• Why is part of my object invisible?
  
  
  
  • Added info to pending FAQ page in manual
  
  

[looeee]

Should this page be moved to the manual or deleted?
https://github.com/mrdoob/three.js/wiki/Features

[mrdoob]

Should this page be moved to the manual or deleted?
https://github.com/mrdoob/three.js/wiki/Features

I would delete it.

[looeee]

Done!

[looeee]

@WestLangley these are the pages moved from the Wiki to the docs. Which do you think should have stub redirects?

Getting Started (was already in manual)
Using Matrices & Object3Ds in THREE (was already in manual)
Drawing lines
Text in Three.js
Testing with npm
Detecting WebGL and browser compatibility
How to run things locally
How to update things

My suggestion would be just these:
Testing with npm
Detecting WebGL and browser compatibility
How to run things locally
How to update things

[WestLangley]

Which do you think should have stub redirects?

Only these:
_How to run things locally_
_How to update things_

[looeee]

OK, done.

[looeee]

Unless anybody spots any other issues, aside from cleaning up the moved pages the last task here is deciding what to do with the Developer Reference section in the docs.

@mrdoob thoughts?

[looeee]

I would like to finalise this issue for now - the last task is deciding whether to move the developer reference section to the wiki. @mrdoob did you have any thoughts on this?

[WestLangley]

Whatever you do would be fine with me, but please redirect long-established links.

[looeee]

@WestLangley I'm actually fine with leaving it as is, and I don't intend to add anything to the developer reference at the moment, so rather than breaking links I'll just close this issue for now.

[mrdoob]

Leaving it as it is sounds good to me 👍