Search Unity

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:

DocsSuggestFeatureArrow

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:

  1. C# examples and conversion errors (~30%)

  2. Suggestions, spelling corrections and open-ended queries on how to improve the docs (~30%)

  3. Reports of missing links

  4. Feature requests

  5. Spam (~10%)

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 future

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

32 Comments

Subscribe to comments

Comments are closed.

  1. Is there a specific documentation for Unity 5? If yes, where can I get it?

    1. Documentation is included with the Unity 5 beta releases.

      We don’t put it online anywhere yet. Once 5.0 has been officially released, we’ll put the docs up on docs.unity3d.com, just as we’ve done for every past release.

  2. i don’t know if you can do this,
    but i hope u add support for documentation to be visible without leaving the code editor (monodevelop, sharpDevelop, visual studio), i hope you make the documentation visible in a way similar to java, where you can read everything about each function in the explanation popup that is displayed.
    this is far more effecient than moving to a webpage to see the docs.

    1. they would have to add proper code comments to methods and fields, imao not gonna happen

  3. Hi,

    just go for it, and make as a wiki and true collaboration with users.

    “User Contributes Notes” will be the only satisfying solution in my opinion.

    php.net manual is in my opinion a true reflection and appreciation of what a community can bring on the table with “User Contributes Notes”. With moderation and letting people vote up and down comments, so there is NOTHING to loose in making this available.

    http://php.net/manual/en/language.types.array.php

    We should be able to make comments and suggestions in each page, all of this totally transparent and visible to everyone, there is nothing to hide in documentation…

    Reporting bugs for a missing documentation is important, but never going to make a real improvment in the usefulness of the documentation.

    Bye,

    Jean

  4. C# as default? Awesome!! o/!

    Also, give a special attention to Editor Related documentation, is lack of C# examples;

  5. On the topic of documentation.
    It would be really great if Unity could update all forum and answer posts that point to the old unifycommunity dot com site to the http://wiki.unity3d.com/ address instead.

    I realise that these are comments made by the community (and some of them long ago) and not Unity Technologies however it would be possible for someone to buy the old domain and trick users into providing their Unity account details.

  6. Wish you guys would finish all of the Unity 4 milestones before offering Unity 5. I’m still waiting on Unity 4 features that are in beta. Does this mean outstanding Unity 5 features will arrive when a new Unity 6 preorder surfaces? I really don’t like this refocusing trend.

  7. Awesome, would love to get some information about possible Exceptions when calling methods, sometimes I get C++ errors that make no sense and trying to Debug those are very hard to do. Knowing what could potentially go wrong with a method given bad data would help debugging.

  8. Damn! I missed that feature the whole month? There’s far too many times that I get to a badly documented page with no examples or even explanation on how a method or property works.

  9. This is a really good idea. I find a lot of the examples and code snippets not very helpful to a newbie, when explaining how you can use it.

    Giving real examples and actually explaining what and how you can change the parameters in a line of code, would help out a lot when trying to find your own solution.

  10. Unity is CommUnity. Unity’s greatest asset is it’s community. The direct input from the community has shaped Unity into the product it is today. This is how Unity becomes successful. I hope this feature finds it’s way back into the docs soon. And thanks for the post.

    As for the c# vs unityscript argument, I thought that was settled a few blogs posts back? :-P

    1. “Unity is CommUnity” – I like that :)

      Correct, and as many of the other comments to this post also points out, as well as the feedback we get specifically on the documentation (even without the “Suggest a change” feature enabled), we see a big interest from you in the community for the documentation, and we are looking at ways to involve the community in improving our documentation. Right now focus however is shipping a great Unity 5, and then we’ll find out how to open the docs for community contributions.

      -Rasmus, Unity Infrastructure Team

  11. Please keep this feature on.
    I think you’ll save time fixing docs and user will learn faster.

    I’ve noticed some issues in the past with docs not compiling.

    Have you thought about adding other community features?
    I’d love unity to integrate more with the open source movement. A way for users to push to the asset store via a repository on github would be awesome.
    Who says you always have to pay for good code :P

  12. Glad unity is adding systems to improve the docs. unity docs are already some of the best out there but it is annoying to find java code and have to convert it over manually. one thing that would be nice is if we had access to the code converter as well. i know tutorial guys would prolly like to give example code in both languages. as well as java coders trying to understand c# would benefit.

  13. We should rather allow the documentation to be changed by the community.

    Allow us to make any changes/corrections, which can then be approved by a documentation manager of some sort. This will make it far more extensive, and allow us to share our thoughts and insights and experiences.

  14. Nice analysis on feedback. What about making “Suggest a change” permanent option for all documentation pages? It would give long term feedback with much stronger arguments.

    Talking about long term documentation I think making it with “wiki” principals would be really nice approach. In that case developers would be able to suggest directly their version of changes and articles would get more likely updated all the time.

  15. UnityScript all the way for me! I suspect big shops favor C#, but as a one-man team, my Web background makes UnityScript perfect.

    1. No it doesn’t

      1. Don’t be a troll, not everybody likes the extra syntax or c#

        1. True, just like some people don’t life pizza or ice cream…

        2. no, no, this discussion definitely belongs here –
          Web background has absolutely nothing to do with Unityscript except for very small overlap in syntax, which can be often even misleading
          any former web developer thinking that Unityscript will somehow ease the development in Unity is sadly mistaken

        3. I suggest that we integrate the Malbolge programming language into Unity.

    2. I agree. I came to Unity from a Flash, Art, and Web Design background so I’m very comfortable with JavaScript. I’m sure C# has better performance but I’m glad we have the option to use both. I think that kind of choice and openness is part of what makes Unity so accessible.

    3. Both C# and Unity script are important.
      I came from as and started with unity script. A couple months later I changed to c# as I liked the benefits of the language.
      Unity script is important to keep as it keeps new users happy and is great for rapid development.
      C# is important due to its features that unityscript doesn’t have.
      Unfortunalty it’s not worthwhile to keep the standard assets up to date in both languages so some people will be upset. The best thing unity can do is keep the scripts encapsulated so you don’t have compilation script orders issues which unity have done pretty well so far on their assets.

      1. C# and Visual Studio’s intellisense makes developing in C# far more efficient than using UnityScript, which has no decent intellisense support.

        Add in Resharper and your productivity is easily 50% – 100% more than anything you’d ever get with UnityScript. So for all these people who think UnityScript in some kind of weird strange way is ‘faster’ or ‘quicker to learn’ than C# has no idea.

    4. Sorry but the stats show only 18% or less people actually use Unity Script. Everyone (small and big alike) prefers C#.

      This is because C# is better and it’s less typing once you start using it’s extended features that Unity script can’t actually do.

      I shipped 3 titles using Unity Script. I moved to C# and all my fears and issues vanished within a week and my code is faster, leaner and more intelligently designed.

      Please do try.

  16. I think the switch to C# as the default is a GREAT move. There’s nothing that annoys me more than getting a client project that someone else worked on first and it’s in UnityScript. Since the code samples on the web and the code completion for C# is far superior it just makes it very difficult to work on a project who’s code is all in UnityScript. This will likely cause most newcomers to start off with C#. Thanks! :)

  17. First!! :D Well… I think this is awesome! I always read and use the unity documentation and I do notice at times that some of the documentation is unclear but… I deal with it just because Unity is awesome sauce. :)