Search Unity

Hello from the Documentation team! We’ve had an incredible year in 2016, and we want to show you some of the changes we’ve made, both to the documentation itself and also to our own processes. We hope this will give you some idea of the thought and planning that is going into making the Unity documentation bigger and better than ever!

Developing the team

The Documentation team more than doubled in size this year. In December 2015 the Documentation team was three people: two technical writers with programming backgrounds, and one technical writer with an editing background. In December 2016 the Documentation team is seven people: one team lead/project manager, three technical writers with programming backgrounds, two technical writers with editing backgrounds, and one tools engineer.

Developing the Documentation

Content published at release date

The number of new Unity features and updates documented at release date has more than doubled:

  • Last year: 5.3 (8th December 2015): 28 new Editor features and updates published by the date of the 5.3 release. We were still adding 5.3 content in May 2016 (25 additional updates were added after the 5.3 release).
  • This year: 5.5 (30th November 2016): 69 new Editor features and updates were published by the date of the 5.5 release. Nice.

Better orientation and clarity for users

In 2016, we implemented:

  • A Unity release version reference on the documentation.
  • A link to the Unity Issue Tracker, so that if a feature is not working as described in the documentation, users can check whether it is a known issue.
  • Prominent links to other sources of user information on all top-level pages of the User manual.
  • A 404 page that provides context and meaning to the error.
  • Rearrangement of many User Manual sections.
  • Unity Services documentation incorporated into the User Manual
  • Versioning of each publication of the documentation.
  • Documentation version switching information is available to users in the User Manual.

Documentation of Unity full public beta releases

Previously: Beta versions were released to a private group, and there was only one public version of Unity at a time – which meant we had the whole duration of the beta period to prepare documentation.

Now: Beta releases are public, and therefore require documentation. However, features can change during the beta process, and there is not enough time to get ever-changing new feature documentation through the editing process ready for beta release. To facilitate documenting features in beta, we are trialling a “documentation in beta” approach for the Unity 5.6 beta release (we’ll see how that goes!).

Developing our processes

A standardized process for developing User Manual content

Previously: There was no technical writing or editorial process.

Now: All User Manual content goes through a multi-stage technical writing and editorial process:

  • We receive information from a Unity developer
  • We read the information, and talk with the developer to learn about anything that is unclear or missing. This is called “developmental editing”. It’s our job to advocate for the user, so we always try to provide as much information as possible, even about things that experienced developers would find obvious.
  • After some back-and-forth, the developer approves our revisions, and the document goes to another member of the Documentation team for a first proofread.
  • The document is loaded into our CMS as a draft page.
  • The document is checked once more by a different member of the Documentation team, then approved for publish.

Our process ensures that every new page is proofread by at least two people, and that the documentation is as clear as possible for our users.

A Unity-wide house style guide

Previously: There were almost no terminology and style standards, and a large amount of inconsistency across the documentation.

Now: Unity has a house style guide, ensuring that we have a consistent voice and use consistent terms across Documentation, Education, R&D Content, and Support. The style guide currently has over 250 entries. In particular, this helps us ensure that what is written in the documentation matches what appears in the Editor, and that what you read in other areas of Unity (like the Education materials and the Knowledge Base) matches what you read in the documentation!

For example: The Inspector window (menu: Window > Inspector) is always referred to as “the Inspector window”, not the Inspector panel, or the Inspector tab.

Documentation ownership

Previously: There was no technical writing or editorial process, and no ownership of the documentation. Anyone working at Unity could add content to the documentation, and it was published live to our users with no checking or proofreading.

Now: Our CMS has been updated to ensure that, while any developer at Unity can still make changes to the documentation, none of it can be published until the Documentation team has reviewed it. This helps us make sure that the information is clear and that the terminology meets our standards. At a company like Unity, with developers all over the world speaking dozens of different languages, this is essential to ensure clarity and consistency!

Coordination with all Unity teams who create documentation

Previously: Collaboration between teams was limited by resources.

Now: In designing and planning our new processes, we have ensured that all of Unity’s content-producing teams (R&D Content, Education, Services, and Support) are involved, so we can deliver consistent, clear documentation to our users.

