What are your thoughts on the current UNITY documentation?

I am basically neutral on the current state of the UNITY3D documentation. However, i have heard from people that like it and also from those that dislike it. What are your thoughts/feelings on the documentation as it currently stands? I am just curious. Thank you...
P777

 

Its there...

 

Could be better, lots of stuff is outdated and some source code doesn't even compile!

In fact, could be a lot better.

 

Darude - Sandstorm

 

I think it's great, easy to find what you're looking for and lots of examples. If you compare to other engines I'd say it is by far the best documentation.

I haven't run into things that don't compile.

 

I think it's very good, there are times some usage examples are missing, and I remember once in a blue moon there might be something that doesn't actually work, but in those rare cases google is your friend

 

Has somebody actually clicked at the "Suggest a Change" link for one of the pages? I'm too shy ...

 

Well the documentation itself seems to be solid sure, however, from experience of others & myself, I think its a case of HOW to use it. When I began my earily programming, I was dirrected there so many times, problem is I didnt know how to use it, I just looked at it like "wuhhhh?". I was outside my comfort zone and wasnt willing to TRY anything. I think thats the problem with new players. They dont know HOW to use the documentation & lack confidence to try.

This is from experience 100%

 

Nice to have it , but there are a lot of not so nice pages in the documentation
For example what does this documentation pages say me ? Nothing at all
http://docs.unity3d.com/ScriptReference/ThreadSafeAttribute.html

Need Examples for the Editor in C#, often there is only js.
http://docs.unity3d.com/ScriptReference/GenericMenu.html

Jea is should use the "Suggest a Change" link more often.

 

Yup, lots of missing stuff in the documentation, especially for UnityEditor where many classes have undocumented APIs, but I think/hope they're trying to change that.
Also, as I suggested here, Unity should really implement XML comments along their DLLs, so that IntelliSense can do its job.

 

It's gotten me excited at times and frustrated at other. It's an alternative to what's out there; I still haven't checked out the videos yet.

 

Hmm, i thought the api pages all have a "suggest a change" link now. But it seems that just a few ones really have this link. So the first step would be to add this suggest link to every page i would say.

 

Do you mean the Manual or the Scripting API?

I don't think I've ever used the manual, and the Scripting API should be a wiki. It would let us add better examples.

