We have been getting requests from users who want to feedback on Unity documentation more easily. So we did an experiment to see how it could work.
In order to get an idea of what kind of feedback we can get from the community, we enabled a “Suggest a Change” function on the documentation site, directly on the page you want to comment on. The feature was enabled for the whole month of August and looked like this:
We wanted to see what kind of feedback we would receive and how we can best address it. During August, we got approx. 500 suggestions this way. These were the most common topics:
C# examples and conversion errors (~30%)
Suggestions, spelling corrections and open-ended queries on how to improve the docs (~30%)
Reports of missing links
C# examples and eliminating conversion errors
The most common feedback we received related to missing C# examples in the Scripting API documentation. As you can see in the blog post on Unity’s scripting languages, we have kept an eye on stats for scripting language usage. Given that the majority of our users use C# and that our internal tooling support for for UnityScript lacked some features, we decided that for Unity 5 documentation:
C# will be the default language internally for code samples in the documentation
We’ll develop a new C#-to-UnityScript converter, which preserves code-comments during conversion (another of the major complaints about our code samples) and solves other issues with the old converter.
You will also notice that our Learn Team uses C# for the new Sample Assets, which will replace Standard Packages in Unity 5. We believe that moving to C#, combined with the new tooling support, will result in higher quality documentation. All we want is to provide you with valuable and useful code samples you can use in your projects.
No more broken links
For Unity 4.5 documentation, we introduced automated link-validation, although given the number of broken links (~100) for 4.5, it simply reports the broken links internally as part of the build. Our goal for Unity 5 is to reduce the number of broken internal links, and eventually drive that number down to zero, at which point we can have a process internally that makes sure broken links no longer get introduced by accident.
The feedback we got from the one month trial of our “Suggest a change” feature was valuable and really showed us the huge interest there is in the community in helping to improve our documentation. Right now, we’re considering how to enable this in the future. We will most likely reintroduce the “Suggest a change” feature at a later point, in one form or another.
The Documentation and Infrastructure Teams