Categories & Tags
Archive

Building Better Documentation

July 1, 2014 in Demos, Tutorials and Tips, Unity Products and Services by

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.

unity_navmesh

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.

Share this post

Comments (24)

David
1 Jul 2014, 3:14 pm

That’s fantastic news guys! The Navmesh doc looks pretty great.

Mikko Mononen
1 Jul 2014, 3:47 pm

@david Thank you! :)

Terry
1 Jul 2014, 3:50 pm

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!

Peter Dwyer
1 Jul 2014, 3:54 pm

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?” ;-)

1 Jul 2014, 5:28 pm

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

1 Jul 2014, 6:28 pm

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

Will
1 Jul 2014, 7:30 pm

This is exactly what has been missing. Hope you continue this trend onward.

Great job!!!

Yukichu
1 Jul 2014, 9:47 pm

I wish there were docs like these when I started.

Excellent stuff.

Peter
1 Jul 2014, 10:44 pm

@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!

mick davidson
2 Jul 2014, 12:50 am

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.

Mikko Mononen
2 Jul 2014, 7:56 am

Thanks all the for the kinds and encouraging words! :) I’m really glad you found the doc useful even in that rough state.

This all started as an experiment in our team, but has gotten traction within the company. I’m excited to see all our documentation to improve over time (there’s quite a lot of ground to cover).

Once we get the docs out we’d like to find a good way to cover examples from the simple code snippets to complete example projects. I’m looking forward to work with our awesome learn team on this.

And I’m certainly hoping to share the lessons once we learn them :)

Tomasz
2 Jul 2014, 11:43 am

The new NavMesh document is excellent already. Looking forward to others of this quality.

Jes
2 Jul 2014, 2:42 pm

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 Mononen
2 Jul 2014, 3:02 pm

@jes Handling multiple agent sizes in one navmesh robustly is more complicated and computationally heavy than storing multiple navmeshes. The agent radius, height, step size and max slope all affect how the navmesh is calculated for a specific character.

Currently it is cumbersome to handle many agent types, and some use cases are not supported at all. We are researching improvements to the NavMesh system and workflow to make it easier to handle multiple agent types.

Jean Paul Marinho
2 Jul 2014, 5:21 pm

Wow, it’s an amazing doc! Thank’s!

2 Jul 2014, 6:35 pm

Hey I know Laurent he works with me!

Arnold P
2 Jul 2014, 10:41 pm

Finally!!! this is one department unity really lacked

Sean Baggaley
3 Jul 2014, 1:44 am

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.

3 Jul 2014, 7:02 am

The best documentation was in PHP.
So do the same, Allow people to comment and add to it (under the API Reference).
But make it sapereted maybe different color.
just some page example: http://ca1.php.net/manual/en/function.list.php

Mikko Mononen
3 Jul 2014, 10:15 am

@jean & arnold Thank you! :)

@leon Say hi to him ;)

@sean Excellent point! What you just explained is what the UX folks try to do, that is, make sure that the whole experience of using a product is well thought out. Some things you do in Unity are fundamentally complex. The easiest way to make something simpler is to make it more understandable. Documentation plays a big role in that. There should be docs to help you understand concepts, and docs to help you solve problems and docs which you can use later as reference.

@boris There’s an on-going effort to allow you guys to give more direct feedback on documentation. I like PHP’s way of doing it. Do you know how they manage it so that it does not become a forum for asking questions? I remember jquery having comments in the documentation, but they were often not very useful as they were full of questions.

3 Jul 2014, 2:11 pm

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

3 Jul 2014, 8:13 pm

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.

14 Jul 2014, 10:42 am

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)

Luke
25 Jul 2014, 2:02 am

Thanks Guys! Cool stuff! Thanks for Empathizing!

Leave a Reply

Please enter your name
Please enter a valid email
Please enter a comment
Spam protection error

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>