Search Unity

  1. Megacity Metro Demo now available. Download now.
    Dismiss Notice
  2. Unity support for visionOS is now available. Learn more in our blog post.
    Dismiss Notice

Actually I have another question folks about Unity documentation

Discussion in 'Getting Started' started by boylesg, Feb 20, 2016.

  1. boylesg

    boylesg

    Joined:
    Feb 18, 2016
    Posts:
    275
    I have had a brief look at the online documentation (and have been warned where I am working at present) that the online documentation for Unity is as about as useful as a dog turd.

    So when faced with, for example, getting a list of all Unity's equivalents of Arduino's predefined functions setup() and loop() (e.g. Update()) and their parameters and purpose etc, where do you folks go to get that info?

    You must be getting that info from some where other than the Unity document pages!

    Otherwise I doubt that this online community would exist because few people would be bothered with using Unity.
     
  2. aer0ace

    aer0ace

    Joined:
    May 11, 2012
    Posts:
    1,513
    Is it really that bad? I feel that I'm pretty productive with Unity's documentation. Like, what's wrong with this?

    http://docs.unity3d.com/ScriptReference/MonoBehaviour.html
     
  3. boylesg

    boylesg

    Joined:
    Feb 18, 2016
    Posts:
    275
    Well that is what I was told by another fairly experienced unity user.

    And when I went to look up a function myself the other day it told me little or nothing about it.

    Perhaps you are just not finished documenting it yet and part of it are little more than stubs?

    Can I respectfully make a suggestion to you - something that I learned myself the hard way.

    I was asked to write a manual on how to install a new hard drive into a Tabcorp (in Victoria, Australia) Easybet terminal and ghost the operating system plus software on to it.

    My first attempt was a dismal failure with the testers having no idea how to practically do it.

    In the end I had to try and picture myself as a non-programmer / non-hardware person and try to imagine using norton ghost for the first time and trying to install a hard drive into a PC for the first time.

    That meant writing a detailed step by step instructions of every minuscule step that has to be carried out - things that you and I breeze over and don't give a second thought to. With screen shots at nearly every step.

    It ended up being quite a large document but most of the testers were able to follow it with relative ease and I scored some kudos.

    As a rule of thumb, programmers generally make extremely poor manual writers.

    So next time you are adding or modifying your documentation imagine me, a Microsoft Visual Studio user, who may be generally familiar with the layout of the Unity architecture, due to similarities with Microsoft Visual Studio and Arduino microcontrollers, but with no detailed knowledge of all the functions, parameters, data structures and object properties etc as well as the idiosyncrasies of the IDE environment.

    Please be as generous as possible with your typing!

    Also why the buggery is 'rename' not in the right click menu for scripts. Why is it necessary to omit this from the IDE and force a novice user to hit F2 in order to rename a script. I would not have had a clue about F2 unless the manager fellow pointed it out to me.
     
  4. aer0ace

    aer0ace

    Joined:
    May 11, 2012
    Posts:
    1,513
    If it is this stage at where you are with Unity and/or game development, then I can completely understand your complaints about the documentation. The Unity documentation definitely assumes some prior knowledge of software/game development and C#. That said, Unity Technologies, and game development studios in general, move quite quickly in terms of evolving the engine, so the documentation can take somewhat a backseat to what you are expecting in terms of in-depth explanations of functions and usages.

    What was the function? If it was something that sounded arcane, then I don't blame you, but generally, software APIs strive to be as self-explanatory as possible.

    I guess you are right with your statement:
    The documentation usually serves as a starting point for more in-depth searches of certain methods and patterns. If you find yourself having difficulty understanding one or the other, usually it's a Google search away for that particular method, for finding example usages. Failing that, usually a forum search works. Failing that, you can try Unity Answers, and failing that, you can post questions on the forum here, and the community here is pretty great at providing usable solutions. Anyway, I think this workflow is basically what anyone working with any game development platform uses for their projects.
     
    Last edited: Feb 20, 2016
    Schneider21 likes this.
  5. boylesg

    boylesg

    Joined:
    Feb 18, 2016
    Posts:
    275
    Have a look at this: https://msdn.microsoft.com/en-us/library/77d16yhw.aspx. This is what I would expect from documentation. It is not perfect, but once you get the hang of the Visual Studio IDE, setting up dialog boxes in the resource editor and then applying message map function to it with the class wizard then what Microsoft has provided here is generally enough to figure out how to use the functions.

    And if it wasn't for this, even now I would have little hope of using Visual Studio successfully because there are vastly more functions and message maps than I have ever used. Usually, within a few clicks, I have found all I need to know to try the new function and figure out properly how it works by experimenting with it.

    The Unity function I am talking about was related to the Roll a Ball tutorial but I forget off hand precisely which one it was. All I got was something like this:

    function XXXxXXX(XXXXX, XXXXXX)
    {
    .........
    }

    No explanation as to its purpose or usage, no explanation of parameters, no example code snippets of its use.

    Re Google searches.

    If you want Unity to be a serious contender for the hearts and minds of programmers then, like Microsoft, you need to take your documentation seriously and not leave it to finding a needle in the google hay stack for absolutely everything about Unity.

    Why don't you come up with some wikipedia like system where your community in here all contribute to building up the documentation and making it highly useful to newbs like me. You know the saying - many experienced hand make light work!
     
  6. JoeStrout

    JoeStrout

    Joined:
    Jan 14, 2011
    Posts:
    9,859
    First, @boylesg, you keep writing as if you're addressing Unity... you're not. There are indeed some Unity employees on these forums, but they haven't jumped into this thread, and there's no guarantee that they will — this is a community forum.

    Second, I agree with @aer0ace that the Unity docs are actually pretty good. Almost every function and property has a decent explanation and code samples in multiple languages. The exception is stuff that is arcane or very new. You can log a bug against specific documentation errors or omissions, and they'll usually fix it in a future release. But I code every day relying heavily on the Unity docs (usually the script reference, but sometimes the manual too), and it's working fine for me. No, they're not Microsoft. But they're plenty good enough in almost all cases.

    Finally, if you want a wiki the community can contribute too, well, they have that too. But I think you'll find the community is even worse at keeping this up to date than Unity is at maintaining their official docs. :)
     
    Schneider21, aer0ace and Ryiah like this.
  7. boylesg

    boylesg

    Joined:
    Feb 18, 2016
    Posts:
    275
    Aer0ace is clearly a unity employ responsible for the documentation, so that is why I have been 'addressing the thread' as if respondents were unity employees.

    So Aer0ace, you can regard the following as primarily addressed to you. And I am not being nasty to you, Unity company or the community. I merely trying to give you some useful feedback from my respectable experience with other IDEs and languages etc at what they make available to their customers.

    I just tried to go into the unity website: http://docs.unity3d.com/Manual/ScriptingSection.html and tried to figure out the function that had poor documentation.

    And immediately it is far from obvious to me (as a brand new user) how to access that part of your help pages that you access with the CTRL + ` (or what ever it was) in the Unity IDE

    I would have expected to find those same pages in the 'scripting' link some where. But after clicking around for a few minutes I am no closer to finding them than when I started.

    I tried searching for 'update' for example and come up with nada/zilch

    In contrast, if I did a google search for CWnd::GetDlgItem, I would come up with page 1 full of references to that MFC function in online MSDN (Microsoft Developer Network)

    So until I go back to work I can't provide you with an example of a poorly documented function.

    And remember I am a brand new user - I was told by a more experienced Unity user not to be too reliant on your documentation because it is crap on the whole.

    I suggest the Unity management take this seriously, because your software is only as good as the support you give to your customers. Microsoft Visual Studio is a an industry standard in large part because of the extensive documentation and support they provide through MSDN.

    Now I have been looking for an alternative to MIT app Inventor 2 and Android Studio (difficult to get working on XP and just plain confusing to use) and Unity has never come up in any of my searches. Despite the fact that it seems some what easier to use than Android Studio on the whole.

    Unity could be a force for Google and android studio to reckon with if the management took documentation and support as seriously as Microsoft does through their MSDN. You almost certainly need an employee that is dedicated to documentation and support, not continually being distracted by software development issues.
     
  8. JoeStrout

    JoeStrout

    Joined:
    Jan 14, 2011
    Posts:
    9,859
    Is he? Usually Unity employees are identified with a big "UNITY TECHNOLOGIES" banner (see Tomek's post here for example).

    I think he is (like me) just a guy trying to be helpful to a fellow Unity user.

    Yeah, you sure found an interesting one there — that's not the script reference; that's a section of the manual about scripting. (As you can tell by the page title "Unity - Manual: Scripting" and the big "Unity Manual" header atop the table of contents on the left, though I admit you would have to know how the terms "Manual" and "Script Reference" are used in these parts to see the significance.)

    I guess if you google Unity scripting, the link you want is actually the second one ("Unity - Scripting API", with a URL that clearly says ScriptReference). If you just clicked the first one, then that could lead to the confusion. Of course Unity has little control over how Google orders its search results.

    But a google search for "unity script update" does produce the page you're looking for (as the top result, even!).

    Well obviously you can't just google the word "update" because (unlike CWnd::GetDlgItem) it is an actual English word, that occurs in many contexts other than Unity scripting. But, as we've seen, if you throw in a couple of context words then Google will take you right where you want.

    Oh, I bet I could come up with a few. They certainly exist. But on the whole, Unity's docs are some of the best I've seen for any company 1/1000th the size of Microsoft.

    Well, now you know not to listen to that guy. I bet I'm a more experienced Unity user than him, and I rely on the documentation almost daily because it is, on the whole, quite good. :)

    No argument there. But stick around a while, and I think you'll see that Unity supports its customers pretty dang well. Yeah, the docs aren't perfect. But when was the last time you had a Microsoft engineer help you out as quickly as this guy did just last Thursday?

    I'd be seriously shocked if Unity doesn't have a whole (small) team of tech writers and support staff. They're not Microsoft, but they're not that small, either.

    Anyway, your suggestions are reasonable (though you're making them in the wrong place — the best way to help improve the docs is to file a support ticket). And yeah, I realize I sound like a fan-boy. That's because I've been a software engineer for 25-ish years, and spent about 10 years of that in the software tools business myself, and Unity is the best software development tool I've ever found. It really is dramatically more productive than pretty much anything else, at least for certain kinds of apps (mainly games), and especially when you care about multiple platforms.

    No, it's not perfect. But it's still awesome. Dig in, learn to use and love both the manual and the script reference, do some tutorials, and if you get stuck on anything, ask! We're a friendly bunch.
     
    Schneider21, Tset_Tsyung and aer0ace like this.
  9. aer0ace

    aer0ace

    Joined:
    May 11, 2012
    Posts:
    1,513
    Clearly... I'll get right on it.

    You know that feeling you get when someone at the store asks you what aisle something is in even though you don't work at the store? Yeah, that.
     
  10. boylesg

    boylesg

    Joined:
    Feb 18, 2016
    Posts:
    275
    Then why did you say this: "I feel that I'm pretty productive with Unity's documentation."

    Why would you be personally concerned about the documentation if it was not your job?
     
  11. aer0ace

    aer0ace

    Joined:
    May 11, 2012
    Posts:
    1,513
    I think you read that wrong. You probably read it as:
    when I meant:
     
    Schneider21 likes this.
  12. boylesg

    boylesg

    Joined:
    Feb 18, 2016
    Posts:
    275
    Fair enough then perhaps I should put all this to the appropriate Unity personnel as suggested. How exactly do you go about that?

    I forget who it was that pointed me in the direction of this http://docs.unity3d.com/ScriptReference/30_search.html?q=update

    But thanks - it is a huge help. I was getting very frustrated not being able to find the info I was seeking.

    But still rather odd that the manual and the above are not linked and cross referenced etc so that a word search in either points in the direction of the same pages.
     
    Tset_Tsyung likes this.
  13. boylesg

    boylesg

    Joined:
    Feb 18, 2016
    Posts:
    275
    http://docs.unity3d.com/ScriptReference/30_search.html?q=update

    With this function description, what would really help is to make mention of the fact that this, and presumably all Update(...) functions are called in a continuous loop.

    As an Arduino programmer that would make immediate sense to me because the Arduino IDE code architecture is setup in a very similar manner.

    But reading this description it would not be immediately apparent to me that this is indeed the case.

    And I believe that there is a whole $hitload of continuously called functions like update(...).

    How do you get a list of them from the scripting API page in the same way you can get a list of all members for the MFC class CWnd?
     
  14. aer0ace

    aer0ace

    Joined:
    May 11, 2012
    Posts:
    1,513
    I'm not sure how you are introducing yourself to Unity, but one path is to read through the manual. I don't want to sound like "RTFM", but it explains a lot of how Unity is architected before jumping directly into the API.

    Have you taken a look at the manual here? Expand the tree to get into more details.
    http://docs.unity3d.com/Manual/ScriptingSection.html

    One of the pages in that section describes the Update() function, and how it operates in respect to MonoBehaviours which are your components for GameObjects:
    http://docs.unity3d.com/Manual/EventFunctions.html

    Again, not sure if you've already gone through all this, but you definitely need to attack learning this sort of thing from different angles, rather than just looking at the API documentation.
     
    JoeStrout likes this.
  15. JoeStrout

    JoeStrout

    Joined:
    Jan 14, 2011
    Posts:
    9,859
    Also see here for complete documentation on exactly when the various "events" (really just callbacks from the engine) get called.
     
    aer0ace likes this.
  16. zombiegorilla

    zombiegorilla

    Moderator

    Joined:
    May 8, 2012
    Posts:
    9,042
    Ryiah likes this.
  17. ZombieGorillaWTF

    ZombieGorillaWTF

    Joined:
    Jul 26, 2012
    Posts:
    2
    This isn't a 'function description', this is a search results page for API pages containing the phrase 'update'. (As the title of the page indicates)

    I agree with ace and joe, the unity docs aren't perfect, and there are problematic areas, but overall they are pretty easy to navigate and generally pretty good.

    You just have to take your time, pay attention to the area you are in (reference, overview, tutorials, etc. ), and you will find what you need. Learn what is there and how it is laid out, rather than trying to impose your own expectations, and you'll quickly start finding your answers.
     
  18. zombiegorilla

    zombiegorilla

    Moderator

    Joined:
    May 8, 2012
    Posts:
    9,042
    Whoa. ^ that was me. My phone got logged into my other account. ;)
     
    Ryiah likes this.
  19. Deleted User

    Deleted User

    Guest

    The API exists to document Unity, not C# which has its own documentation. If you want to learn C# basics, any C++ resources will do. Unity's documentation seems to have a few small holes on some specific functions, but they're mostly self-explanatory ones.

    Furthermore, it includes a manual with examples as well. As far as I know that's not typical of an API. Knowing only C++ most of the problems I am having in picking up Unity (week 1 here) are quirky trivialities that wouldn't stop me from getting something done; just little things that bother the perfectionist in me.

    So far it's an amazing engine and I think it's incredible that these tools are free to begin using.
     
  20. Ryiah

    Ryiah

    Joined:
    Oct 11, 2012
    Posts:
    20,952
    That's a bit like suggesting you can learn UnityScript by following JavaScript tutorials. While you may pick up much of the language that way there are going to be differences that would be better explained by tutorials covering the language you're actually interested in using.
     
  21. BrUnO-XaVIeR

    BrUnO-XaVIeR

    Joined:
    Dec 6, 2010
    Posts:
    1,687
    If compared to other public engines (UE4 which I use every day, or CryEngine), Unity's documentation is heaven.
    For me Unity's docs are very complete and nowadays is hard to come across anything you need to R&D, almost everything Unity is out there in official docs or somebody else's blog.
     
  22. Deleted User

    Deleted User

    Guest

    First, Don't try to learn a programming language with fragmented tutorials. You need a comprehensive book. That's terrible advice because there are so many cheap books available and the structure for teaching these languages is so well established.

    Also, no it isn't. C# is a direct derivative of C++ mostly with more limitations. UnityScript and JavaScrips use completely different syntactical structure. Understanding how pass-by-reference and pointers work in C++ makes using references a in C# a breeze because you've already done something harder (building your own arrays using pointers).

    Learn C++ and/or Java and you have an awesome foundation. This isn't overkill if you actually want to make games.
     
  23. JoeStrout

    JoeStrout

    Joined:
    Jan 14, 2011
    Posts:
    9,859
    Wow, I assumed that your "to learn C#, use C++ resources" suggestion was just an unfortunate typo. I'm with @Ryiah on this one; this is bad advice. C# is far more removed from C++ than UnityScript is from JavaScript (which use the exact same syntax, BTW). Java is closer to C# than C++ is, so that would be a little better, but an even better way to learn C# would be to use C# resources. They're all C-derived languages, but that doesn't mean they have more than superficial similarities.
     
  24. Deleted User

    Deleted User

    Guest

    You want to learn C++ first because if you do you will have better foundational knowledge. Look up the differences between C++ and C# and if you don't know what they are, you should learn one and then the other. Knowing C++ makes learning other languages easier.

    The people asking these questions don't even understand the basic elements of object oriented design and they're already talking about developing games. It's not going to go anywhere if you don't know what a finite state machine, or variable scope and type, or inheritance even are. Most of what you'll learn studying C++ will apply to any language.

    Learning computer programming from YouTube is awful. Get a book, you're going to need the ability to rapidly reference previous chapters.

    There's nothing wrong with starting with C# I suppose it's just what I was taught.
     
    Last edited by a moderator: Feb 26, 2016