Unity Documentation Outdated

Just posting this here so that ANYONE who is even remotely responsible for Unitys development realizes that the documentation is horribly outdated. Some of the options have been moved (and keep moving since new updates come out weekly) and some of the articles are just misleading!
Dont do continuous deployment if keeping docs up to date is too hard...

 

The documentation 9 times out of 10 has the compatible version of Unity listed in the top left of the screen. Also Unity documentation is pretty much miles better than any other engine documentation out there and gets updated all the time, so...

 

Holy ****, THIS!

 

I mean hell, I've long had criticisms of Unity. Loads of them. Thankfully, the 2017 and later cycle started to address my major complaints, but if UE4's documentation was even half as good as Unity's I'd have switched.

Unfortunately, it's maybe 5% as good.

 

I agree it's far better than plenty of other documentation I've used. It also definitely has it's issues. Are you bug reporting them?

 

Haven´t really noticed any outdated information but the search in the Manual just kinda kills me.

Search "Rigidbody2d" and only get "Rigidbody 2d" as the seventh result. Or search for "tile" and the first five results is the same duplicate entry. I am kinda used to at least having a quick search without loading over just matching titles but the Manual doesn´t even seem to have that. Maybe I am missing something obvious here but I am having more luck finding the right entry asking Google than the Manual.

 

Yeah, manual / api search sucks.
It's faster and yields better results to simply google it. Which will return manual page anyway.

 

Like @Murgilod mentioned below, are you using the right version of the doc?
Also, you can report a problem with a page since each of them has a "Report a problem on this page" link. See screen captures below.

​

 

I'm a huge fan of good documentation because it greatly assists with helping new developers, but at the end of the day if the choice is between ideal documentation and an up-to-date engine I'll always choose the latter because explaining how part of an engine works is far easier than trying to work around the limitations of outdated software development tools.

 

The documentation is enormous. You're not being actually helpful unless you give some specifics as to what is wrong.

The only criticisms I've had of the documentation isn't being wrong, but being a bit light on details for some pages. A specific simple example that seems to continually come up on this forum is Vector3.ToString(). Here's the entire documentation:

https://docs.unity3d.com/ScriptReference/Vector3.ToString.html

New Unity devs using this though don't realize that the individual x, y, z values get truncated by default. That isn't mentioned in the docs. To get the "exact" values you need to do something like:

Code (csharp):

1. string actualVector3ToString = vector3.x.ToString() + " " + vector3.y.ToString() + " " + vector3.z.ToString();

Maybe you can mess with the "format" optional parameter, but I haven't tried messing with it, and that could use some documentation there too.

 