They should also have a Code Snippet section (like https://gist.github.com/) that we could link to from the scripting wiki.

The regular old wiki (http://wiki.unity3d.com) is too much of a random dumping ground.

 

@Tiles, yes we did have a "Suggest a change" link on our pages back in August, which has given us a lot of valuable feedback, which we will use to improve the documentation going forward. Especially there was a lot (~30%) reports on UnityScript samples which wouldn't convert to C#. As announced on http://blogs.unity3d.com/2014/09/03/documentation-unity-scripting-languages-and-you/ we're shifting to C# as the main language also for documentation, so we will address these "broken samples" in the 5.0 docs.

Since we started getting a significant number of duplicate reports, we decided to take the "Suggest a change" feature down again, but we see it as a good way to get your feedback, and we will most likely have that feature available again at a later point.

Best regards,
Rasmus, Unity Technologies

 

That's nice to know. Thanks

 

Im pretty irritated with it right now actually. They removed the list of input manager name keys from the docs/man/input
so I can't get joystick up and running for lack of a right name for joystick x/y +/-

 

Maybe this is useful - http://wiki.unity3d.com/index.php?title=Xbox360Controller

 

Huh? http://docs.unity3d.com/Manual/ConventionalGameInput.html Same as always; hasn't changed.

--Eric

 

maybe I am thinking of the wrong doc or the wrong site, but it looked alot like this,
http://docs.unity3d.com/ScriptReference/KeyCode.html

except that it had the Axis names, Something Like JoyStick0 Axis0 (-).

Hmm...best look some more.
and some more...

Putting that aside, are we discussing the new look? Or are we discussing the functional aspect of the API reference material for unity?

Overall it's pretty good. Taxonomy is pretty fair. Multi Code examples are usually good enough.
links to related topics would be nice.

i.e.
== You have this.
== would be nice
Some API refs will say something like
RigidBody.Velocity
BLAh blah blah

SEE RELATED : RigidBody.relativeVelocity; (measures the speed between two objects)
RigidyBody.velocity.Magnitude (etc)

Example One : Getting an objects velocity
Example Two : Setting an objects velocity


Your help system, docs as they were are great for the most part. Very up front and obvious. It would be nice to have the deeper just a click away.

Like here

http://docs.unity3d.com/ScriptReference/Component.GetComponent.html

If it could also reference getcomp in kids and parents , that would be so nice.


As for the new look. I will never ever ever be a fan of anything pastel, but then again, I am not your entire audience. I think the bling effect will appeal to many people.

 

P.S. It's important to remember that Unity has an API nearly the size of Java. It's huge, and even if one is familiar with programming, it can be a task. The documentation *should* be the first line for introduction (although in reality the community is.) Organizing that into a format that makes learning Unity super simple is no easy task for you guys, and you've come along way on that since whichever version had the flying dog included with it. So don't think I'm being a butt-hat or anything. Frustration is frustrating.

 

Actually I like Unity's documentation. This doesn't mean that it's perfect or should remain like that forever but for my needs so far I like it.

Navigation has improved on the last iteration and is now more organized and structured.
The wording is mostly easy to understand even for beginners.

On the scripting API I can't say too much as I am only using very basic commands and features from there.
So far it felt adequate to me. If there are missing references or documentation they should of course be added and actually available, already. Undocumented features are bad and need to be remedied.

I wouldn't want a Wiki, though. Wiki documentation never feels really solid or clear to me. Layout and navigation on pure wikis often is a mess if you don't know what to look for or if you're just browsing.

Still: All in all I like Unity's documentation very much. If it keeps improving further - adding the missing stuff - updating the old and irrelevant things then I know that I will certainly like it for years to come.

 

The current evolution of navigation reminds me of the MSDN disks that came with VB and Foxpro back in the day.
There is also the distinct possibility that I have been hunting for answers in other forms of documentation for so long that the structure of the help system is just really foreign to me.

As for the "loose meat" wiki structure, I will never understand how that managed to gain foothold, anymore than I will understand how formats like the classic linux forum style of "documentation" has taken off. I think when it comes to things like that the methods and specifics are based on having little or no regulation or work put into them,

BTW, what CMS is this site using, I like the post editor alot...Wouldn't mind adding it to my CMS...

 

The Unity forums use XenForo.

--Eric

 

The navigation of the scripting API feels good to me, however, I find some pages completely lacking information as others have already pointed out.

Especially when it comes to writing editor code, it's unclear to me whenever I have to use some functions and when I shouldn't. Just as an example, there is an EditorUtility.SetDirty function somewhere, but it is still a bit vague when to and when not to use this function. Does this also include writing propertydrawers? Or do they handle this stuff automatically? The page mentiones prefabs, but this doesn't count for gameObjects that are in the scene? Questions like these never get answered in the docs.

Another example, I have no clue on how to use propertyDrawers for use in EditorWindows. How does one go about that?

 

Navigation is good, the rest is subpair. The documentation lacks depth and some things are completely undocumented. I hope Unity developers will improve it over time.

 

I think it is lacking on two things:

-Be specific on what is doing what exactly. 2 examples: Atomic for mecanim. So transitions can be interrupted. Does that means the transition is skipped and we instantly jump on the next transition? Or that the transition is just cancelled and we go back on the previous state? And what happen to my trigger if it is checked and in a transition. Many questions... Other example: Animator culling mode. Does it imply the state machine is still working in the background? It can be more specific.

-Need examples.. Not every pages includes examples of utilisation. When you should use that function or option is not obvious if you're not used to those things.

 

I don't see how that will improve things, that just feels like the load is being pawned off somehow... it should be a large part of your product development/deployment process to ensure each Class has thorough documentation along with references, example"s" (emphasis), and guides. IMO, wiki's and the like are more of the realm of "community" additions to expound upon the basis of what already exists. Unfortunately, that doesn't happen when you run into the following example:

I've run into many instances of this style of documentation with Unity:
http://docs.unity3d.com/ScriptReference/EditorMaterialUtility.html

When all of it should really look more like this:
https://msdn.microsoft.com/en-us/library/system.collections.ienumerable(v=vs.110).aspx

While the "manual" is a good direction and I really enjoy the "in-depth" blogs by your leads, I still feel as though the API is lacking.

I can understand that perhaps the documentation group (if there is one) may be in the process of working on Unity 5 material and what Unity has today is better than it has been in the past, but I just certainly hope that it is greatly improved for U5 release. There's still an amount of work left to do on 4.x, but after U5 I'm afraid WYSIWYG for 4.x documentation.

In all honesty, I kinda' expect that too.. it's just the natural order of things. It will just be really frustrating if upon U5 release, the documentation state is on the same degree that 4x was...

The idea is too reduce the amount of digging and discovery I have to do to use your product (API) to create the things I want and to expand the editor in ways that I need them too. Especially the latter of that, people could rejoice with this capability of the Unity editor... and a reduction of the ramp-up time to do this can only happen with fully documented and exemplified materials.

 

When I read following sentences, it took me 10 minutes to realize what it really means

If replacementTag is not empty, then for each object that would be rendered:

• The real object’s shader is queried for the tag value.
• If it does not have that tag, object is not rendered.

Let me guess what the code snippet probably looks like:
const char* pcTagValue = SomeDirctionary.Find(pcTagName);
if(invalid == pcTagValue)
return SomeInvalidTagValue;


I think it is plain translation from the code but not the logical flow. I really need to change my mindset to follow the document.

 

My thoughts on documentation are they're frustratingly minimal for the more technical tasks, but verbose for the simpler tasks, and it's not just an impression. I would have thought that in general, the docs need an advanced rollout which reveals lots of techie info that would otherwise clutter things for newbies, but deeply satisfy the programmers digging deeper.

I want to see notes from the developers. I want to understand much more about the inner workings of Unity to best work with Unity and get the most from it. As I understand it, even Unity staff have to say things like "I'd have to check the source..." and truly great documentation (which can set you apart from your peers) would cover this.

Unity's docs are often better than documentation from peers, but could be so much more. I understand the risks involved with presenting information about what happens under the hood - ie things can get out of date - but that is a good use case for pulling out a comment from the source code when building docs - perhaps via a tag. So we have an advanced rollout with these comments pulled from source, which of course tend to be up to date since any changes by programmers would certainly have to fix the tech doc comment.

 

Can we please just open source the documentation so anyone can make edits.

 

Found an error in Docs:

http://docs.unity3d.com/Manual/shader-TransParallaxDiffuse.html

Uses screenshot from ParallaxSpecular. You can't cheat gamer who licked every wall in every Crysis!

 

Hello,

I really wish the docs were open source and that they had ability to add comments. Apart from that I wish there were more examples from the community to add more depth.