 Uh, so everyone, welcome. Thank you very much for coming to the Community Dev Room. We're now pleased to welcome Tanya Roth, and she's going to be talking to us about doing effective technical writing, even if you are not a writer. So please welcome Tanya. Thanks a lot. Can you hear me okay? Oh, okay. So thanks very much. It's the first time that I'm at Foster, but it's great to be here. Welcome to the talk, Technical Writing, sorry for non-writers. I've done this talk a couple of times already. I usually do it as a one and a half hour workshop, including a practical exercise at the end, where you can really try to find issues in an existing text and modify it. We're not going to do that today, because we just roughly 20 minutes. So, um, yeah, by the way, my name is Tanya. I'm a technical writer since, well, a little bit more than 15 years now. I joined SUSE in 2005, and I'm in the documentation team, obviously. And before that, I have also written documentation for mechanical engineering and for medical technology. So maybe I would just like to have some quick demographics. What about you and the audience? So how many developers do we have here today? Oh, yeah, lots. Great. And actually, any first timers that have not written any line of documentation yet? Oh, yeah, quite a few. Perfect. Any fellow technical writers in here? Oh, OK. Welcome. Do we have any musicians here in the room? Wow, perfect. Because I would like to start with a very quick warm-up, and if someone of you would be giving us the parts like this, this would be excellent. OK, what's your name, please? J.C. So everybody, this is J.C., and he's our keeper of the pulse for this warm-up, OK? I would like you all to get up, please. Hit it hard. Lovely. OK, I would like to do some clapping, so I clap, you clap, OK? Let's go. Let me clap first. Now you. Perfect. Continue to clap, please. You can choose any of the patterns or make your own. OK, everybody, thank you, Jason. A little bit of a warm-up after the lunchtime, so I hope you feel refreshed now. Now that we've done that, let's dive right into this warm-up part. We did it already. Then let's go to the some basic rules. I mean, following the good old tradition less is more, and regarding the time that I had, I thought it would just make sense to pick some five basic rules that are easy to follow and easy to remember, even if you're not a language expert or don't want to dive into grammar very deeply. Because according to the Pareto principles, I could give you a huge set of rules, but in my experience, like 20% of the rules have 80% of the impact on your text, so that's why I just picked five. OK, so for me, the most important point is change perspective. I mean, especially as most of you are developers, of course, you know your code very well, you know your software very well, you know all the little bits and details about it, but you have to think of your audience. The better you know your audience, the easier it is to write something for them. So, for example, imagine you are a mechanical engineer and designed this fantastic engine over there. Of course, you are very proud of this engine and would like to describe it in detail. But if you know that your audience just wants to use the engine to drive a car, don't give them all the details about the engine. Instead, tell them, for example, how to activate the windshield wipers, tell them how to switch on the lights in bad weather conditions or how to execute maintenance tasks like refilling oil. So, also think about the level of detail. Usually if your audience is very experienced users, they don't need that much details, whereas newbies need a little bit more details. So, also in the warm-up that we just did, I assumed something about you as my audience. I assumed you're not wanting to lead any rhythm-based events, so I didn't go into all the details of techniques of how to do a rhythm-based event or intervention. I just, because you were simply participating in this, I just gave you the instruction that you needed to participate in this warm-up, okay? So, that would be the first point. Second one, I guess everybody is already familiar with this kiss abbreviation. It stands for keep it simple and short. So, the good news is, because also we had this in the previous talk, you have to think of your audience that are non-necessarily native speakers of the language that you're writing the text or will be publishing the text in. But this means also for you as a writer, don't worry if you are not an English expert and need to write in English, because if you keep it simple, it will also make it simpler for your audience and it will also make it simpler for any translators that are not very deep into their topic necessarily. So, and we can apply this principle to several levels. So, for example, we could have a look at words. So, very infrequent words, that is words that are not very common, they slow down the reading. So, if you have words like utilize, replace it with use, it's much easier and simpler. Same goes for indicate, you can replace it by show, or tell, or say. And also prerequisites, I would just replace it with requirements. So, and this is just a few examples, there are many more examples. Then we can have a look at the grammar level. For example, if you have an action and want to give the result of this action for the reader to make sure that he did the right action, so he got the right result. You could say, click OK, and the full bar dialogue will appear. So, that way you would have future tense for this result, the dialogue will appear. But most of the times, this is not really needed. So, also here, if it's appropriate, keep it simple. I would say like present tense is usually appropriate for like 80% of most texts, I would say. This is not saying you don't should use any other tenses, but also here you can apply this principle. Then another level is the sentence level. It sounds very easy or obvious, but in fact it isn't. So, if you write something, go through your sentences again and try to make sure that you have one idea per sentence. Not more. I mean, if it's very short ideas, it's okay to combine them. You could, for example, say, click OK and shut the dialogue. So, this I would say is still okay even if it's also two ideas in one sentence. But very often we write long sentences and if you go through them again, you will find that you mix a lot of ideas often into one sentence. And this just makes it more complicated. Then we have another thing like filler words. So, something completely new. So, if it's new, it's new. Cannot be newer than new. So, remove completely. The same goes for already existing. Just get rid of already. And we also very careful with words like simply or just. I mean, in spoken language, we use them very often. But also there, think of the situation of your audience. When do you refer to a documentation? Sometimes you refer to a documentation when you tried to find your way around the product and didn't succeed. So, you're actually probably already frustrated or angry because you didn't manage to get that damn thing running on your own. And then if you read in the documentation, just do, I don't know what, it doesn't help that much. So, get rid of simply and just. Then the next, by the way, I forgot to say something. I also tried to use this in the warm-up exercise because we did a little call and response where I clapped and then you clapped. I tried to give you something simple and easy. I didn't ask you to do body percussion and sing along the way. So, I tried to find something that everybody could manage. So, okay, next point, the third one. If you have very complex information and, of course, in technical documentation, this is the usual thing. We have complex information. Otherwise, we probably wouldn't need the documentation at all. So, but please try to divide it into smaller snippets into chunks. So, this helps to reduce the complexity and to provide multiple access points for users of probably different levels of knowledge. And if you don't know what to, if you need to structure a text and you don't know what to put first of all, everything that all of your readers need to know and that is not optional. So, for example, if you have to write about managing user accounts, I would say the first section could be creating user accounts. Then probably the second section could be enforcing password policies. And then as a third section, you could have something like managing quotas because that's probably something that not every, everyone who needs to create or manage a user account really needs to know, or at least he doesn't, or she doesn't need to know it at the very first place. So, then if we have a look at the hierarchy, I would say three levels are mostly enough. So, try to be pragmatic. Try not to be scientific. You are, although we are at the university here, you are not writing the doctor's thesis where you have something like section 1.5.7.12.15. This is too complex because if your readers don't find the solution to their problem within three clicks, you will very probably lose them and unfortunately mostly never get them back again. So, try to use a pragmatic approach to this, to your hierarchy. And then for something like where you want to give instructions or step-by-step describing an action, also think about there's something called Miller's Law in Cognitive Psychology. So, it's about our limits or our capacity for processing information. And it said that seven minus or plus two items is enough. So, if you have a procedure that has like 20 steps, think about it again and split it up into smaller procedures. So, find smaller subtasks because it's just easier to follow. And another thing regarding the structure, also after you have written it at the latest, then make sure it reflects your readers' goals, not your own ones. So, think about what your audience wants to reach with the software or which tasks they would like to go through and try to structure your texts from this perspective. And it also helps if you think about the purpose of each sentence or snippet because it makes it also easier for you as a writer. So, if you can say that there's something that's just really an instruction like do this, just put it into a procedure and make a step out of it. And there it's perfectly okay to use active voice. So, address your reader directly. And if you have a warning, for example, if you installed something and want to warn your readers that they need to do a backup first, this is a clear warning. So, put it in front of the step or of the action where the danger arises. So, it also helps you to structure the text. And if you have things like background information, like you want to explain a basic concept or the background, put it better in front of your procedure and don't mix it or merge it into the procedure because it will just load up all of your steps and it will make it harder to follow the individual steps. So, I would say if that's something, that's a description, put it in a separate place probably before the procedure. Yeah, also, again, forgot something, sorry. Also, in the warm-up that we did, I tried to split it into chunks. So, we had, for example, I reduced complexity by stopping one part of the group so the others could listen and everybody who's probably lost in this overall rhythm could get a new idea of how to join in again. So, this is also a means of reducing complexity. Okay, then the next point would be consistency. Again, if you are writing technical documentation, you're not in school anymore. So, it is allowed and it's actually very good practice to use the same terms for the same things because otherwise you will very probably confuse any unexperienced users or also any translators that only have very general knowledge of this topic. So, for example, if you talk about symbolic links, call it symbolic and you decide for this term, call it like that throughout your text. Don't call it symbolic link in the first sentence, then soft link in the next one and sim link in the third because probably everyone, an unexperienced wouldn't know that it is actually the same thing. So, think about terminology, be consistent. The same goes for spelling. There are, of course, several spellings for, in this case I meant the noun, actually, the add-on. You could spell it with a hyphen, without hyphen, or even into separate words which would not be correct from my point of view. This would be the verb form in my view. But anyway, if you decide for a spelling, stick to this decision. And if you have, especially if you have lists, use parallel constructions. So, if you see a list like this, why white space is important, attention focus. It visually separates sections, breaking content into chunks. So the reader may ask him or herself why you are using a different structure here. So, if it makes sense, use the same structure. You could say, for example, it focuses attention, it visually separates sections, it breaks the contents into chunks. Okay, also in the warm-up, I used the same gestures for the same things. This was continue to play, this was stop. So, also used consistency there. Then the last point, it's a very common thing to do in the English language to insert particles like however or nevertheless somewhere in the middle of a sentence. And chromatically, this is perfectly okay. But it disrupts the train of thought of your readers. And as we already learned, they might be impatient or angry already. So, put these particles either to the beginning or to the end of the sentence. And the same is true for long commands. Don't stick them in the middle of your sentence, it will just make it hard to read the sentence. And then there's a specialty of the English language, it's called phrasal verbs. So, something like shut down or start up. For example, you can separate these two parts of this phrasal verb, but it's much better if you just say shut down the server, so keep the phrasals together. Yeah, and with this I would be at the end of my talk. So, but I guess we can just open up for Q&A now. Yeah, absolutely. So, I'm going to get our next speaker in so she can start setting up all your ticking questions. And he would like to migrate. Give us two seconds to start walking out that door. And we will bring new people into this room. Fabulous. Thank you for your time. Tanya, thank you for your time. Thank you. Thanks. I would like to invoke rule five, avoid interruptions and point out that when you get interrupted it doesn't, you know, you miss rule four, which I would like to put on Twitter. Rule four? Don't remember. Sorry. That's okay. I'm sorry. It's not up here. Chris. Yes. Please. They are online already. Yes. And you can also find more reading resources there at the last slide. We will be publishing all the slides from the community. There was a second question. Or was it the same? Okay. Okay.