Search Unity

  1. We are migrating the Unity Forums to Unity Discussions. On July 12, the Unity Forums will become read-only. On July 15, Unity Discussions will become read-only until July 18, when the new design and the migrated forum contents will go live. Read our full announcement for more information and let us know if you have any questions.

Why is Unity documentation so bad?

Discussion in 'Documentation' started by Kamilche_, Jun 24, 2015.

Thread Status:
Not open for further replies.
  1. Kamilche_

    Kamilche_

    Joined:
    Jan 11, 2015
    Posts:
    75
    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.
     
  2. the_motionblur

    the_motionblur

    Joined:
    Mar 4, 2008
    Posts:
    1,774
    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?
     
    aleks_unity likes this.
  3. aleks_unity

    aleks_unity

    Unity tech writer/programmer

    Joined:
    Jan 12, 2012
    Posts:
    25
    the_motionblur likes this.
  4. LaneFox

    LaneFox

    Joined:
    Jun 29, 2011
    Posts:
    7,647
    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.
     
    aleks_unity likes this.
  5. Kamilche_

    Kamilche_

    Joined:
    Jan 11, 2015
    Posts:
    75
    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.
     
    newmant and CarterG81 like this.
  6. LaneFox

    LaneFox

    Joined:
    Jun 29, 2011
    Posts:
    7,647
    Thats like saying all newcomers are silly bears.

    You silly bear, you.
     
  7. Kamilche_

    Kamilche_

    Joined:
    Jan 11, 2015
    Posts:
    75
    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. duck

    duck

    Unity Technologies

    Joined:
    Oct 21, 2008
    Posts:
    358
    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.
     
  9. Eric5h5

    Eric5h5

    Volunteer Moderator Moderator

    Joined:
    Jul 19, 2006
    Posts:
    32,401
    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
     
  10. ViperG

    ViperG

    Joined:
    Jun 24, 2015
    Posts:
    6
    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.
     
    newmant likes this.
  11. Kamilche_

    Kamilche_

    Joined:
    Jan 11, 2015
    Posts:
    75
    Thank you for the info. I will post discrete examples of missing documentation in the future, and strive to be more polite.
     
    LaneFox and chelnok like this.
  12. Graham-Dunnett

    Graham-Dunnett

    Administrator

    Joined:
    Jun 2, 2009
    Posts:
    4,287
    That's why the threads at the top of this page:

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

    are provided.
     
  13. Kamilche_

    Kamilche_

    Joined:
    Jan 11, 2015
    Posts:
    75
    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. :p
     
  14. Eric5h5

    Eric5h5

    Volunteer Moderator Moderator

    Joined:
    Jul 19, 2006
    Posts:
    32,401
    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
     
  15. duck

    duck

    Unity Technologies

    Joined:
    Oct 21, 2008
    Posts:
    358
    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.
     
    aleks_unity and Graham-Dunnett like this.
  16. neamerjell

    neamerjell

    Joined:
    Jul 20, 2015
    Posts:
    6
    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/
     
    Hodgson_SDAS likes this.
  17. aleks_unity

    aleks_unity

    Unity tech writer/programmer

    Joined:
    Jan 12, 2012
    Posts:
    25
    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. neamerjell

    neamerjell

    Joined:
    Jul 20, 2015
    Posts:
    6
    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. Serepa

    Serepa

    Joined:
    May 15, 2015
    Posts:
    32
    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.
     
    hippocoder likes this.
  20. CarterG81

    CarterG81

    Joined:
    Jul 25, 2013
    Posts:
    1,773
    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 o_O What takes up the majority of your time? Out of curiosity.
     
    Last edited: Dec 10, 2015
    newmant and hippocoder like this.
  21. Graham-Dunnett

    Graham-Dunnett

    Administrator

    Joined:
    Jun 2, 2009
    Posts:
    4,287
    Well, the team is 3 now. It's been just about 1 person for the last 2-3 years. The team will grow in 2016. So I fully expect the docs to get better. That's important to me. And I agree that some docs are not good enough. And we'll work on getting the docs better next year.

    Also, we now have new releases every 3 months, and hopefully people will see the new docs for the new features in 5.3 are pretty good. And shipped on time. This is pretty important to all of us.
     
    BTStone, hippocoder and CarterG81 like this.
  22. CarterG81

    CarterG81

    Joined:
    Jul 25, 2013
    Posts:
    1,773
    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 :p

    So well done! Well done.
     
  23. Graham-Dunnett

    Graham-Dunnett

    Administrator

    Joined:
    Jun 2, 2009
    Posts:
    4,287
    :) Good to know.
     
  24. feiting

    feiting

    Joined:
    Oct 26, 2012
    Posts:
    33
    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.
     
    Hodgson_SDAS likes this.
Thread Status:
Not open for further replies.