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

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.

 

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.

 

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.

 

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.

 

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

 

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.

 

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.

 

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.

 

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.

 

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

 

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.

 

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

 

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.

 

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.

 

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.

 

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.

 

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.

 

THIS UNITY!!!

 

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)

 

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.

 

I disagree in principle. 100% is too much to ask of anything, but I do think they should be able to consistently hit >95%.

Right, as is engine development in general. And despite flaws I think they generally do a decent job with that.

The reality is that they have a bunch of different competing sets of work (feature development and documentation being the key ones here, but QA would be another big one) and they need to pick priorities with regard to how much each one gets. At the moment I think they could benefit significantly from redirecting some effort from feature development and adding it to documentation.

I know that the gut reaction from many people is "no, give me the good stuff and I'll figure out how to use it". But figuring out how to use it in the face of incomplete or poorly thought out documentation both wastes time and damages the practical utility of those tools, and "unknown unknowns" mean that some of it just gets outright wasted. As an example, there was a thread recently where someone was asking Unity to provide a feature which was already there. In that thread I pointed someone else towards an existing feature that would solve a different problem, they were also unaware it was there. Neither of those people are silly, it's two demonstrations of a bunch of work Unity has done on feature development which were going to waste as a result of failed communications.

Of course that will never be 100% eliminated, but in many cases it's less effort and greater benefit to do better communication about your work than to do more work.

 

We've been getting steadily better tools on a regular basis for 25 years. Not just from Unity, but also from various competitors. As Hippo says this is an endless thing. Depending on your perspective this was either "cracked" by Unity around a decade ago when they made the licenses cheap and accessible to anyone (before that an entry level engine license was a six-figure deal) or it will never be "cracked" because the bar keeps rising.

 

There's the answer.

 

Thank you for the reply! If we come across specific instances I am sure people will report, but I think this thread highlights that there is a serious amount of outdated (or effectively undocumented with no examples) stuff out there, and I cant imagine anybody from the community who is unpaid taking the time to comb through all the docs to highlight this when you have a dedicated team for this who are paid in comparison.

So totally on board with reporting, but this problem goes beyond that and has done for a long, long time.

Does the docs team even have a list of all the out of date and undocumented areas? It often feels as if they do not, and if not that is where I would start addressing this internally.

I appreciate you getting back to us!

 

Thank you @TreyK-47.

I am pleased to read your reply, but given these obvious gaps in the documentation, excuse me for being skeptical. Ultimately, actions speak louder than words.


Can the documentation team perhaps comment here and explain the VR Splashscreen image as I cannot get it to work, and now even the default Unity splash screen is absent? I am not on Pro so cannot even turn it off which has me utterly confused needing a little guidance please.


I made my own logo, made it a Sprite and placed it in the VR Splashscreen Image box and yet it does not appear at all. I also played around with the draw mode, and added my logo again below the Unity one each 2 seconds and nothing. I cannot get any Splash screen logos to appear now as I said even after putting all back to default. Preview seems totally disconnected from what I see in my Oculus Quest.

 

I've been doing this for years, and yes some of them have been fixed. But that's really not the point. We're not asking for individual issues to be fixed. We're asking for the business to have a better fundamental attitude about documentation.

Most importantly: A feature is not "finished" until it is also properly documented. This needs to cover both standard use and also, where relevant, how to extend upon what is provided.

I'm going to find my other thread and quote it in here. See below.

 

Wait... are these writers the same people who make the stuff? Because if they're not then I feel that could be a part of the issue.

I don't expect every programmer to be a technical writer, but they at least need to be directly involved. Because I also do not expect every technical writer to be, say, a graphics programmer capable of making custom stuff based off your SRPs.

 

From a holistic point of view, the documentation shouldn't be the concern of users.

Ever.

It should just be so good, so great, that it's a source of constant inspiration and (therefore) positive publicity and promotion of the Unity engine.

It's a TRIPLE COMPOUNDING negative to put any expectation upon users to contribute to the documentation.

