Missing Details in the Documentation...What is Unity doing?

News & General Discussion
1

As the title says, I am noticing critical missing information in the Unity documentation that if nothing else, I wanted to put on other’s radar including Unity’s but surely they already know.

I posted yesterday about the missing “Virtual Reality Splash Image” which is present in the Splashscreen Player settings in the Engine, but there is no mention of it in the Splashscreen documentation. None. Not like VR is that new to the engine. This is sloppy.

Then yesterday I discovered after a WEEK of fighting with the engine to address all the errors after an export → import scene packages into a fresh project, that my many layers did not make it over. Searched the forums and learned that I needed to import tags via the Tagmanager file, however a reimport did not address as it looks like I needed to do this “undocumented” step during the first import!!! Not even sure if that is even correct as there is no mention of this in the export packages documentation. WHY NOT? Not like it is a new feature as far as I can tell.

I am not sure how pervasive this issue is throughout the documentation, but my experience working with Unity over the past year as a newbie has been harder than it should have, mostly due to countless avoidable engine issues and documentation issues like these. I shudder to think how many hours I have wasted on issues that just should not be given that Unity is a mature product. It is not just me either as talking to just about any other Unity dev, they feel the exact same way. Just the other day I was watching a YouTuber looking for the Player Settings and watched her get confused when she went to look for it under Edit. This is just flat out sloppy and really adds to the mental load of a newbie in unnecessary ways. This is just one of many examples.

Don’t get me wrong, I am grateful to have access to the engine, appreciate that Unity is adding new features all the time and that this is a very complex environment, but if I am honest, I legit regret choosing Unity which is not something I say lightly. As a small budding VR Dark Ride development studio, my time to market has been negatively impacted far too many times due to my Unity partner not delivering quality. I used to just pass it off as my own lack of experience, but now that I have gotten a feel for the engine, I am asking myself and others, what is going on at Unity? What are all the 3,500 staff members working on? Hopefully an engine refresh which seems to be coming, but when the first thing you read on the roadmap is a Safe Harbor Statement, you cannot help but wonder if that IPO income is going to be squandered. Let’s hope not as we NEED better tools as the market is only growing and demading much more content.

Not looking for a response here from anyone, including Unity as actions speak louder than words. Show us you care about these issues by simply fixing them so others are not getting tangled up in them. Surely Unity can add the missing documentation over the next few weeks. It is to both the developers and Unity’s benefit as the more successful developers are, the more income Unity is going to make. As it stands right now, there are countless developers that simply gave up as they just could not spend the time to fight the engine. That is bad for Unity’s new shareholders.

2 Likes
2

Just about everyone knows. I have been complaining for years and they have done nothing about it.

For many of the packages the comments and code samples are the only way to make sense of them.

3 Likes
3

yeah pretty much the rule is if I have to learn how to do a new thing it is either going to be youtube that teaches me or slow trial and error. it’s very rare that documentation ever saves the day. I’m talking both unity and other engines here.

In the cases that there is documentation and its more than just repeating the name of the thing in reverse order, it usually isn’t useful until after you’ve done a lot of trial and error to figure out how it works. And then it seems so easy its like, how hard is it to write down how this thing works in plain english?

Unreal has a big hero on youtube named Matthew Wadstein. Basically he has taken every node in unreal and explains by example how it works in plain english.

I wonder if such a hero exist for unity? There is a lot of project based tutorials and thats great, but somebody who basically makes a user friendly encyclopedia like Wadstein would be a real hero.

problem I imagine is, there is no money in it.

3 Likes
4

There is YouTube video, which explains every node of Shader Graph. Shader graph huge hero if you want call it. But that does not resolve anything. Still need to understand, what nodes actually does.

But nodes are representing little fraction in comparison to write things by code, which has ton of functions, which nodes won’t ever cover. This is where custom nodes come into play.

Now try find your big Hero in Unreal C++.
I put bet, there is none. However, Unity is flooded with tutorials of various skill levels. Plus C# alone is well documented. I don’t know about Unreal tho.

Putting programing by code and by nodes into same basket doesn’t work.

While Unity doc is far from ideal, it still covers huge range of topics.

Online snippets and git repos are good source of knowledge.

1 Like
5

There’s “Rama”. Or was. I’m not sure if he’s still active, but the guy created plenty of C++ tutorials.

1 Like
6

Much of what you say is perfectly reasonable. And I’m definitely with you on the documentation. 15 years ago Unity used to be better than the competition in that regard. In the mean time that’s changed.

However, on this point specifically…

… this whole page is there because the community wants more information, and when Unity used to provide that without making such statements people kept getting upset at them.

In the early days Unity just talked openly about stuff that they were trying out. Unfortunately, this lead some users to be disappointed / angry / threatening when things changed - which is pretty common in a heavily R&D-based area of software development.

So then Unity stopped telling us about stuff until it was nearly ready, and people got upset about that, too. Partly because “you’ve stopped doing stuff” (they hadn’t, they just stopped talking about it) and partly because “if you’d asked for feedback early you could have made it better” (true, but see earlier).

So they hit on a middle ground of publishing the roadmap and being super duper clear that it contains no promises. And honestly, I think that’s fair. And also, honestly, it changes nothing for me as a developer. If something isn’t in the engine and working now then I am not going to plan it into a project because there’s a whole bunch of risk, of which Unity delivering it is just one part.

4 Likes
7

I don’t know. I agree that if you told a developer to stop doing stuff for a few weeks and just document what’s already there then they could get a whole lot of good stuff written. But surely the issue isn’t that? It has to be organisational.