Since 8th December 2015 we have released 31 online documentation publications, many of those multiple version publishes (such as 5.3, 5.4 & 5.5b).

Great! So… job done, then?

Far from it. We know as well as you do that the existing documentation remains imperfect. There are 1,200 User Manual pages and 10,000 Scripting Reference (API documentation) pages per Unity version (so, for example, 11,200 pages each for 5.3, 5.4, 5.5, and 5.6). Much of this content stems from earlier times, when Unity was smaller and there was no ownership of the documentation, so there are holes, errors, outdated information, and occasionally just empty Scripting Reference (API documentation) pages.

The major hurdle to any progression is our existing tools, which are slow and don’t allow for an easy editing process. These tools are from a different era of Unity, when we released new versions less frequently and when new features were fewer in number. We have a plan to address this, though, and while it’s too early to go into any detail about it , we can assure you that we’re doing everything we can to make documentation faster, smoother and easier.

All in all, it’s been an amazing year, and we hope to achieve even more in 2017. We are so incredibly grateful for the support of the Unity community; we see your kind tweets and forum posts, and it’s a constant reminder of why we’re doing this work. Stay tuned – we hope to have even more to show you next year!

40 Comments

Subscribe to comments

Comments are closed.

  1. I love you documentation team! keep up the great work and best of luck with the new team :)

  2. Is there some sort of CMS plugin / functionality within Unity ??

  3. How to write blog for our game website. http://bit.ly/2lOLtaC

  4. Where’s that offline PDF version people have asked for?… Bueller? Bueller? :)

  5. Hi,

    We are still badly missing users contributions like in php.net

    There is so much knowledge and expertize within the community that it’s a shame there is no tools for sharing it in a convenient way.

    Bye,

    Jean

    Bye,

    Jean

  6. Great to get some insight on the process. I’m really impressed to read how small the team was (and kind of still is) for the quality you provided and are providing. I really appreciate the work you put in there, it makes developing with unity a lot easier!

    Apparently everybody posts their wishes here, I too have a wish that does not really fit anywhere else. I’m using the offline documentation quite a lot to access information without being dependent on a fast internet connection. There is just this annoying problem of not being able to copy paste the url to reference to the website documentation. Any chance you could add a permalink to every page (for the offline documentation)?

    Cheers and thanks a lot for your awesome work!

  7. Dear Unity Documentation Team,
    Thank so much for the full public beta Documentation!
    Example: “WhatsNew54” section and “SwitchingDocumentationVersions.html”

    Same feedbacks: I think what is missing and important is user examples in the Scripting API section down after the official explanation with up and down votes. And link to Unity video tutorial as mention before.
    [draft example: http://php.net/manual/en/language.operators.arithmetic.php%5D

    for example look here:
    https://docs.unity3d.com/540/Documentation/ScriptReference/Events.PersistentListenerMode.Bool.html
    there is no so useful information. Is missing an example an what is a bool. For a beginner especially if is not ENG.

    Missing:
    I have done my personal Unity manual. I wish to share it with you so that you can understand a different structure for the manual. List structure

    To have an idea of how is made here it is same examples:
    for example a complite list of all ATTRIBUTES: and what they do
    [System.Serializable]
    [Range(0,1)]
    [Space(10)]
    [Tooltip(“Explanation”)]
    [Header(“Title”)]
    [StringClamp(15)]
    [RequiredField]
    [ExecuteIn…]

    Is hard to find all the existing [attributes] and are they included into the beta or final documentation?

    or for example a list of all common VARIABLES for a beginner, and what they do:
    bool, int, float, Vector2 3, Color, enum, dictionary, Texture2D, GameObject, etc…

    a complete list of all var Type and what they do:
    private, public, static, abstract, etc…

    list of all forms of communication between scripts, and how to do [the video are grate]

    And in the scripting API section is missing feedback button for each page so that we can send message if there are missing or spelling problems.

    I personally like also kind of manual where there is one long page with ALL THE UNIT FUNCTIONS. One function in each line and a short compact explanation (and link to the api). So that we can study or investigate. This is like a compact dictionary book. In this way, we can look to the compleat list faster and have a draft idea of what we can do. In bold or special colour the new ones.

    Thanks so far for the work done!!

  8. Jashan Chittesh

    January 31, 2017 at 1:47 pm

    I just saw this recent blog posting and while I know I should actually file a bug report (and will probably do when I open up Unity 5.6 the next time), there’s an issue with Unity’s documentation that has been fairly annoying in more recent times:

    Unity has a local / offline documentation, and this is also linked through the little Manual/Question Mark icon in the inspector and also, of course, from the menu. And … as the name implies, it works offline, which is awesome (believe it or not, we sometimes have Internet disconnects).

    In the past, this worked flawlessly (at least on Mac which I used back then). But recently (or maybe just on Windows), there is something that causes the page load times of those local pages to skyrocket. I’m talking of waiting about half a minute (maybe a little less, maybe quite a bit more) until I get to see the actual page – and this happens on every single entry, and with every browser I have tried (IE, Firefox, Chrome).

    It basically makes the offline/local documentation completely useless … so please avoid fancy stuff like external fonts or things that simply break the local documentation.

  9. Please add a types column to the script reference.
    Been asking for a long time.

  10. Sorry for unrelated.
    Unity Automatic Graphic API don’t work truly on some Android Devices specially android 4.4.2 and lower.
    can’t detect true supported API.
    https://forum.unity3d.com/threads/force-opengl-es-3-0-causes-startup-crash-on-s3.266477/

  11. I have reported many docs bugs but some obvious ones are still slipping through the net –
    I keep seeing functions in the docs that are missing their definitions at the top of their help page – e.g. https://docs.unity3d.com/ScriptReference/Graphics.DrawTexture.html

    Would have thought such things were automatically generated

  12. Hi!

    This is great. If you have some list of stuff where the documentation is lacking, please add shaders to the list.

    The documentation has basic info, but when you want to go more deeper, then you are out of luck – stuff like different passes (incl terrain), about srgb conversion (whether the output color is converted correctly back to srgb or not – because it doesn’t seem so), how to combine using geometry shaders with deferred shading, all the undocumented ambient lightning/attentuation functions, etc.

  13. Great documentation has been one of my favorite parts of unity.

    Really excited to see this note:
    A link to the Unity Issue Tracker, so that if a feature is not working as described in the documentation, users can check whether it is a known issue.

    I’m hoping that the link will be per feature so say I’m looking at image effects It brings me directly to that pre-filtered list.

    Also it would be great if the link dynamically highlighted if there are any open issues. E.g. RED when there are one or more issues, green when there are none. (save time from clicking)

  14. Firstly, I created three animations from unity.
    Then build it using WebGL.
    I am able to merge it in existing web application, but

    I need to change those animations on button click and each time load new animation made from unity.

    Now, I would like to know:

    Is it possible to dynamically change single canvas and Module on button click using javascript ?
    If so, I would like to know how it can be done ?

    I tried it but I am getting error as :

    An error occurred running the Unity content on this page. See your browser’s JavaScript console for more info. The error was:Uncaught TypeError: Module.printErr is not a function

    An error occurred running the Unity content on this page. See your browser’s JavaScript console for more info. The error was:Uncaught TypeError: Cannot read property ‘apply’ of undefined

  15. That’s great. All is great. Something like new Features and Changes (special page linked to relevant documentation) will help us to track the path quickly. THANK YOU
    I hope will have time to write good book about Unity programming basics. I used unity for many years and haven’t found good book for beginners…

  16. Alkis Tsapanidis

    January 27, 2017 at 3:28 pm

    Another feature that would be rather lovely, would be having the inter-version links (ie. “Version: 5.5 (switch to 5.6b)”) were links to the current page on the version we are switching to, if that is available.

    As it stands, switching between API versions is awkward enough that I always do it by manually editing the URL.

    1. Hi Alkis! I totally agree. This is something we’ve been stuck on for a long time. The limited tools I mentioned in this blog post are the primary factor preventing us from implementing a smooth version switcher – they make tasks like this much harder than they should be – but it’s a point of irritation for all of us here, and we’re working on a couple of different ways to get it up and running. I hope that helps – and thanks so much for your feedback!

  17. Alkis Tsapanidis

    January 27, 2017 at 3:25 pm

    One thing that I would love to see would be an errata page about mistakes that have been fixed in the documentation. That would be useful for bringing the community up to speed when *very* long standing mistakes in the documentation are fixed.

    One such example is that the callback order page stated that yielding WaitForFixedUpdate returns after FixedUpdate and before the physics step. That is incorrect and was fixed in the current version of the documentation for 5.5.

    The problem is, this has been misdocumented for years and many Unity versions and has stemmed threads, questions etc. Anyone looking at the documentation for a previous version of Unity will get the wrong information. Anyone that already has seen that information will not necessarily re-read that page to get the correct information.

    When mistakes are fixed, you need a way of letting the developer base know.

  18. It would be great if the manual and class reference were available in PDF form.

  19. Robert Cummings

    January 27, 2017 at 1:14 pm

    Hi Docs team!

    My main issue with documentation is that it’s dumbed down for noobs (for want of a better term), and we need high quality information. What it does under the hood. Performance considerations. Tech stuff that really matters.

    If the docs can have an Advanced rollout or similar for each function, with detail and techy info, then you’ll allow people to do more with Unity which results in more people using Unity.

    1. Hi Robert,

      We’re aware of this lack in the User Manual and we’re trying to tip the balance a bit more so that Advanced and Beginner users are catered for equally. Did you see this section that was added very recently?

      https://docs.unity3d.com/Manual/BestPracticeUnderstandingPerformanceInUnity.html

  20. That’s great, thanks for the amazing improvements:
    The only thing I wish existed was to have the documentation integrated more firmly within the Unity Editor. Yes, there is the cogwheel button that brings up the documentation for a component, but it would be even nicer to right-click any input field, slider, UI element in the inspector and jump directly to the related documentation (It’s like that in Cinema4D).
    Best, Claus

    1. Hi Claus,

      Thanks for the suggestion! We recently had a look at a number of other product’s documentation features to see what we could do better, but we didn’t spot this. It sounds like a great idea.

      I’m adding it to our list!

    2. Holy crap yes! So many times I find myself wishing this was a feature, especially with UI components and image effects, among other things.

  21. “we can assure you that we’re doing everything we can to make documentation faster, smoother and easier”

    It’s just that there a bug report from months ago do to with improving exactly that.. I’ll point it out here https://forum.unity3d.com/threads/documentation-of-new-api-still-vastly-underdeveloped.442566/#post-2866382 and here https://forum.unity3d.com/threads/local-documentation-bug.434815/ its been pointed out other places aswel… simple fix reduces offline doc loading in IE (because like fk implementing an option inside of unity to both have it use another browser path for help icon to use (so it doesn’t use default system browser) or the default documentation install path) so this bug causes opening the doc pages in IE to take ~30s.. anyway I’ve given up waiting and have just made changes myself to the all ~16k files that have that broken script url, and just symlink’ing this edited doc folder to the new unity install path everytime I install a new beta update, then I don’t bother installing the offline doc package because it doesn’t seem to change much between beta versions anyway and there is no easy way to see what changes have been made…

    Personally I couldn’t think of a better documentation system than the one PHP doc team uses.

    “https://docs.unity3d.com/Manual/WhatsNew55.html”
    its just a link to the friggin messy release notes page.. this is not easy to keep up with latest improvements taking place with the api with unity and the relative doc pages for these changes and improvements.. unless you’re paying attention to the beta boards.

    php ..
    http://php.net/manual/en/doc.changelog.php
    …an actual links directly doc pages for new added api etc…

    and again php has user submitted comments on its doc pages .. going back years.. with script examples and useful information.. it should be a highest priority imo to have that sort of help page system.

  22. Please also support the Scripting API feature to the scripts in the docs. You already use/have it on the forums.
    See https://www.youtube.com/watch?v=2bXDuYP84i8

    For example a script mentioned in the docs is:
    https://docs.unity3d.com/Manual/VariablesAndTheInspector.html
    Would be nice if you could click on any API element and jump to the scripting reference just like in the above video.

  23. This pleases me.

  24. Bryan Livingston

    January 26, 2017 at 7:57 pm

    It’d be nice if the doc team could get on the ball and add more tooltips to the inspector so we didn’t have to go to the docs so much to see what a field does.

    I tried pushing a pull request for the UI for this but was blown off with a “We’d need to internationalize it” excuse.

    1. Hi, Brian! I’m from the Unity Docs team. Tooltips are definitely on our radar at the moment. Historically, the Docs team’s role has focused solely on the User Manual and Script Ref, but we’re now in a much better position to take an active role in supporting the UI/UX teams and improving in-editor information as well. Getting the process right is an ongoing mission, but I hope this provides some reassurance – we’re working on it!

  25. I love this blog post. I work closely with the docs team at my day job, so I know a bit about the effort and hurdles and pain it takes to maintain documentation on software. It’s not easy, and for as imperfect/incomplete the Unity docs may be right now, I can only imagine how tough it’s been to get to where it is even at this point.

    Definitely looking forward to those future improvements, and I’m glad documentation is getting some much-needed attention.

  26. Would be great if you did this:

    https://feedback.unity3d.com/suggestions/allow-users-to-add-script-examples-to-documentation-and-add-user-contributed-notes

    Allow people to add their own knowledge and examples in. Would really make your documentation site invaluable.

    1. I’d second this, but only if it would be reviewed by a unity developer. The risk is that bad practices will flood the documentation (and get up-voted because “it works”)

    2. This sounds great!

    3. I’m also a huge fan of this.

      There are many hidden gotchas and non-obvious things in any engine, and being able to document these is very valuable. I would have written about 100 of these in the Asset Bundle documentation as I discovered them, but instead other users had to wait nearly a year for Ian to write his Asset Bundle guidelines which contain a lot of what I discovered (much of it sent to Ian). I don’t think it’s reasonable for the Unity documentation team to catch all of these types of issues, as they rely heavily on developers telling them about them, and in this particular case I think a lot of them were first discovered in the field and unknown to the developers who wrote the code, since they were heavily relying on systems they likely did not write to work (WWW, android file system, iOS file handle limits due to non-posix implementation, etc).

      I also think these comments should be reviewed and approved by the documentation team in some form, but possibly viewable/votable/discussable by users before that in an ‘unapproved’ area. This would integrate much of the forum information into a place where it is regularly reviewed and revised, updated or removed when versions change, etc. Right now, much of the information on the forums is out of date or just wrong, but it’s still an invaluable resource – so integrating that better into the documentation in a way that the valuable information bubbles up seems like a win to me.

    4. Hi, Bill. I’m from the Unity Docs team. This suggestion comes up regularly, and there was a thread on our forum about this a couple of months ago. Read my reply here for more information about our position on this.

      https://forum.unity3d.com/threads/make-unity-documentation-public-comment-section.395553/page-3#post-2582587

      The feedback system described in that post has been prototyped and is functional. You can see a video of it here: https://www.youtube.com/watch?v=kr-PeG909pk

      However because it was developed during a hackweek, it’s not ready yet. It needs a more robust and secure back-end which can cope with the amount of use it would get as a result of our approx. 300,000 page hits per day. This is something we’re trying to schedule in.

    5. This sounds like it could go downhill REALLY fast

    6. I think this is a must have.
      it’s like Wikipedia, no matter how many paid writers you put, you can’t match the power of million users.
      if you want something to scale, you have to allow users to add comments , notes , allow users to rate the documentation page & tag things as inaccurate or outdated.
      – this way, the doc team can quickly review the pages that are tagged as outdated.

      @PHILSA
      regarding bad advice or bad examples, it can be easily solved using a rating system for the comments (like the unity questions & answers page or like reddit)

    7. I strongly agree that the docs need user contributions. I don’t think the internal docs team can realistically address an appreciable amount of the issues with the documentation in any reasonable time frame. There’s just too much missing. Give us a user contribution or discussion section on each page with votes.