1. If the documentation is below par, the user first must figure out, for themselves:

- what a feature/API is and does, before they can ascertain if it might be suitable for their usage
- discover the optimum ways to use it, and how to incorporate it within other feature/API usage
- find others that have used it to discuss scenarios and issues not experienced in direct usage

Each of the above compound, before they successfully use it, and before we get to the following issues of writing something to fix/fill holes, gaps and gaping chasms in the docs, as they still need to:

2. Recognise that having done the above, they've contextualised the feature/API from a personal, subjective perspective that might have limited transferability and be difficult for other users to personally relate with and to.

3. Find the time to go back to the documentation, or where it should be if it doesn't exist (way too common in Unity), and begin to formulate some opinion on how it could/should be written.

4. Articulate that and send it into a black hole. Users don't get any feedback or confirmation of what they've sent into this blackhole. This, alone is the single most ridiculous aspect of user contribution to the docs in its current form. CC the contribution back to the writer, immediately, Unity... PLEASE!

5. Hope that Unity has read what's sent, and somewhat acts on it, without ever knowing if it ever will be acted upon, and without ever getting any acknowledgement that it's been done.

 

At this point, and considering all that's occurred at Unity the past several years, how slowly and awkwardly everything new has rolled out (meaning there's been more than enough time to document everything, yet is barely documented, at best) it's impossible to conclude anything other than this:

Unity doesn't care about the docs.

Draw your own conclusions on what this means they think about the majority of their users.

 

If some of the engineers I know still work there, I can guarantee their are programmers who care VERY MUCH about the docs. The fact that they have a documentation team at all, shows they do care. The truth is that technical documentation doesn't generate money. It supports the people who have spent money. Every company I've worked at would say docs are important, but at the end of the day the effort will always be pushed off in favor of bug fixes, new features, and marketing. It took literally years before I finally freaked out and issued a minor (tantrum like) ultimatum requesting we cease all feature development and get the entire team to work on docs. I don't see that happening at Unity, because it doesn't make sense for them to do so.

I've spent the past couple days just reading Unity docs and I'm pretty impressed. Yup, there are gaps just like there are engine bugs. I'd say keep reporting the doc problems just like bugs are reported and hope they get resolved. If you know what the missing information is, include it in the report so they can rectify more quickly. That somewhat satisfies an earlier post suggesting more community contribution.

Full disclosure: I'm very biased and tend to always be on the side of doc writers.

 

Two out of three ain't bad, I suppose.

 

Have you been reading the documentation for the various packages too? Or just the base documentation? Because once you step out of the base documentation the quality and quantity takes a nose dive.

You've clearly never worked for the company that is the gold standard for documentation - Microsoft. People constantly mock them but I have never gone into MSDN with a question that it has not answered.

 

The allocation of money and manpower is what determines where the "care" is. Individuals personal convictions
don't matter...

Not right away. In the same way education doesn't generate money. Short-sighted thinking that will be the death of any organization. It is writing off the single most important investment you can make. No point making a tool if you don't show people how to use it.

If Unity relies on its customers to educate each other it is a big gamble. If they invest to educate their customers they will create more.

 

And they're search engine friendly website pages, too... and scroll friendly, and dark mode by default and on and on and on it goes.

 

Fair point. I haven't. Only so much time in the day to read docs for fun before people start judging how I spend my free time.

Totally agreed on the MS point. I have not worked for a company that cares about docs as much as Microsoft. They were my inspiration when I was writing tech docs.

 

You won't find me disagreeing with any of this. I'm betting anyone on the doc, community, and some of the engineering teams will also agree. I passionately believe everything you wrote, but we are in the trenches. The shot callers are not. So maybe not the real truth, but the perceived truth.

 

Yep. I was real disappointed when I saw quality of the "package" docs.

I think QT has higher quality. Or had. At some point.

MSDN.... I don't know. It is mostly okay, but I wouldn't call it stellar.

 

