Search Unity

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.

Artboard 1

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.

24 replies on “Building Better Documentation”

I like the way you decompose mental process and user goal.
It seems you are also taking into account perceptual mapping, will you make a giant zoomable visual doc? (big picture of all the paradigm where you can click on links, zoom in, pan to get a feel for the flow of things)

Mikko – I think they moderate the posts, and you can also add rating system to the comments, so we will bring up the most usufull user comments/usage examples.

Great documentation! The use of visual aids, like pictures and graphs are also very much appreciated as they really clear things out. Thank you.

I wish this were a more widespread attitude.

All interfaces are about communicating information. There are no exceptions. In my years as a technical author and, before that, a programmer, I realised early on that documentation is as much an integral part of a user interface as any dialog box, icon, or menu.

If you’re doing any form of UI-driven development, then documentation has to play an integral role in that.

I khow that it is about documentation not about AI navigation, but please don’t bake agent size into navmesh!!! Use agent size in path finding algorithm so we can path for any type of agent using only one navmesh and not one special navmesh for every type of agent.

Mikko, as a tech writer, I find this a useful and fascinating article. Thanks for sharing your experiences. I think you’ve done an excellent job evaluating the problem and the possible resolution. As you say, explaining complex information simply and effectively is difficult, but not impossible – obviously that’s what tech writers ought to be doing. It will be interesting to see what happens next.
Will you also be sharing that experience too? Cheers.

@Connor You are not even vaguely alone in that. I’m a qualified software engineer and I struggle to grasp some of the existing explanations of unity functionality. I followed one of the learning animation tutorials and then tried it myself. I sat there for 10 minutes trying to work out why a transition didn’t seem to trigger the way it had in the tutorial and the way it was described in the existing old documentation. Finally, when I came at it from the “If I were writing this functionality what would I have done” angle I managed to figure out what the documentation simply assumed I knew from the start!

I consider myself a “Fernandez” and this is going to be very, very helpful for me. I struggle with understanding certain concepts and methods, mostly due to a lack of formal training.

I will benefit greatly from further documentation like this.

Thank You

Great news! The documentation is oftent the thing not onle hobby developers lack, but even huge professional projects! Thank you for such a detailed doc

I feel like I should be falling to my knees with my hands outstretched yelling “At last! At last they get it!”

Of course what I’m actually going to do is ask “So where’s the rest of the docs then?” ;-)

Yes! Yes! Yes! The doc is *outstanding*. You allow us to see the pictures and how everything falls into place and works and also provide for the low level technical details. This is a home run…Thank You!

Comments are closed.