Technical Communication for Unity Developers

Editor's Notes

• #2: Good morning and welcome to Technical communication for Unity developers! Before we begin proper, let's introduce ourselves.
• #3: 0:30 - 02:30 KERRY: So, who are we and what do we know about technical communication? (Kerry intro) SIOBHAN: I’m Siobhan Gibson, I work on the documentation team as a technical writer and editor. My main job is to collect information from developers at Unity about upcoming features and updates, and to turn that information into Unity’s technical documentation - mainly for the User Manual and API Reference, but also for release notes and other technical resources. I also act as an internal documentation consultant for Unity’s development teams, to help them produce more useful resources for users and for each other, and I produce writing guides and resources on technical communication for the whole company. I work with development teams, QA engineers, support, content teams, community management - pretty much anyone at Unity who communicates with our users. Today, we’re going to talk about a lot of the information that’s in the resources I produce.
• #4: 02:30 - 04:00 SIOBHAN: So, let's talk about what you'll learn from us today. So today we’ll start with what technical communication is, and why it’s important - not just in general, but also why it might be particularly important for specific tasks. Next, we’ll talk about how to be a good technical communicator. We’ll go over the foundations of technical writing, including the three key principles to bear in mind, and a recommended technical communication workflow based on how we work at Unity. We’ll also include some advanced tips and recommendations based on our combined experience, for those of you who want to know how to go from being a good technical communicator to a great technical communicator. What we won’t cover is specific writing tips - you’ll be pleased to hear this won’t be an English lesson! This is a high level overview of technical communication concepts and best practices, and the advice we give you should be transferable in whatever language you’re using to talk to your users.
• #5: 04:00 - 06:30 KERRY: So, what is technical communication? It’s not a trick question! Technical communication is when we communicate technical information. when do we use technical communication? So you might initially be thinking about the things that Siobhan and I do: documentation, technical support, tutorials. But it's much wider than that. If you're working on a game, technical communication happens all the time, in all parts of your work, right from the very start of the project. Technical Design Document/Game Design Document, Email or Slack message to a colleague, Code comments, Reporting a bug, Social media, Giving a talk Basically, any time that you want to convey technical information to another person, that's when you're using your technical communication skill. As you can see, it's a skill that runs all the way through game development, from first design to promotion, to support.
• #6: 06:30 - 08:30 SIOBHAN: So let’s take a look at some of the specific scenarios in which you might benefit from good technical communication skills. If you’re making or releasing something, e.g. games, assets, hardware: People can use the things you make! They can find the information they need, so they can get stuck in quickly If you’re promoting something: good comm allows you to promote the technical features it in a way that works best for your target audience If you’re writing documentation: Good docs and tutorials reduce the load on your customer support teams, by making it easier for your users to find the answers themselves instead of sending support tickets If you're filing a bug report: Clear communication helps you avoid too much back and forth when trying to resolve bug reports, so you can get your bug fixed quickly If you’re talking to colleagues, good comms means clearer conversations, and fewer misunderstandings or guesswork If you’re talking to customers: Being able to clearly communicate technical info with your customers gives them much more faith in you, and allows you to develop better relationships
• #7: 08:30 - 10:30 KERRY: There are two very common misconceptions about technical communication. The first misconception is that if you have knowledge of the thing you're communicating about, then that's all you need. For example, someone might think that because they developed a feature then they will automatically be good at communicating about that feature. This is incorrect! As Siobhan knows, in the old days, the Unity Manual was written entirely by the developers. They would develop a feature, then write the docs for it, and the docs would go live. With, uh, varying results! Some bits were good, some bits were… not good. Knowing your subject matter helps you to communicate, but it is definitely not the be all and end all of technical communication. In fact, you don't even need to know MUCH about the thing you're communicating about to do a good job - we'll talk more about that later. The second common misconception is kinda the opposite. People think that you need to be a good writer to be able to communicate effectively, and perhaps if they aren't naturally keen on writing, or are working in a second language, or whatever, that that means that they can't do this. This is also wrong!
• #8: 10:30 - 11:30 KERRY: Technical communication is a skill. A separate skill from writing, and from subject matter knowledge. If you're good at writing or have subject matter knowledge, you can still be bad at technical communication If you're bad at writing or don't have subject matter knowledge, you can still be good at technical communication As with any skill, you can practice technical communication and get better at it. You just need to know how to do it. Luckily for you, we have created a foolproof guide. If you follow the steps we will teach you, you will produce good technical communication. And the more you practice, the better your technical communication skills will be, so that you don't need to keep referring to the guide - the skill will come naturally to you. So, let's start with the first part of our guide: the 3 principles of technical communication.
• #9: 11:30 - 14:30 SIOBHAN: The three main principles of technical communication are Accuracy, Clarity, and Conciseness. Each of these is important for a different reason. Accuracy is the most obvious. If your user has the wrong information, or doesn’t have all the information, they can’t use it. When we talk about accuracy, we also mean completeness, and precision. The information you provide needs to be correct and complete. Clarity is important because if the user has the information, but they don’t understand it, they have the same problem; they can’t use it. When information isn't presented clearly or isn’t aimed at the right audience, the reader might misunderstand it, or just give up on it. Confusion in the way you communicate can also end up alienating your reader, by making them think that something is more complicated than it is. The information you provide needs to make sense to your audience. Conciseness is perhaps the least considered, and often the most challenging when communicating technical concepts, but it’s just as important as the other two. People tend to be task-oriented when reading technical info; they scan for the relevant information and skip the rest. The information you provide needs to be easy to find. KERRY: This is your cheat sheet here. This is the secret to great technical communication. If you remember nothing else from this talk, remember this! When you communicate, ask yourself: is it accurate? is it as clear as it can be? Is it as concise as it can be? If the answer is yes, you're doing a good job. If the answer is no, your communication still needs work. Now, you might have noticed that while "accurate" has a fixed meaning - something is either accurate or not - and "concise" is pretty simple - you just need to say things plainly and in as few words as possible - "clear" is a slightly more flexible idea. What's "clear" to one person might not be clear to another. And sometimes to make something more clear, you might need to make it less concise. How do you know when your work is clear enough or concise enough? Don't worry, we'll explain that in a minute. For now, just remember these three principles.
• #10: SIOBHAN: Here’s an example of a piece of technical communication. Delamping: Apply levo-rotatory force to the incandescent lamp until it is separate from the Edison screw chamber. Now, you might be able to figure out what this is trying to tell you, but only if you had some fairly specific knowledge. This uses some obscure terminology, and it’s not immediately clear which bits of information are important and which aren’t. Let’s take a look at how we could rewrite this.
• #11: KERRY: “To remove a lightbulb, twist the bulb counter-clockwise until it comes away from the socket.” So in this example, the content is still accurate. But now it's also clear and concise. This is what I meant when I spoke earlier about people thinking that subject matter knowledge is the most important thing - in fact, in this case, it was a hindrance, because the original author had lost sight of what is clear and what isn't.
• #12: 16:30 - 18:15 SIOBHAN: OK, so we’ve covered the 3 main principles - accuracy, clarity, conciseness - and now we’re going to take you through the workflow we use to ensure all of our technical communications adhere to those principles. These steps are drawn from how we write, and from general best practice for writing. First, you define your purpose and your audience, then Prepare your source material, then Write a Draft, and finally, Edit and proofread We’ll take you through each of these in detail: what you need to do, and when you know you can move on. Go through these steps whomever you’re communicating technical information - it’s good practice and over time it’ll make your tech comms better. It’s important to note that this doesn’t always need to be a super-formal process. So let’s start with the first step.
• #13: 18:15 - 21:30 KERRY: Step one. Begin by defining your purpose and your audience. This means asking what you want to communicate, and to whom. Doing this helps you define what is meant by “clear”, because you know what "clear" means for your audience.
• #14: 18:15 - 21:30 KERRY: So in this case, I'm showing you examples from my own work. Both examples are descriptions of garbage collection in Unity. The first is from a tutorial I wrote for beginner Unity users who are new to the subject of garbage collection. ”When our game runs, it uses memory to store data. When this data is no longer needed, the memory that stored that data is freed up so that it can be reused. Garbage is the term for memory that has been set aside to store data but is no longer in use. Garbage collection is the name of the process that makes that memory available again for reuse.” The second is from a report I wrote for experienced Unity game developers. ”The game generates up to 20 KB of garbage per frame, resulting in frequent garbage collections.” In the first example, I define a lot of terms and explain the WHY of things. This is because my audience are beginners. For this message to be clear to them, I must introduce new concepts and words. In the second example, I know that my audience is familiar with the terms I'm using, so I can be much more concise while still being confident I'm clear. This is what we mean by clear for your audience.
• #15: 18:15 - 21:30 When to move on: Are the purpose and audience accurate? Have you included all of the information you want to communicate? Have you considered every member of your audience? Do you understand how to be clear for your audience?
• #16: 21:30 - 24:00 SIOBHAN: So now you know what you’re trying to communicate, and who you’re communicating it to, it’s time to start gathering information. This step is focused on accuracy and completeness. If you’re the developer, you can probably skip some of this, because you’ll be familiar with the subject matter already (but extra info good). If you’re not the developer or an expert on the subject matter, this step is really important. When researching, we recommend you collect as much information as possible, from as many sources as possible. In technical communication, you’ll often find that you need to collect, absorb and discard many pages of information to write a single sentence that is accurate, clear, and concise. Talk to developers and QA engineers, and find out what testers and users are saying - either by talking to them, or by looking at community spaces like forums. If you can get a demo to test yourself, even better. When you’re gathering this information, it’s good practice to keep asking questions, not only to check that your understanding is accurate and that the information you do have is complete, but because you need to advocate for the reader at this stage. Keep looking at the information you have, think about where a new user might get stuck, and whether there’s extra information you can collect to help them.
• #17: 24:00 - 25:30 SIOBHAN: So, when do you move on from this step? These are the two questions to ask yourself: Is the information I’ve gathered an accurate and complete representation of my subject matter? Is this information clear enough for my audience? Let’s take one example of when you might do this. Let’s say you’re collecting information to write a tutorial. You can make sure it’s accurate by making sure you talk to multiple people and read multiple sources, and by testing the tutorial workflow yourself to make sure you understand it fully. You can make sure it’s clear by thinking about who your audience is, and whether they’re likely to understand the information you’ve gathered. For tutorials, your audience is usually somebody who’s never done this before, and who might even be engaging with the concepts for the first time! So you could do extra research by reading other beginner-level tutorials aimed at the same audience, to see which terms and concepts you probably need to explain. When you’ve collected enough information that the answer to these two questions is yes, you’re done, and you can move on to the next step.
• #18: 25:30 - 30:30 KERRY: If you've ever written an essay, you've probably been told to write a draft first. A draft is a rough version of the message. It has all of the correct information on it, in the right order, but without worrying about the quality of the writing. First, you create what's called a first draft. This is the first version of your message, and it is not for anyone else's eyes - it's just a stage where you practice delivering the message. I recommend that you write your first draft as quickly as possible. It's very common, as you write this first draft, to realise that you don't have information you need - it's best to a TODO where you have missing information. The same with if you just can't describe something well - do a bad job and leave yourself a note to return to it later. Just get something finished! When I'm writing something longer form, I actually find this the hardest part of writing, because it can feel very overwhelming to sit in front of a blank page and just start. The best way I've found to push through it is to keep the momentum going - honestly, write anything no matter how bad. Write "something about why garbage collection is bad" if you have to. You can return to it! If you're not used to drafting and you're new to improving your technical communication skills, it's good to call whatever you would normally write your first draft. So in the case of something short, and informal, like an instruction to a colleague, type it out and then review it. Once you have your first draft, take a break and look at it again. Read it through and identify any missing information. Fill in any missing information. Check that the content is in a clear order: does one part of the message lead logically to another, or do you start on topic A, then jump to topic B, then back to topic A? If the order isn't clear yet, reorder your message. Keep doing this until you are happy that all of the information is there, and it's in an order that will make sense to your audience. When it is, this is what we call your final draft.
• #19: Here's an example of drafting to add information. First draft: ”Click on the [BUTTON NAME] button." Final draft: “Click on the Start button.”
• #20: Here's an example of drafting to re-order information. In the case of a bug report, the logical order is the order things happen in. First draft: ”The application crashed. The last thing I saw before the crash was a popup saying "Error 234". This happened when I clicked on the Start button." Final draft:"I clicked on the Start button. I saw a popup saying "Error 234". The application then crashed.”
• #21: 25:30 - 30:30 To work out when your draft is at final draft stage, you should be asking yourself: Accuracy: is the information accurate? Clarity: is all of the information that my audience needs here? and is it in a clear order? The wording will not be clear, so don't worry about that right now - just the order that the information is presented in.
• #22: 30:30 - 32:30 SIOBHAN: The final step is editing, which is the main part of my day-to-day job. Editing is where you transform your draft document into a user-facing document. Most of the work is focused on re-organising, re-writing and condensing information. While drafting is primarily focused on accuracy, editing is focused on meeting our other two key principles: clarity, and conciseness. Before I start talking about this, I want to clear up a common misconception: While a lot of people think that editing is primarily focused on fixing spelling and grammar, it’s actually a much broader task that encompasses much more than that. Spelling and grammar come under what we call proofreading, and although proofreading is an important part of the editing process, it’s a small part at the end - and that’s the part you really need a writer for, especially if you’re not confident in your own writing. It’s best practice to have somebody else do it, because they can look at it with fresh eyes and help you find the gaps in information, but if that’s not an option, self-editing is still better than no editing.
• #23: 32:30 - 34:30 SIOBHAN: Let’s start with clarity, and look at some ways to ensure clarity in your communication. - Use audience-appropriate language. Think about the audience you defined earlier, and use language that your audience will understand. If you’re writing for a broad range of users, like I usually do, try to avoid advanced technical terminology, or at least include an explanation or link to give your reader more information. If, like Kerry, you’re writing for a more specialised audience, speak on their level, and try not to make too many assumptions about what they might know outside of that specialised subject. - Be consistent. In this context, we mean consistency in the way you write and the terminology you use - for example, if you’re referring to a GameObject in Unity, you should always use the word GameObject, not object, or actor, or anything else. You should also use this step to make sure your communications match your UI, that the words you’re using to refer to specific buttons or settings do actually match what your reader will see when they try to reproduce your steps. Consistency is a really big part of gaining your reader’s trust, and establishing yourself as a valuable source of information. We use a writing style guide to standardise our communications, which we’ll talk about more in a moment. - Avoid ambiguity - Technical communication is only useful when it’s precise and exact. Think about whether the information you’re providing could be misinterpreted, how it could be misinterpreted, and and how likely it is for it to be misinterpreted - then re-write to avoid misunderstandings.
• #24: 34:30 - 36:00 KERRY: This is an example from the API docs, for the property AudioClipPlayable.isPlaying. Here’s what it said originally: “Is the AudioClip currently playing?” If you’re familiar with API docs you could probably work out what this means, but it’s not at all clear, and it’s not telling the user anything - in fact it’s asking the user a question, which is really unhelpful! Here’s the same information, rewritten for clarity: “Use this to check whether the Audio clip is currently playing. Returns true if it is playing, or false if it is not.” This actively tells the user what the method is for, and what it does under different conditions - there’s no ambiguity here.
• #25: 36:00 - 37:30 SIOBHAN: Okay, let’s move on to editing for conciseness. - Our key point here is to remember the purpose of content. It’s tempting to include a lot of extra info, like anecdotes, or the history of the concepts, or hypothetical situations. Remember what specific piece of information you’re trying to convey, and cut out anything that doesn’t directly achieve that. - Lead with important info: Readers are task-oriented; they tend to scan the beginnings of sentences to look for the specific information they want. You can help them out by making sure your paragraphs and sentences act as good indicators of the information. - Don’t write too much: It’s really easy to write 100 words about something that could be explained with one sentence, but padding just dilutes your information - which this next example demonstrates.
• #26: 37:30 - 39:00 KERRY: This example is from some unedited draft documentation, and it’s aimed at gamedev programmers. “If you happen to know how to handle the correct number of threads that your system can handle, and avoid bugs caused by race conditions, you can perform multiple tasks at once that can run for a long time. Unfortunately, when you’re developing a game, this is rarely the case. Usually, you have a huge number of small things to do.” It’s long, and a lot of it is padding - we don’t need to think about the hypothetical situation that it lays out to understand what the content is trying to say. Most of this paragraph is actually about something that doesn’t happen. The only part that’s relevant to our game developer audience is the very last sentence. Let’s rewrite that. “Game development code usually contains multiple small tasks and instructions.” The After gets straight to the point; it only tells the developer reader what they need to know. Also note that the first example is 61 words, while the revised version is only 10 words. If you include unnecessary padding, you’re creating extra work for yourself! - and in the case of resources like tutorials or documentation, editing it down means you have less content to maintain.
• #27: 39:00 - 40:00 KERRY: So, when is it time to move on from the editing stage and actually send your message? That is up to you. Using all the skills you’ve learned so far, simply read the edited message and ask yourself: Is it accurate? Is it clear for your audience? Is it concise? If the answer is yes, great! You have produced a good piece of technical communication.
• #28: 40:00 - 41:00 SIOBHAN: OK, so that's how you get good, but how do you get GREAT?
• #29: 40:30 - 41:30 SIOBHAN: Use peer review. Peer review is when somebody else checks your work - you might be familiar with having your code reviewed in the same way. * Get subject matter experts to check it for accuracy. * Get users to check it for clarity and conciseness. Invite feedback and dig into it - what didn't they understand? At which point did they get stuck? Were there any areas where they felt like they had to guess what you meant? How could it have been clearer?
• #30: 41:30 - 42:30 SIOBHAN: Our next tip is to use a style guide. A style guide is a set of standards - If you work in a studio, you might already have a set of standards for your code or your design. You don't necessarily need to make your own writing style guide - at Unity we use the Microsoft Style Guide as our base, which is online and free. It acts as a reference guide for writing, and means everyone has quick access to basic writing guidelines. We then maintain an internal Unity-specific one on top of that, to help us to keep track of standardised Unity terms, like Prefab or Asset, and to make sure we only ever use those terms when we mean to * It also helps us keep track of the more obscure aspects of writing about technology, like when we need to know whether we mean run time, run-time or Runtime
• #31: 42:30 - 43:30 SIOBHAN: Soft skills are “personal attributes that enable someone to interact effectively and harmoniously with other people.” In practice, this generally means social and interpersonal skills. It’s the opposite of hard skills, which we generally use to talk about specific quantifiable skills like programming, or maths, or writing. A lot of communication is ultimately about empathy - understanding the other person, putting yourself in their shoes and thinking about how you can reach a mutual understanding. Technical communication is no different! You can't only apply logic to a task like this; you are a person, communicating with another person, and to be a great technical writer you need to remember that good communication happens when understanding happens in both directions - the more you think about and understand your reader, the better you'll be able to communicate with them.
• #32: 43:30 - 44:00