Why is Unity documentation so bad?

I think Unity wins the 'worst documentation ever' prize. I hereby yank it from old Microsoft MSDN documentation, and award it to Unity.

There needs to be instructions such as 'where is this found in the UI', 'what package it is in', 'what the namespace is', 'what the object hierarchy is.' In addition to information about each setting itself.

Here's an example of piss-poor documentation: http://docs.unity3d.com/Manual/class-Transition.html .

All the documentation says, is 'The following properties can be used to adjust the transition and how it blends between the current and next state (the two states connected by the transition).'

Has Exit Time
Settings
 Exit Time
 Transition Duration
 Transition Offset
 Interrupt Source
  None
  Current State
  Next State
  Current State then Next State
  Next State then Current State
 Ordered Interruption ​

There's no description of what ANY of those mean - 'Has Exit Time', 'Exit Time', any of it.

FYI, per Mixamo, here's what 'Exit Time' and 'Has Exit Time' means:

Exit Time (Unity 4) The exit time is a percentage of the animation that you want to complete before automatically transitioning to the next animation. For example, you can transition to Animation A, tell the animation to complete 90% (0.90 exit time) and then automatically transition to Animation B.

Has Exit Time (Unity 5) In Unity 5, Mecanim is a little different. Instead of using Exit time as a parameter it has instead "Has Exit Time". If "Has Exit Time" is true AND no parameter based conditionals are set, then the animation will transition after exit time. If "Has Exit Time" is true and parameter based conditionals are set, Mecanim will wait for the conditionals to become true, then continue playing until the exit time is complete, and then transition. If you want to have your animation transition instantly leave "Has Exit Time" to false and use a parameter based conditional.​

Now that's an example of proper documentation. The time wasn't in seconds, or milliseconds, or frames, like you may have guessed - it's percentage of animation you want to complete.

And I've found the documentation lacking, for most of the stuff I've tried to look up.

The more I use Unity, the more in awe I am. It's a great product. The documentation is REALLY letting it down, and hurting newcomers to the engine.

 

I think not.

The example you showed indeed is a part where documentation is severly lacking - also because mecanim doesn't even have the blue helper icon (with a link to the documentation) in the inspector settings the other features all seem to have.

Though, I don't think it's productive to immediately jump to hyperboles. You actually took the time to propose a better solution (and actually a very valid and good one, I think). Why don't you just use the bug reporter and submit that in a civil manner to the Unity team?

 

Thank you for awarding us this coveted prize With regards to the page : http://docs.unity3d.com/Manual/class-Transition.html, we do seem to have a specific bug that is skipping content that should actually be there, and we are going to address that.

 

Overall the documentation is quite good, but there are some things that need some love in there.

Worst ever? No, thats a temper tantrum talking.

 

Because as a newcomer, I've found most things I've tried to look up in the manual, aren't there, or are poorly documented.

I could find more examples of lacking documentation - look at 'Fog'. But this problem in the documentation is so pervasive, a blanket statement is in order.

 

Thats like saying all newcomers are silly bears.

You silly bear, you.

 

I'm used to companies totally ignoring everything I say, and not responding to my complaints or requests for help, despite paying for the product. Or acknowledging or responding to bug reports, or following up on them. Are you saying Unity is different?

Huh. Well, if there's real people working behind the scenes to fix things, and they actually read the forums, then I guess I could be more polite.

I hereby retract the opening flamethrower paragraph of my first post, but I stand by the rest.

 

I think that was pretty clearly demonstrated by aleks_unity (note the "Unity Technologies" badge), and now duck (ditto). So, yes. And yeah, not even remotely "worst ever" or even in the top 100 worst, though there's clearly room for improvement.

--Eric

 

Not only that, the spaceship shooter tutorial doesn't even work. The scripts it provides or tells you to use do not work, you have to google it to find out how to make them work in Unity 5. If your going to depreciate things, update your assets that you give to beginners or put a text bubble on your youtube tutorial video.

 

Thank you for the info. I will post discrete examples of missing documentation in the future, and strive to be more polite.

 

I see that the Animation Transition settings have been updated, thanks. You said it was a bug in the auto-generated documentation - how many other areas of the documentation were updated, after fixing this bug? Did your documentation file size balloon after fixing it?

Has the offline documentation been fixed as well? Just wondering if I should redownload it. (I like to access documentation even when Comcast craps out.)

And to everyone who browbeat me for complaining about it - you're welcome, if I hadn't, it wouldn't have gotten fixed.

 

That's not what the objections were...it was the unwarranted use of hyperbole. Pointing out errors and shortcomings in the docs is fine, just keep things realistic and professional please.

--Eric

 

I think the docs are really good with a few minor nit picks. My only major gripe is that the example code is not displayed in both C# and JavaScript. As I mentioned in my thread, I know just enough about JavaScript to tell it apart from C++, and I'm just learning C#. So you can imagine my frustration in trying to translate from a language I am vaguely aware of to a language that I just started learning...