Yep. That's why even though working alone sucks, I still prefer it over a big team. I care about the final product - can't not care. And you know what they say, if you wanna job done right, have to do it yourself.

 

I'd like to elaborate here.

I had a chance of using visual studio before Community Edition and Visual Studio Express became a thing. That's early 2000s.

Back then you weren't always online, code completion was limited, you couldn't exactly hover over an identifier to see what it is, so a normal mode of operation was what I call "Turbo Pascal Mode", which means that in case of doubt you'd place a cursor on an identifier and press F1 for help, which would hopefully open up a documentation page for this very identifier.

That worked in Delphi, Borland Pascal, and sometimes in Visual Studio which came with MSDN archive. Delphi was the most reliable, because around version 4 and 5 it was lighting fast, and incredibly easy to use due to shortcut keys it utilized. It also pretty much introduce basic identifier lookup. Visual Studio couldn't always resolve the identifier you were aiming at.

Now, back then, the MSDN archive was really thorough and usable, and was pretty close "stellar". However, at some point later, the quality of the archive dropped, Visual Studio Express appeared that didn't really include any help, so the utility of built in help became lower, and at the same time the MSDN archive became of lower quality. Then at some point it switched to using online docks.

Things really changed since, thinking about it. I haven't used "F1 help" in ages, these days you sorta go google things right away, and google lands you at the documentation page.

 

I would agree that it doesn't "generate new income", but in the long term it certainly does "make money" because it consolidates existing income.

In other words, nice docs won't help me make a sale now, but it sure as heck will help to keep customers around if even when they did advanced stuff things went generally smoothly because all the info they needed was right there available for them. Of course that's not the only factor, but it's an important one.

 

Good docs are like ads.
You need to invest first to make them.
You don't earn directly on them.
But it is long term payout and conversion alike. Customer attracted to good docs, will spend more time with using given tools. Just like ads make viewers to eventually buy stuff.

 

From a thread about animator performance. Fully relevant here.

 

Oof...that's hard to read. I'm getting some seriously scary flashbacks: Why WAS Torque3D documentation so poor? The comments in that forum thread killed my spirit for over a month and made me reevaluate my career choices. What's the saying about making your own bed? It was not comfortable.

It might be worth pointing out that the thread title used to be "Why IS...". When there was a full team consensus from top to bottom to deliver on the docs the community asked for, it wasn't a week or two of a couple people. It took months, because once we started pulling on a thread it just unraveled. What folks in this thread are asking for is doable and probably wouldn't be as big of a nightmare as it had been for me.

Unity was brought up more than once in that thread, mostly pointing out its superior documentation and asset pipeline. Very interesting...

Two things I will not do again: Be a dedicated technical writer or manage a community. Both are highly rewarding and I will always respect people who do it, but I couldn't do it again.

 

At the point where I began using Unity the docs were fantastic imho. I barely needed other resources to do what I wanted to do and get started in general. The problem is that that was years ago and the engine is changing faster than the documentation for those new features.

 

But would you consider the current state bad? For projects of similar age and complexity I think Unity docs are still pretty solid, much better than say, Unreal docs. Of course they could improve, and there are plrenty of applications and services with amazing docs, but I think Unity are doing better than par in this regard.

 

I would consider them being split into two completely different ways of docs being bad in itself, and most package docs are very incomplete.

 

Package documentation is quite bad at this point. It is nowhere near the quality of Unity 4 docs and its stellar Surface Shader article, for example.

https://docs.unity3d.com/Manual/SL-SurfaceShaderExamples.html

Another problem is that old documentation does not properly redirect you to the new version of article if you switch version and the search is useless. But those two issues existed for a long time.

While reduced quality of the docs is a new thing.

 

@bgolus is probably the single most valuable provider for information on shaders. It's incredible how much information he's posted over the years. He really does deserve some recognition from UT.

Almost any google search you do on shader problems/questions will end up pointing you to a @bgolus post. It's uncanny. Also, the best thing about his posts... They're actually correct. Every single time.

 

I can confirm that he is extremely knowledgeable.