For some odd reason, I can only understand things about coding through coding itself. I don’t know why, but all those databases for explaining things just make no sense at all for me, or even errors on coding.
For example, I’ll just grab an article:
"Calls the method named methodName on every MonoBehaviour in this game object.
The receiving method can choose to ignore the argument by having zero parameters. If options is set to SendMessageOptions.RequireReceiver an error is printed when the message is not picked up by any component."
I know what SendMessage does: a script tells another script(s) to perform one of its own functions. Why couldn’t they say it that simple? I cannot even understand what the 2nd line of that page is even saying! This also happens to me whenever I’m on Unity Answers or on Stackoverflow, I literally cannot comprehend on what the “answerers” are even saying.
Are the references too complicated for most people, or am I just too stupid? I’ve always wondered this. If I become a really advanced programmer, am I somehow going to become one of those people who sound way too complicated for amateurs/beginners?
Because your revised version is actually less descriptive to an experienced coder than the one they have.
Having read and not-understood many a doc page in my lifetime, I can see where you’re coming from - on the other hand, for more experienced people the more technical terminology is more precise and thus helpful.
For example, what you’re missing in this doc page is understanding of the terminology used.
Method - a block of code with a name and a series of arguments
function DoSomethingCool(arg1, arg2){
//blah blah
}
In that example, we have a block of code (inside the braces), it is named ‘DoSomethingCool’, and it has two arguments that is, objects that can be passed in for the method to do something with.
MonoBehaviour - is the base class for everything you attach to a gameobject in Unity.
So there are quite a few differences between what your description of SendMessage does and what the actual function does. The big one is that there is a difference between a script and a MonoBehaviour - a MonoBehaviour is a script, but a script is not a MonoBehaviour - kind of like how a pen is a writing device but a writing device isn’t necessarily a pen. The other difference is that a script does not tell another MonoBehaviour to call a function - it tells every MonoBehaviour on the target game object to do something.
Imagine you have a Hair script with a SetColor() function, which (surprise!) sets the color of the hair. Also imagine you have an Eye script with a SetColor() function, which (surprise) sets the eye color. Now imagine you have both of these attached to a GameObject named head. If you call head.SendMessage(“SetColor”, Color.red), then it will not only set your hair color to red, it will also set eye color to red. Which may be what you want, or it may not - that’s why it’s so important for the documentation to be detailed and specific as to exactly what the code does.
API docs are written the way they are for a reason. They need to be complete and specific, and they need to inform you how to use something as well as what it does.
As flaminghairball said - the additional detail/terminology is a useful tool that takes time to learn.
For example that second line: “If options is set to SendMessageOptions.RequireReceiver an error is printed when the message is not picked up by any component.”
Is very important. It tells me there is something called ‘options’ that I can set to ‘RequireReciever’. It’s apparent from surrounding documentation that this is an optional parameter, that is set to ‘RequireReciever’ by default. If this is set as required, then my code will throw an error when a receiver is not found. If not, the code won’t care.
Now, if as a programmer I assumed one setting over the other… then I’ll very likely be producing buggy code. As such, if the documentation didn’t specify what happened - then I could spend hours trying to reverse engineer the functionality!
His issue isn’t what it says, but how its said. And yes, it can be a bit confusing at first. Unfortunately, a large part of programming is elitism, and being able to speak and understand the “lingo” is a way of “earning your stripes”.
Oddly, the way I learned programming was through the GameMaker documents, which explain things in an understandable, human language. I was thrilled as I read them, because this strange, foreign language finally made sense to me!
For now, just break down the sentences into small pieces; one word at a time. Re-read it a few times, and eventually, you’ll understand it. After a while, it will make sense and, as you read future documentation, you’ll just find yourself shaking your head at the overly technical sentence structure.
I think that to express theirs professionalism, unity presents their documentation in technical writing. I don’t see anything wrong with that, that is what we have to expect with most of the thing related to knowledge. It’s short and precise, there’s no need to be verbose in that kind of thing.
It’s not just Unity though. Majority of scientific fields have an obvious need to be exact and thorough and thus all the books covering any naturally interesting things are incredibly boring to read. That’s why most people don’t like to study.
These aren’t accurate assessments. Programing/engineering software is a precise process simply because of its nature. As a technical field it has a specific terminology that have precise meanings. Function and method for example have contextual differences. It is not a rite of passage or “earning your stripes” or done arbitrarily. And definitely not overly technical, since it is a technical field to begin with. When working with other engineers, this is how you communicate, it save times and makes sure there are no misunderstanding.
Just to reiterate what both flaminghairball, angrypenguin and npsf3000 have said, it is API docs are specific concise explanations of the API. It has nothing to do with “elitism” or professionalism is all about accuracy. It is in no way intended as “programing for beginners”. The unity docs have overview sections to help with that. If you diving into the API docs it is assumed you bring with you a knowledge of programming. It would like looking a appendices or footnotes in a book, without having read the book.
That being said, while very useful, the Unity API docs are pretty under documented in some cases. Especially with regards to the editor stuff. Often I come across a class or method with a single line vague description with details. Stuff like styling custom editor panels, with something like “uses GUIstyle” but then it is a bit of guess and check to find out which styles are actually supported. I can understand being light on some the C# stuff as you dig deeper at the MS site, but things are unique to Unity and not part of the generic C# structure could be expanded on.
For those of you who find the API confusing, check out the unitygems site, they are getting a pretty deep base of explanatory articles/tutorials that may help. That site it really turning it a fantastic resource.
Alternatively the documentation could be done as such:
I think it’s important to note that just because technical terms are used that doesn’t mean the documentation is perfect - from a noob or ‘expert’ POV. There are a range of unrelated problems that have nothing to do with terminology that can also impact readability and understandability. However, as far as API’s go the Unity3D one is fairly approachable… and the job of a programmer is not only to solve problems but to translate problems/solutions from several different ‘languages’ paradigms. This can, particularly at the start, cause pain. However at the end of the day no matters how much more can be done, you have to learn to use what exists today and push on past the pain - you can’t expect perfection and function.
They have the proffesional way of saying it up there, but as a company that fuels one of the largest groups of indie devs that are just starting they should have a simpler way of saying the stuff also. So ya i understand where your coming from but say a 3 year college grad with a master in Computer Engineering comes in and sees unity as a great device and thinks of using it as a engine for a game. But then they look at the docs and see the docs saying a term in a few words, the grad might think of the company as a low development company not meant for the big leagues so they might take there bussiness somewhere else. Its all about the way that it is bieng presented.
This is very true. Though generally, Unity’s docs are pretty good, they do fall pretty short when compared to something like AS3 docs. They use a ton of examples and have great notes on things like performance and alternate ways of approaching the same goal.
I have noticed that the docs are difficult to understand, but understanding them is not a part of becoming an “elitist” programmer. Programming is programming, simple as that. How well you do it depends on your own experience, and while you may not learn much by looking at the documentation of a function, they include a bit of contextual code so you get a bit of knowledge for using it.
It’s also helpful to use some good old-fashioned trial-and-error to get what you need, so while the docs are useful for understanding how to write the little bit of code to finish your script, they aren’t the giver of all life to the coding world.
They do, in plenty of places, tutorials, getting started and overviews and demos. There are plenty of places outside of Unity as well. But is not what the API docs are for, they are NOT as starting place (unless you know what you are doing already). If you are new to programming/Unity/whatever, start with tutorials, the overviews etc. Indie does not mean n00b, and dumbing down the API docs is the surest way to drive Unity fully in to the hobby/toy realm.