In these cases (ToString(format) at least a link to the Microsoft C# documentation would be great IMHO.

 

Don't bother using Unity's built in search functions. Just do a google search with "site:unity3D.com". You can do the same with the forums.

Built in search sucks.

 

Fortunately, it also works with other search engines; unfortunately, I couldn't find what I'm looking for. I search the doc for "ternary operator" and there seem to be nothing about that in the documentation... It seems that the only reference to ternary operators existing on this site is the video tutorial and it doesn't say much about how to use it best.

site:https://docs.unity3d.com/ ternary operator

 

That's because it's part of the C# syntax, not Unity's API.

https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/conditional-operator

 

Same thing for the properties I imagine. I don't understand why some things that are part of the C# syntax are in the api and others are not...

 

It is very simple: if they (Unity) defined it or redefined it, it's part of the documentation (see != and == operators in most cases). If it's part of the C# as-is, it's not part the documentation because you already suppose to know that (C# perquisite).

 

Unity's documentation is terrible when compared to Unity's documentation (it is competing with itself because all other engines don't ever come anywhere near close, combined).

 

Not true. Documentation for Gamemaker is far superior (or at least it used to be - I haven´t used Gamemaker 2). Easy to search, everything is documented with code examples and relevant topics are cross referenced. I could actually learn & find new functionallity I needed in the documentation without even having to use google or any online resources.

Most companies won´t or can´t dedicate the nesscary resources to make a proper documentation (I would know since it is the same for the place I work at) but it ain´t impossible.

 

If you can't find it in the Unity documentation, try the C# documentation on MSDN. If that doesn't work, try google. If that still doesn't work, post in the scripting section.

 

Er, not really that clear cut.

Put it this way, if something as limited in scope as Game Maker had more and better docs than Unity, then Game Maker would be one of the most complex engines available. Much more likely, you came from using Game Maker and expected the same tiny subset of information to be immediately available.

But if we compare the feature set of Game Maker and only that feature set vs Unity, then I'm sure it would be logical for Game Maker to have superior docs, if only for 10% of Unity.

Since Unity is this vast, and encompasses a lot more than Game Maker (the equivalent would probably be a playmaker on asset store) so are it's docs. You have to hunt because it's not just designed for tiny 2D games.

So the problem is that Unity does everything, so it's hard to show you the exact limited thing one might look for. Some ideas could be:

- google
- youtube
- udemy
- learn section
- unity blog
- these forums

etc... if struggling, I recommend you post - people will help find the resources.

 

I am not sure if I understand your argument here.
Yes, Gamemaker is more limited in scope and therefor has an easier time with documentation. This still makes their documentation better.

The vast nature isn´t the issue here. C# encompasses even more than Unity but it still has proper documentation at times like this:
https://docs.microsoft.com/en-us/dotnet/api/system.array.indexof?view=netframework-4.7.2

The Unity manual often has just the bare minimum documentation for their functions which look just like a 1 to 1 doxygen export:
https://docs.unity3d.com/Manual/script-Physics2DRaycaster.html

Good documentation doesn´t have to show the exact little thing one is looking for. It just has to explain the existing functions properly - how to use them is the developers job.

Just to be clear I can understand that improving the documentation isn´t the biggest priority for unity since there are plenty of easy workarounds - I am just pointing out that better does exist.

No worries, I have used Unity long enough to figure out where to find whatever I may need but I can´t help but be annoyed at times when I have to hunt through multiple forum posts & manual pages and trial&error may way through Physics.RayCast, Physics2D.RayCast and Physics2D.GetRayIntersection instead of just being able to ask the manual what my options for raycasts are and it telling me some basic stuff like how it actually truncates my z-axis without telling me.

 

His argument is that the easier a subject is to document the less impressive the achievement is and I have to agree with him. If you're going to brag you should at least pick something worth bragging about. Like Microsoft's Developer Network which far outstrips just about every other documentation project.

 

*shrug* Gamemaker is still a game engine which was the initial claim - not to mention that my point wasn´t the amount but the quality.
No clue where bragging has come into the picture here.

 

Best way I could describe it.

 

I'm posting from 2020 and their documentation is still outdated.

 

Very useful thanks for the necro

 

There are entire sections of the documentation that only exist in earlier versions of the engine manual but not newer ones and there's huge swaths of the scripting reference that still don't explain what things do or how they're used. There have been numerous times where my best option for figuring out how something works was to use google translate on a page written in Japanese from years ago.

So yeah, there are still documentation issues across the board here and it's becoming a pretty big problem that Unity has failed to really mention even just the idea of a plan to address this. Unity is a big company, they can't bring on more technical writing staff?

The necro is meaningful because nobody at Unity seems to be willing to raise the dead in their documentation areas.

 

That's crazy talk. If you need more than a 1 sentence description of what something does, then Unity has no time for your level of hand holding.

https://docs.unity3d.com/ScriptReference/AudioClip-frequency.html
https://docs.unity3d.com/ScriptReference/AudioClip-loadInBackground.html
https://docs.unity3d.com/ScriptReference/MeshCollider.html

Spoiler

Kidding!

 

I send a bug report every time I find something unsatisfactory in there. There are some things I bug reported multiple times, but they eventually did change.

 

So I was browsing the docs because I figured the other night "hey, maybe I should try using the Unity APIs instead of rolling my own stuff that may already be there." Made a "cool" discovery.

https://docs.unity3d.com/ScriptReference/Grid-cellSwizzle.html
https://docs.unity3d.com/ScriptReference/GridLayout.CellSwizzle.html

These one sentence functionality descriptors suffer from a couple problems.

First, "CellSwizzle" is a term that has no real meaning on its own. Saying "the cell swizzle of the grid" is useless. It means nothing. If you click through, you get the list of coordinate orders. If you're an experienced dev, you'll probably be able to go "oh, okay, I understand how this works," but if you're not really experienced in Unity, or with coordinate systems in general, you might end up going "what the actual goddamn F*** is a swizzle?"

So you google it.



Oh, that's very helpful.

So you google "cell swizzle" specifically and you get this thread on reddit:
https://www.reddit.com/r/Unity3D/comments/7s06a2/cell_swizzle_what_the_heck_is_it_reading_the_docs/

And this leads to another discovery: nowhere in the Unity documentation is "swizzle" actually explained, and the place where swizzle is most commonly used as a term (and the only reason I knew what it was in the first place) is in from shader programming, which is something Unity seems to have kinda gone out of its way to avoid diving deep into, maybe in part because it is a highly technical field with loads of usability issues, maybe in part because it deals with a lot of of technical jargon that assumes a lot of experience and knowledge.

Where does the term show up in Unity?

The tilemapping grid system.

How long has this been documented like this?

About three years.

 

I found a definition but no one would have thought to go looking for it there.

https://docs.unity3d.com/Packages/com.unity.shadergraph@6.9/manual/Swizzle-Node.html

 

In graphic/shader programming "swizzile" actually often refers to coordinate access syntax used in vertex and pixel shaders, which allows reorder of source components and their reassignment.

"v1.xyz = v2.zxy", "v1.xyz = v2.zzx" and the like. .zxy part is the swizzle.

Here are the docs with more examples.
https://docs.microsoft.com/en-us/wi...registers-modifiers-source-register-swizzling

So, yeah... channel reordering.

 

I address this later in the post. In the context of this documentation, it means nothing. It exists without context.

 

[/QUOTE]

I mean, that's great and all, but—

Three years is a pretty long time for things like single sentence explanations of new features using specific technical terms.

 

I suppose part of the problem is that this rings hollow, given Unity's long-standing "say something is being done, several years later nothing has been done" pattern? A blog post is great, but there's a pretty big reason I'm using Unity for wrapping up existing projects and supporting legacy ones rather than pursuing new development. Documentation is one aspect of "we're working on it, we promise!" (I saw this come up years ago, in fact) that it seems pretty risky to take at face value.

 

Merry Christmas And thanks for your continued interactions on the forum, they do not go unnoticed and we really appreciate your time and effort responding to us all here

 

See, I don't really buy this either. Whenever we've been told things in the past, and I suppose I should gesture towards the 4.6 UI situation, is that we were told that a new UI was coming. For years, even, very similar to the documentation situation.

And then we'd be told "yeah, it's still coming."

And then again, and again.

And then we got something that was so removed from an industry standard UI toolkit that, years later, we're getting a new one, and credit to Unity, we actually get substantial development updates there.

But if we just got a blog post every 8-10 months or whatever, it'd be a dramatically different story, and that's actually better than what we've seen on the documentation from. It's actually a pretty sorry state of affairs that I can expect single person indie devs to provide more reliable devlog posts than a multibillion dollar corporation with thousands of employees, you know? A blog post wouldn't be any good, but a dedicated forum with staff responses and updates like we've gotten with UIElements/UIToolkit/UIWhateverIt'sCalledThisWeekDespiteHavingADifferentNameInTheDocumentationAndEditorAndNamespae or any number of the other packages would be good.

There have been loads of single sentence API refs for ages and I have to, as I have a few times in the past, gesture towards the absolute gold standard of documentations that is the Microsoft C# Guide/Reference, which not only includes references for the language itself, but also goes in-depth into how it's used and implemented. Peep their reference page for async, for instance

https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/async

It actually feels like around 5-ish years ago, these sorts of pages were a lot more common in the scripting reference, you know? But maybe that's the price Unity (and thus, its users) pay for the years of constant feature additions that serve more as back of the box bullet points than actually useful dev tools.

edit: to add to this, the radio silence and lack of rolling updates brings with it another concern: if we don't know what's being done and we can't even have the vague implication of feedback in response to changes, it runs the risk of being like the old Lithium rollout. One day things just change over to a new system with no concern for user feedback and we're left wondering if things will be rolled back while having to deal with a potentially even more unworkable situation in the meantime.

 

Merry Christmas to you and the rest of the team and forum too!

I had a hunch you switched engines when you stopped posting here for a while. What are you picking for new 2D and 3D projects?

 

Right now I've been rolling an in-house solution that I've been gradually bulking up. It's pretty raw at the moment, really simple asset pipeline, a bit of a pain to deploy to non-windows platforms (though they're not a priority in the first place for me). Its renderer is really standard OpenGL, but I'm keeping it loose enough that I can slot in Vulkan if I ever feel the need for that.

A couple key parts, however, are that I've been building it from the ground up to rely heavily on ECS as its core architecture, which has had some pretty significant performance gains; and it has a UI system that's basically just an extension of XML that doesn't make me want to kill myself.

 

Wow, rolling your own solution was pretty far down the list of answers that I expected. Would you say your usecase is so special that this is a unique situation? I imagine if any of the other engines where a good enough fit you'd have picked one of them?

 

We've heard a lot about the docs team increasing in size for more than a year. I haven't actually seen any tangible changes - new features consistently have poor-to-bad documentation, and there are always open questions. Back when we started using Unity, we didn't have to nag devs on the forums to get to know how things worked.

One problem that you have to look out for is that devs don't want to write docs. If there's a big documentation team, that gives the devs an excuse to say "look, they're responsible for documenting stuff, so we don't have to".

More than hiring documentation people, you need a culture shift internally to understand that your work is pretty much worthless if it's so poorly documented that nobody can use it. Public API methods named DoAThing() where the documentation is "Does a thing" is more common now, not less.

You need to just not let teams ship stuff that's not documented. I'm a programmer myself, I also want to write code and solve problems rather than writing documentation for my stuff, because documentation is boring. That's not an excuse, though.

 

This can be reasonable, depending on task/scope. For smaller or simpler games, for example.

 

I wouldn't say my usecase requires something unique, but where the benefits really shine are in the personal workflow improvements and also not having to deal with a good deal of a decade of engine cruft. For instance, having direct access to the very basis of the engine itself, but specifically coupled with the intimate familiarity that comes with having written most of the core components (there's some other bits in there, like XML parses and whatnot, that it was better to use existing solutions for), allows me to know exactly where I'm working from and what I'm working towards.

