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.
The number of new Unity features and updates documented at release date has more than doubled:
In 2016, we implemented:
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!).
Previously: There was no technical writing or editorial process.
Now: All User Manual content goes through a multi-stage technical writing and editorial process:
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.
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.
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!
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).
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!
Is this article helpful for you?
Thank you for your feedback!