Feedback: Surveys ignoring documentation

I'll tag @UnityMaru as I don't know who's most appropriate for this.

I was recently invited to fill in the "Unity Operate Solutions" survey via the new Pulse thing. There's a question in there which stood out to me as being, frankly, terrible:

The issue was with the set of answers available there. It had the blog, forums, external news sources... what it didn't have was your own documentation.

This is concerning for two reasons:
1. It's a badly designed question which will give you skewed data. You forced me to select something that isn't my primary source of information, so you collected incorrect data from me. How many others is that also true for?

2. It reinforces the idea that you don't value your own documentation. I mean, you didn't even consider it as a place that people might want to go for information. It's hard to imagine it being properly factored into planning or resource allocation.

To the contrary, for everyone past the point of needing tutorials you should be making sure that your official docs are the first place we want to go, and the last place we need to go. As an experienced developer already familiar with how your product works, when I'm using a new thing then I shouldn't have to go anywhere other than your manual and your API reference. They should be complete, accurate, digestible and reliable.

That won't happen if you're not taking them seriously.

A feature isn't finished until it's documented. It's not enough that it works, your customers have to be equipped with the knowledge required to use it effectively.

To give credit where it is due, the documentation has indeed got better over the last few years. I am seeing improvements. However, I also see things like this (1) and like this (2). And then you asked me where I get my info from, and didn't even list "Official Documentation" as an option. That's an issue.


1. The official "manual" for TextMesh Pro, which has been an official in-house Unity feature for years now, still points to the 3rd party website from when it was developed as a 3rd party asset. If Unity have properly adopted it then why have they not also integrated it into their own manual?

2. The migration guide from the old input system to the new is mostly just a list of API entries. The few step-by-step sections in there don't address how to implement anything equivalent to the polling-based implementation the old system was based on, despite the fact that if you're migrating a project (as opposed to designing it into a new one) that's almost certainly what you need to be doing. It was near completely useless to me when I migrated my project - feedback which I already provided in detail back when they specifically asked for it during the preview.

 

There should be an "other" field where user can type.

You know, just as a fail safe.