Just guessing here, but I get the impression that whatever is being done internally to track developer performance doesn’t account for documentation, or at lest doesn’t do it well. If so then any developer who likes their job will be making sure that something works, then moving on to the next thing. Edit: And this stuff isn’t fast to get results once changed, because existing planned work has to get through he pipeline, then the changes can apply to new stuff.

As an example of documentation not being accounted for, a few weeks ago there was a survey put out officially by Unity. One of the questions was about where we go to find out how to use new parts of the engine, and the manual / docs weren’t even listed as an option. I distinctly remember because I made a thread kind of like this one to rant about it at the time. :slight_smile:

4 Likes
8

It’s not often mentioned, but one of the darker patterns of gamification is being used against Unity users.

If it’s initially easier to play a game than it becomes in later stages, and there are prizes at the end (release) and you charge subscription rates and/or offer purchasable player boosts (see the Asset Store, Service Support Packages, Source Access and Staffing), the only thing you need to keep users P[L]AYING is an increasing difficulty curve slightly less than their sunk costs (time, energy, association and money) and the lure of new shiny at key stages.

9

I felt this way too. It reminds me of when you would get docked marks in school for defining a word with the word. Unity does this all the time and I often am more confused from reading the description than I was prior.

I do have to disagree when you said “problem I imagine is, there is no money in it.” There is money in it…for Unity as they make money when developers make money and right now there are countless would be developers giving up who have great ideas but are not able to sift through the noise. I cannot speak to flat screen gaming, but I can tell you the demand for XR titles is way past the supply and that demand is growing at an exponetial rate. It is Zuck’s biggest blind spot and a serious limitation to reaching 100M users and beyond. We need better tools and documentation/videos and whomever can crack it first, is going to make a lot of money. Lets see if Unity can step or of fade away. I hope their new investors are paying attention.

10

I agree. I should have said, “no immediate return that is easily quantified.”

2 Likes
11

They should have open-sourced the documentation a long time ago, with some form of mod approval. Often times I’ve had very useful information I could have added to a page for something I figured out, or a modified code sample that better reflected the method I was using.

1 Like
12

Makes you wonder if a community run documentation website could be a thing.

13

Just pay @Kurt-Dekker and @bgolus a small fortune, and give them two assistants each, and lock them out of the forum for a month with an infinite supply of their favourite caffeinated drinks.

Problem solved.

3 Likes
14

Honestly I think thats it.

You have a few heroes that are doing so much already. Why we need the goofy interns showing up every month with some slapped together survey that doesn’t even make sense. Just hire the heroes, pay them a real salary - there is no risk because we can all already see the work they do for free.

If unity wants to catch up with foliage rendering and performance go hire the awesome studios guy. In some ways the work he has done is better than what unreal has. Only thing seems to get in the way is unitys disjointed render pipeline mess.

1 Like
15

Honestly it’s pretty good, an endless battle though for an engine of this scale. Could use some more code examples, or a trusted wiki entry for each command linked at the bottom of each page so any gaps in Unity’s examples are helped along by community without Unity giving up control of each page.

Code examples do help so very much.

4 Likes
16

I second any idea that gets the community to input. I know I have spoken about this at length before, but I will continue to do so:

Unity will never be able to stay on top of the docs to a 100% standard that everyone wants and needs. Its an uphill battle against a moving target.

Involve the community in a way that lets them add content to docs, and have the docs team approve/deny with requested changes said content.

That really seems like the only way to ever keep pace and make up for all the areas that are lagging behind and completely undocumented, or badly documented.

1 Like
17

The thing is, Unity is a commercial project and not an opensource one. So they SHOULD be able to stay on top of the docs for 100% standard without community help. They certainly have plenty of employees, so could spare a few of them to write more documeentation.

2 Likes
18

THIS UNITY!!!

19

100% agree, but we have both been around here long enough to see that is unfortunately not happening and if anything getting more out of reach. The docs have gotten worse in terms of total content that is documented, compared to back in the day (seems engine is growing too fast for docs team to keep up)

I don’t know what the solution is but it does not seem the current system works very well

I will say that there are some gems in the docs and the team themselves are great and clearly skilled, it’s simply unable to meet the demand / speed required right now

If unity could just quadruple the docs team I imagine they would have by now, and I truly believe it would take at least that to handle things internally (including catching up all the lagging areas etc, not just providing docs for the new stuff as it comes out)

20

I’ve done this. It ultimately went down hill for 3 reasons:

  1. If the result is officially part of the Unity product, you still need dedicated employees overseeing it. I can tell you that one person isn’t enough for this, otherwise they go a little crazy over time.

  2. As the engine changes, you need to perform a regression test on the docs the same way QA performs on engine features. The more docs and the more engine features, the more regression tests you have to go through. Sadly, there isn’t a solid unit test system for docs =(

  3. Eventually, everyone stops writing and maintaining. Your content decays and we are back to posts like this.

I’ve said this so many times before, but it always rings true: “Documentation…everyone wants it, nobody wants to write it, and it will never be finished.” It’s worth all the effort it can get, but it’s the least glamorous and most tedious part of game engine development.

Speaking from professional experience, the most solid solution is to just keep hiring more writers until you have enough monkeys pounding on the keys until you have “complete” docs. Then you keep them around when the engineering team ultimately ruins their day by changing entire swaths of the engine. This is also an uphill struggle, because convincing shotcallers to pour money into an effort like documentation is as difficult as convincing the programmers to write docs. The difference is you can bribe the programmers with drinks at the next GDC as a reward.

Edit - I do not know who or how many people at Unity write the technical documentation. I pass no judgement on what is currently available or missing. Just talking about what I’ve run into in the past.

2 Likes