I also don't need a terribly huge amount of some more advanced features. The renderer is kept very bare bones but uses something a little analogous to the SRP system in Unity, but because I'm not trying to be all things to everyone, I'm able to focus on extending it in ways that suit me specifically. This isn't really meant to be a general purpose engine, but an engine that fits a more narrow set of expectations.

Like, I'm not out here making Fallout 4 or Final Fantasy XIV or big broad projects. Most of the stuff I make is entirely solo dev work, and the parts where other people are brought on board usually involves asset creation. Going for a more personally sculpted, lean solution allows me to target my goals of high performance, ease of use, and also Windows XP 32 bit compatibility because that seemed like a goofy idea.

 

Oy! Merry Christmas superpig dude. And to everyone too.

 

It is so depressing reading posts like this. Years of hearing we are working on it and not seeing much forward movement makes me question my loyalty to Unity.

 

This. So much of this.

A thing isn't finished until it's documented.

Also, so much of this!

About a week before the new input system went to 1.0 (or from preview to not preview, or something) I spent a day converting a large project over to use the new system, then writing up a big, chunky feedback post to the developers, on these boards where they had specifically asked for such feedback.

A major point in the feedback was (paraphrased) "the documentation needs work in these particular areas", and the developers specifically responded to that saying (also paraphrased) "we know, we're getting to it soon". About a week later the version changed, and last I checked (a while after that) the documentation was still the same.

