SceneManager docs need help (soon) + dump of collected docs issues

I've been collecting docs issues / omissions / ideas over the last two weeks. Here it goes:

Website usability improvement needed: Please have the docs go to the page you are currently viewing when you click the "Switch to X version" link; right now it brings you back to the docs home, and you have to search again for the same page you were on!

Docs issues or omissions I encountered:

SceneManager and Multi-scene editing
SceneManager and Multi-scene editing really need help right now the most. I just tried to figure out some basic scripting of it, and swerved off a cliff, finding a bunch of other cars at the bottom. We're starting a post-apocalyptic-style tailgate party, as the pages of docs pages float idly down from above. Just kidding. I like making analogies.

https://docs.unity3d.com/540/Documentation/Manual/MultiSceneEditing.html

• Has no general code examples about how to load scenes
• Has no explanation of how to do the following under tips and tricks. Some explanation of switching from singleton managers, and how to make a manager scene persistent?: "It is recommended to avoid using DontDestroyOnLoad to persist manager GameObjects that you want to survive across scene loads. Instead, create a manager scene..."
• Upon getting this error in the Unity console, I found no explanation about how to do this "OnLevelWasLoaded was found on MessengerHelper. This message has been deprecated and will be removed in a later version of Unity." - Transition info could be placed on this page, or a different one?
• Use cases for ways to use multiple scenes? Layers like in screenshot? Different levels w/ a manager? Async dynamic loading as you progress?
• Needs more explanation of references between scenes. Editor vs runtime.
• Could use a tutorial video too (or a longer written tutorial in the Learn section)...

http://docs.unity3d.com/540/Documen...neManagement.SceneManager.GetActiveScene.html

• What is considered the "active scene" when multiple scenes can be loaded at the same time?
• And also what does it mean to make a scene active here: https://docs.unity3d.com/ScriptReference/SceneManagement.SceneManager.SetActiveScene.html
• Problems with loading a scene and setting it active immediately. Never addressed? Or needs docs on how to do properly: http://forum.unity3d.com/threads/scenemanager-loadscene-additive-and-set-active.380826/
• How does one get a list of all loaded scenes? Where is the "SceneManager's list of added scenes" and are these ones loaded, or ones in build settings? How does one get the last scene that was loaded (additively or otherwise)?

https://docs.unity3d.com/ScriptReference/SceneManagement.SceneManager-sceneLoaded.html

• No example on how to use. Same for other 2 events in the docs. Not just me - I've also seen some unanswered forum threads from the last few months about this. Also, one can't get a reference to the scene that was loaded?

https://docs.unity3d.com/ScriptReference/SceneManagement.SceneManager.GetSceneAt.html

• Does this return null if no scene found? What happens if parameter is not "greater than or equal to 0 and less than SceneManager.sceneCount"? Will this error or produce a warning?

More Stuff:

https://docs.unity3d.com/ScriptReference/Object.FindObjectsOfType.html
And other "Find..." functions

• Does not mention that objects are not returned in a particular order (what order are they returned in?). User may be expecting objects to be returned in the order that they are in the hierarchy (which would be a nice option; I had to write an extension method).

https://docs.unity3d.com/ScriptReference/StateMachineBehaviour.OnStateExit.html
https://docs.unity3d.com/ScriptReference/StateMachineBehaviour.OnStateEnter.html

• Lacking explanation. Exit is after transitions are complete? And no code example.

https://docs.unity3d.com/540/Documentation/ScriptReference/Animator.SetFloat.html

• Lacking. No explanation of damptime (already reported?), and linked page is also lacking and w/o example.

https://docs.unity3d.com/Manual/StateMachineTransitions.html

• No explanation of where an Exit Node goes or how to use them properly. Exit to where? Perhaps these special nodes need their own documentation.
• Should link to the sub-state machine doc page which continues explanation of transitions involving them?
• Transitions reference should have a section or be linked? Seems like it should belong here; at first I could not find it

https://docs.unity3d.com/Manual/NestedStateMachines.html

• Needs more explanation on how to use/transition (transition between different sub-state machines), and why transitions are not previewable.

http://docs.unity3d.com/ScriptReference/Transform.GetSiblingIndex.html

• No explanation, no example. Not clear by name that SiblingIndex is the order of objects in the scene hierarchy. Example could be finding objects in scene and ordering by hierarchy.

Missing training/docs

• Need a manual page about Unity best practices for your project's folder structure + organizing your game's folders and assets. Preferably with examples from real games. There are only a couple blog posts out there on 3rd party blogs, and they don't give the whole picture. Needed for beginners or for people starting a project & wanting to keep it organized properly.

General idea for deprecated functions ("upgrade guides"): For functions that are deprecating or being given warnings in the editor, can we get the explanation of how to replace said function or fix said warning in the documentation? Rather than having to search Google for the solution buried somewhere in a forum thread, when the text of the warning/error itself is not enough.

Holy wall of text.

"You want another one? Just say the word, say it"

 

+1

SceneManager-sceneLoaded
in particular needs an example because it requires 2 parameters (which isn't mentioned in the documentation).

 

Is this still not working in the 2017 cycle??