Building Better Documentation
One of the hardest things about writing documentation as a developer is to step into the shoes of the user. When you know everything about a feature of a product, it can be extraordinarily hard to see the whole thing with fresh eyes. We went through that exercise recently with NavMesh, and I wanted to share you how we did it.
Implementation Model vs. Mental Model
One way to be able to dive into the users perspective is to inspect the product from the implementation model and mental model. Simplified, implementation model is the way the developer sees the product, and mental model is how the users sees things. These can be very different.
For example the implementation model of a car is all about cylinders, spark plugs and differential gears, but the mental model is a vehicle which gets you around. The more advanced you are in a topic, the more you eventually learn about the implementation model too. But the common case is that you wish that it would just work.
Here’s the journey that most Unity users go through when learning a new feature:
- Fundamentals describe what the whole feature is all about and how it’s different pieces fit together. If you have some problem you’d like to solve, the fundamentals should give you just enough information that you can start solving the problem.
- Procedures map the fundamentals into things and workflows in the Unity UI, such as adding specific components or baking NavMeshes.
- Techniques combine all of the above to solve actual problems, for example: how to move a game character to the point you clicked on your level?
Before the user gets into the fundamentals she’s often faced with some sort of communication about the feature. For example a novice user might not even know that he should be looking for NavMesh in the first place, or more advanced use might just skim around to see if the specific feature she’s looking for is covered. This is often covered by our marketing material, blog posts, forums and Unity evangelists.
Many of our users of not ever reach the very deepest end of the pool, but some do. When you want to optimise the last bits of your game, or if you have very specific need, you may end up reaching the point where you’re poking right at the implementation model.
To sum up, the first step was to understand what types of information the users need when they learn a new Unity feature. The next step is to understand who to write to.
Know Your Audience
The need to write better documentation emerged from a discussion we had earlier this year about the audience for Unity NavMesh. We talked to people and tried to tease out what was missing and what their pain-points were.
Based on the interviews and previous discussions with our users, we build a number of personas (or characters). These personas provide a way to walk down from mental model towards the implementation model with a specific state of mind. The journey will be different for a novice versus a pro users and differs based on discipline too.
We mapped 5 personas, here’s who they are:
- Fernandez, Hobbyist game developer, “I’m new and I just want to make a mobile game.”
- Ivo, Senior game programmer gone Indie, “I’m veteran programmer, implementing AI for the first time.”
- Oleg, Senior AI Programmer, “I’m reimplementing our old AI system in Unity.”
- Laurent, Senior Game/Level Designer, “I want to design complex game with great AI”
- Miia, Architect, “I want to add life to my architecture visualization”
We further organized them based on “how much AI” they want, and “how much programming” they can do. The idea was to try to find outliers, such as Laurent, who will require more tools to be efficient in his job.
One part of the process is to also pick which personas to focus on. We chose to focus on Ivo, since the things we needed to improve for him, also helped Fernandez and Oleg. For the time being we’re focusing on programming savvy users, leaving out, but not forgetting, Laurent and Miia.
Personas change over time, we reconsider the validity of the list after each release as we learn more about our users and their projects. In addition just writing documentation, personas are a great way to focus work too.
Documentation Driven Development
Now that we know what we need to explain and to whom, the task of changing perspective and explain things becomes a lot easier.
One thing we found sorely missing was the fundamentals, so we started with that. One thing lead to another, and soon we had procedures and some common techniques explained too.
At times trying to explain things in plain (Nordic) English was quite humbling. Some features looked really simple from the implementation point of view, but felt upside down, when trying to explain them from user’s point of view.
More often than not, if something takes a lot of effort to explain, it is often also hard to understand. That does not mean that you cannot explain complex things. Being able to refer to existing documentation, such as the fundamentals, can greatly simplify the explanation.
One thing we want try later is to “improvise” the documentation earlier in the development process as a first test to see if the UI and the terms make sense when talked out loud. I guess one could almost call that documentation driven development.
Here’s a programmer literature version of the doc we wrote. From here our great doc team will take over and turn that into a proper documentation.
We found this first pass very useful, but we want to improve going forward. For example we want to learn how to present more advanced techniques concisely, how to write better API docs so that they answer the question you had in mind when looking things up, and how to better APIs and components in the first place so that they are easier to explain.
Stumbling towards better documentation,
– The AI team.