Teething issues aside, the new system is much better than the old and is a no-brainer replacement in any new projects... as long as you know how to use it. But t's got terrible documentation which makes that seem far harder than it is. So even though you have a generally good replacement system ready to go and out in the wild, your user base is getting fragmented between two different official systems in large part because... what... everyone thought someone else would do the documentation?

It's probably a two day job to make some decent "getting started" examples for other common scenarios that would make things easier for almost anyone who wants to try it out. Why does Unity not consider that a core part of a version 1.0 product?




On a separate but closely related note... I am a little concerned when I hear about a bigger documentation team. I completely understand that you get tech experts to develop the tech, and writing experts to do the writing. Cool. But the issue with your documentation isn't just one of writing throughput. A critical aspect of tech documentation is that you need to communicate a deep understanding of the tech being documented, and a writer isn't necessarily the best person to do that. They know writing, but they don't necessarily know the specifics of every piece of tech.

A small example of when this isn't done properly is the code example that the Unity docs had for Mathf.Lerp for years. It showed Mathf.Lerp being used as a "move towards" function with Time.deltaTime as the interpolation factor. That "works", but is incredibly misleading about what what it does or typical use cases. It lead to many people misunderstanding what it was most useful for, and plenty of forum quesitons about things such as target positions never being reached, or how it worked as expected on one computer but not another (because it's not frame rate independent).

And it would have taken one developer who knew what they were doing 5 minutes to write out a better example.

The upshot of all of that is that your first pass documentation should be written by the designers of the thing being documented. The writers should take it from there to make it consistent, professional, reader-friendly and so on. But the guts of the info, use cases, and examples all need to come from the developers.

 

This seems like a fantastic idea!
@AskCarol: can you please pass it along to someone who can make this happen? I didn't know who best to tag on this, but I hope you can help us out on this.