Why is Unity documentation so bad?

Web Resources
1

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: Unity - Manual: Animation transitions .

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.

5 Likes
2

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?

1 Like
3

Thank you for awarding us this coveted prize :slight_smile: With regards to the page : Unity - Manual: Animation transitions, we do seem to have a specific bug that is skipping content that should actually be there, and we are going to address that.

1 Like
4

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.

1 Like
5

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.

2 Likes
6

Thats like saying all newcomers are silly bears.

You silly bear, you.

4 Likes
7

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.

8

Hi Kamilche_ I’m another of the people working on the docs. The missing property descriptions that you pointed out are indeed due to a table syntax bug in our code which builds the final HTML doc pages, which accidentally caused the second column to be omitted. In case you needed the descriptions for those right now, here they are copied straight from our source:

Has Exit Time: Determines whether the transition’s condition can take effect at any time, or only during the state’s exit time.
Settings: Foldout containing detailed transition settings:

  • Exit Time: If “Has Exit Time” is enabled, this value represents the time after which the condition can take effect. This is represented in normalised time, so for example an exit time of 0.75 would mean that the transition can take effect only whene when the playback of the current state is more than 75% complete, and the transition’s conditions are met.
  • Transition Duration: The duration of the transition, in normalised time (relative to the current state’s duration). This is visualised in the transition graph as the portion between the two blue markers.
  • Transition Offset: The offset of the time to begin playing in the destination state which is transitioned to. For example, a value of 0.5 would mean the target state will begin playing at 50% of the way through its own timeline.
  • Interrupt Source: Allows you to control the circumstances under which this transition may be interrupted.
    • None: The transition will not be interruptible.
    • Current State: The transition can be interrupted by other transitions within the current state, but not within the destination state.
    • Next State: The transition can be interrupted by transitions defined in target (next) state, but not within the current state.
    • Current State then Next State: The transition can be interrupted by transitions on either the current or the next. However, if a transition becomes true in both current and next at the same time, the current state will take priority.
    • Next State then Current State: The transition can be interrupted by transitions on either the current or the next. However, if a transition becomes true in both current and next at the same time, the next state will take priority.
  • Ordered Interruption: Determines whether the current transition can be interrupted by other transitions independently of their order.

This bug affects a few other pages too, and we’ll update the online docs soon with the fixed versions.

4 Likes
9

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

–Eric

10

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.

1 Like
11

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

2 Likes
12

That’s why the threads at the top of this page:

http://forum.unity3d.com/forums/teaching.23/

are provided.

13

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. :stuck_out_tongue:

14

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

3 Likes
15

There were somewhere around a dozen pages that suffered from this formatting problem. Given that there are around a thousand manual pages (not including the script reference pages), it wasn’t a significant ballooning in size ;).

No, the offline documentation is only updated when a new build of the editor itself is released. It’s much better to rely on the online docs primarily (as it sounds like you do) as we’re able to update them way faster than the offline docs.

2 Likes
16

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…

1 Like
17

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).

18

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.

19

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.

1 Like
20

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 :eyes: What takes up the majority of your time? Out of curiosity.

2 Likes