Search Unity

我们知道大部分用户都希望能更容易的反馈关于Unity文档的建议,所以我们做了个实验来看看它是否可行。

为了获悉我们能从社区得到何样的反馈,我们在官方手册页增加了“Suggest a Change”功能。该功能在整个八月期间有效。页面如下:

我们想了解我们能收到一些什么样的反馈以及我们如何用最好的方式来解决它。8月期间,我们通过这种方式收到了大约500条建议。下面是一些常见主题:

  • C#示例及转换错误(约30%)
  • 建议、拼写纠正以及开放的询问如何改进文档(约30%)
  • 链接失效报告
  • 功能需求
  • 垃圾信息(约10%)

C#示例及消除转换错误

我们收到的最常见的反馈就是脚本API文档中缺少C#示例。你可以在 Unity脚本语言这篇博文中看到,我们一直在关注各脚本语言的使用率。鉴于我们大多数的用户都是使用C#语言,而我们为UnityScript提供的内部工具支持还缺少一些功能,所以我们对Unity 5的文档作出了以下决定:

 

C#将作为文档中示例代码的默认语言

我们将会开发一款新的的C#-to-UnityScript转换工具,它将在转换后保留原有代码的注释(我们代码示例的另一个意见集中点),并且解决旧转换器的其它问题。

你可能也注意到,我们的Learn Team在新的示例资源中使用的是C#语言,该资源将在Unity 5中取代先前版本的Standard Packages。我们坚信转向C#然后结合新转换工具的支持,将为用户们提供更高质量的文档。我们所希望的就是为你们提供更有价值更实用的代码示例。

减少失效链接

在Unity4.5的文档中,我们加入了自动链接验证,但鉴于4.5版本中我们收到的失效链接数(约100条)反馈,我们发现它只是在构建中内部报告了失效链接。对于Unity 5,我们的目标是减少无效内部链接的数量,甚至将该数字降至0,关于这点,我们已经制定了一个内部的流程以确保减少失效链接。

展望未来

我们从为期一个月的“Suggest a change”功能中得到的反馈是非常有价值的,我们也从中得知社区中存在大量有兴趣帮助我们改善文档的用户。目前,我们正在考虑未来如何执行它。我们很可能在随后以某种方式重新推出“Suggest a change”功能。

32 评论

订阅评论

评论被关闭。

  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. :)