Unity is a powerful game engine, but that power is not very meaningful if you cannot figure out how to use it. That’s why one of the most important aspects of Unity is its documentation. There are a little over 39,000 distinct symbols in Unity 6’s public API, and that does not include packages; every single one of those symbols needs to be documented, explaining what it is, what it does, and when, why, and how you might want to use it in your project.
While there are plenty of places where Unity’s documentation shines, there are also a great many rough spots. For example, consider EditorUtility.CopySerialized(). Perhaps you can hazard a guess at what it does from the function name, but beyond that, the documentation isn’t much help: “Copy all settings of a Unity Object.” What does that mean? What are the “settings” of a Unity Object, exactly? What does it mean that the function is called “CopySerialized” and not just “Copy”? Where does the copy go? What’s the difference between this function and Object.Instantiate(), which is also about copying an object? Enterprising developers could experiment to figure out the answers, but the point of documentation is that you shouldn’t have to do that.
Still, at least the documentation acknowledges that this function exists. In other cases, you might discover a symbol through code-completion popups in your IDE, or see it mentioned in a code snippet online, and go hunting for information on what it does… only to find that it’s not even listed in the documentation. Is having no docs page better or worse than having a bad one? It’s hard to say - but it doesn’t matter. Either way, it needs to be fixed.
Improving the documentation is a key focus for 2025. To kick off that effort, we recently ran a “Docs Quality Week” to address some of the most critical issues.
Recruiting for ground truth
At the heart of every API documentation page is the ‘ground truth’ information about what the API actually does. It’s easiest - and fastest - for the developer who created the API to provide that information and write the initial documentation when they introduce the API; they have a complete understanding of the purpose, functionality, and edge cases that their code is handling (or at least we’d hope they do!). The developer can then collaborate with the technical writing team to turn that ground truth into finished docs; the writers can ensure that the developer’s ground truth is phrased in a way that is clear and consistent, and they can also prompt the developer for extra details, so that the resulting docs are comprehensive.
That hasn’t always happened, which is how we’ve ended up with API docs that aren’t as clear, consistent, or comprehensive as we’d like; and when the problem is that we’re missing ‘ground truth’ about an API, developer assistance is typically needed to do the detective work on how the API is implemented and fill the gaps in information. At some past Unity hackweeks, we’ve seen the ‘Attack the Docs’ project, where technical writer Siobhan realised that having every developer at the company within walking distance was a great opportunity to get quick answers to questions… but unfortunately, we’ve not been able to get everybody together like that since before the pandemic. Dropping questions into team Slack channels just isn’t the same.
So, for Docs Quality Week, we asked for people across our engineering teams to take the week out from what they’d usually be working on, and focus entirely on improving the API docs instead - even just with bullet points that the writing team could clean up later. By the end of the week, we had seen contributions from around 85 developers and QA engineers, some of whom had never actually had the chance to work on API docs at Unity before.
Phased Prioritization
When we’ve got tens of thousands of symbols in the API, which ones do we look at first? We established two metrics for every documented symbol in the API:
- Impact: how much impact we think improvements to a docs page could have, based on how many views it gets, as well as the star ratings that users have given at the bottom of the page.
- Quality: the current quality of the docs page, based on our internal audit of the docs, the number of open issues filed by users, and automated checks for issues such as broken links or missing code samples.
The metrics got stack-ranked into bands, and then we grouped all the pages into four ‘phases’:
(Table from our internal docs showing the breakdown of the phases. The links in the last column show us tables of the individual pages in each phase.)
The approach is straightforward: prioritize fixing everything in Phase 1 first, then move on to Phase 2, and so on. Phase 1, containing the pages that see the most traffic from our users while also being in the bottom band on our quality metrics, consisted of 156 symbols in the core product, and another 66 in packages, for a total of 222 symbols.
This approach only addresses symbols that already have at least some documentation, rather than those missing documentation entirely. Although fixing missing symbols is also important, we chose to improve only existing docs pages for this effort, partly to keep everyone focused and partly because it’s harder to know how to prioritise the symbols that have no documentation. We’ll get back to the missing symbols in the future.
On your marks, get set… go!
Our team in Tokyo were the first to get going on Monday morning, and other teams in Copenhagen, the UK, Paris, Montreal, and Bellevue joined in as the day started for them as well. I put together a kickoff video for everybody which walked them through how to use the tooling and where to find help.
(Kicking off the week. Regrettably, I forgot to include any memes in the video.)
As people worked through the list of Phase 1 APIs, we started to see a steady stream of questions flowing into the dedicated channel for the week. There were plenty of questions about how to read the information in the phase tables or use the docs tooling, but also many about ‘what good looks like’ for an API - “it looks pretty correct […] Anyone had suggestions about what kind of improvement can I do?” This is where our experienced technical writers were able to provide quick and valuable insight, teaching developers the kinds of questions to prompt themselves with that could draw out more information. “What is this? Why is it useful? When is it needed? What can go wrong? What other APIs or features does it relate to?”
We also saw lots of questions about how to write code samples:
- “How should I approach writing a code sample for
EqualsandGetHashCodemethods?” - “Do code samples need to be complete files that will compile when copied and pasted into a project, or can they just be smaller snippets?”
- “Is it necessary to write a code sample for an abstract base class like
Collider2D?” - “How do we write code samples for static classes which provide a bunch of utility functions like
EditorApplication?”
A key concept that many developers learned was that the way to approach a code sample is not just “write the smallest possible code snippet that uses the symbol.” When documenting AsyncOperation.completed in the API, for example, the minimal code we could show might just be “subscribing a handler to the event”, e.g. we could write a code sample like this:
using UnityEngine;
class Example
{
public void SubscribeToCompleted(AsyncOperation op)
{
op.completed += (_) => Debug.Log("Operation completed");
}
}
This is technically correct code, and it ‘uses’ the symbol, but all that anyone could really learn from this is “what subscribing to an event in C# looks like” - the user most likely already knows that, and if they don’t, the code sample for AsyncOperation.completed is not the place to try and teach them!
Instead, the point of a code example is to show usage of the symbol in a meaningful context - imagining situations where the user might want to actually use the symbol, and then showing the part it plays in that situation. This will sometimes mean showing off use of other symbols in the same example, but often the symbols are related anyway, so it’s appropriate - and the code sample can likely be reused, showing it on the docs page for those other symbols. Check out what AsyncOperation.completed used to look like, and what it looks like now. What do you think?
Some developers also found that working through the documentation resulted in making code changes. The new docs for EditorUtility.CopySerialized() note a couple of non-obvious behaviours about handling of hideFlags and about derived classes that we figured out by reading the implementation, and we realised that we didn’t actually have tests for those behaviours to help ensure we don’t accidentally break them - so we added the tests. In another case, the question of “what is the error behaviour?” led to discovering that UnityEngine.Windows.File.ReadAllBytes() could potentially return garbage data in the array if the actual read of data from disk failed - we’ll get that fixed in an upcoming patch.
And above all else, it was educational. As one developer put it: “I want to say that I find this exercise enlightening! By just picking APIs by importance instead of levels of comfort, I’m learning a ton of (strangely) useful stuff.”
The final numbers
On Friday afternoon as we wrapped up the week, we took a look at our progress:
- We’d started with 222 symbols in our Phase 1 group; devs had picked up 145 of them, or 65%. In many cases, devs were also cleaning up other related symbols (e.g. other methods in the same class) even if they weren’t part of Phase 1, because it’s often simpler to address multiple related pages at the same time.
- A total of 194 ‘docs week’-tagged pull requests had been created, 65 of which had already been merged by the end of the week. Most pull requests touched multiple symbols, and all of them were reviewed by technical writers to ensure the writing aligned with our style guide, the format was correct, and everything met our documentation standards.
- We resolved around 145 feedback reports submitted through the “Report a problem” link at the bottom of documentation pages. These reports highlight unclear explanations, missing examples, or incorrect information that you encountered while trying to use the API, so when we address them, we know we’re solving problems that you actually ran into.
On the one hand, that’s nearly two-thirds of our “popular worst” pages either improved or with improvements now in flight - we’re thrilled to see that, and we hope you are too! Many improvements are already live today in the 6.1 Alpha documentation; others will be published over the next few weeks as people land their remaining pull requests and release new versions of packages. The numbers from the end of the week are already out of date when it comes to the full impact of what people did.
On the other hand, with about 85 developers contributing, that’s an average of a little under two symbols per developer improved in 5 days’ worth of work. Seems a bit low! Some of this is explained by the fact many developers were not participating full-time - some only joined part-way through the week, and most developers still had regular development tasks to do, like reviewing pull requests, attending standup meetings, etc. Also, as noted, this was the first time many of the developers were being asked to write API docs to the level of quality that we consider acceptable, so there was a bit of a learning curve.
The week also showed us a decent number of opportunities for improvements in our tooling, to make it easier for developers to actually find out the quality of the docs that they own and make it easier for them to make changes. Although we use the C# standard for API documentation (XML documentation comments) in packages, we use an older, more awkward-to-work-with approach for the core product. It’s long been a desire to migrate the core product over to XML documentation comments as well, and it looks like we’ll be getting that done in the next couple of months. As we solve these problems, we’ll make it easier for teams to push on the docs on a regular basis.
Onward to 2025
This week served as a good pilot for driving API documentation improvements in 2025. We trained up a bunch of our developers on how to write better API docs, got clarity on how we can make the experience of working with docs at Unity easier, and made a bit of a dent in some of our lowest-quality, most-impactful pages. There’s still much, much more to do, and we intend to get a lot of it done next year - not just with another ‘Docs Quality Week’, but through making documentation debt a more integrated part of what all our teams can see and work on, and also improving the experience for users by making the documentation easier to find and navigate.
If you’d like to help: Please share your feedback via the star rating and ‘Report a problem on this page’ link at the bottom of docs pages! We review all submissions and are committed to resolving issues with increasing speed. Let us know what you’d like to see on a page, and we’ll work to provide it, to the benefit of everybody.
