Unity Documentation in 2017
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.
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!