http://forum.unity3d.com/threads/lost-in-translation.343699/

 

Just a note, please don't confuse C++ and C#. We do not support C++ scripting in Unity, only C# and UnityScript (also known as JavaScript, because of it's JavaScript-like syntax).

 

Yeah, from my limited experience with both languages, I believe C++ and C# are vastly different and C# has more in common with Visual Basic than C++, and considering that VB is my "native programming language", it's probably why I find it easy to understand.

 

I wanna say that sometimes it's really difficult to find any info about some features. As I wrote here I spent whole day trying to understand what and how "feet Ik", "feet spacing" and "stabilizeFeet()" do. And I still don't know. Though maybe just because I'm stupid.

Do you really think it is good explanation? No any word about how to setup transition iterruption priority? I guess just by changing their order via dragging in state transitions list?.. But I prefer to KNOW instead of GUESS.

 

Although there are definitely worse offenders, I can see where the OP is coming from. The documentation is hit or miss. Some of it is fine, while some of it is horrendously bad. It's definitely not award winning in any regard.

When it comes to new releases too, like when UNET was first released, it can enter the realm of "one of the worst" like the OP suggests. THat's hit or miss too though, as the manual explaining Multi-Scene Editing (another new feature) seems fine.

If the documentation were something that Unity employees updated in their spare time as they could or wanted, it would be pretty fantastic of a job. I'd think they deserve a good award. However, that's not the case. I am baffled that a company which has multiple full time employees dedicated to documentation would have such awful documentation. Unless those employees are not full time or are not devoted exclusively to documentation. Then it isn't so bad. (If there are 3 employees who work on the docs, what do they do all day? I am legitimately curious. That's a lot of manpower over the years ignoring missing content, erroneous examples, or unfinished parts. Especially when some fixes only come when we report them.)

If there are no employees dedicated to the docs, I'd ask "Why is Unity documentation so good?"

If there are 3 full time employees dedicated to the docs, I'd ask "Why is Unity documentation so bad?" or at the very least "Why is Unity documentation only 'okay'?"

I ask legitimately curious. I know many of us aren't Unity employees or documentation writers. The answer could be as simple as "When everything at Unity is taken into account and we finish our other tasks, we only have an hour a day to work on the docs!" or "There is more to documentation writing than what you see on the website." Although honestly I just don't understand unless it's the former. I write a lot, and I understand it's all a lot of work and times a lot of time. However if I had 8 hours a day? I can't imagine what could be accomplished, let alone with multiple writers What takes up the majority of your time? Out of curiosity.

 

Oh okay, that makes sense that it was just 1 person for most of the time. That's a lot of work for one person. Thanks for the answers!

It's important to us too. We definitely notice, or at least I did. I definitely thought that this latest update was the best by a large margin, docs included. I was pleasantly surprised by 5.3, which is saying something since I am rarely ever impressed

So well done! Well done.

 

Alright Unity, this time I'm gonna be on your side (first). (And yes I realize the discussion evolved, 3 employees, politeness, but some of this hasn't been fully addressed yet).

First, Unity caters Excessively to newcomers. Like you said, you don't know what namespace you're in, because somehow they didn't organize their docs the way everybody else would, but in the meantime, they just created a massive video series on how to do everything you'd need to create a specific type of game (rocket/2d rogue/platformer) because enough people whined (I'm guessing) about "How do I specifically make X" whereas an engineer just grabs their tools and uses their noggin.

Not only that, Unity Tech managed to put SPECIFIC examples of code usage in nearly every class. That is amazing, we wished for years for that in DarkBasic (not that I use that language now, but it was great for the pre-tablet time).

That said, no, you don't know what hierarchy you are in (like apple's docs), or namespace. Unless perhaps, a user gets fed up with searching by alphabet and wants categories, like... me... in the past... where I posted everything by subject AND in hierarchy. So Kamilche, hunt my name or do a search for "hierarchical" or "hierarchical order". I didn't update for the latest, but it's close...

I wanted to remove superclass functions in every class, 'cause... why do I need GetComponent referenced on sprite? But that took way more effort to reward ratio.

Small admittance, what I did got me hired at Popcap. I now have near direct access to the unity team besides being "that annoying guy that also acts like gut bacteria and benefits everyone by being here", so my little pushes on the community are nearly invisible but when I post something it's because I'm really needing or wanting to use it, like the Build Clean button.

I don't have time to do what I wanted with the reorganization, but I'm happy to hear your team's upping the ability. Also, I know how hard it is to document code. Your newcomers won't even know the engine (internals) anyway, and have to become experts AND write it down, it's not easy for anybody. But, we gotta be a squeaky wheel, just 'cause what Kam said for some of it, and to hope engineers and newcomers get equal treatment, or maybe you can hire udemy instructors so you don't have to waste time making a "how to make water" demo, just ensure we have the math functions ready. Not that I know quaternions at all, just giving example.

And yes, I realize I should've capitalized on my time investment (In time, maybe) Thanks for making an awesome product.