 I think there's more people who wanted to come, at least according to Shad, but I think we should just get started. Thanks everybody for showing up to this talk. My name is Christoph Wickerth. I used to be very active in Fedora. I used to be a package maintainer, ambassador, FAMSCO member, FESCO member, board member, council member and whatnot. That's what I'm going to talk about tomorrow, about my decade in Fedora. Now I'm going to talk about documentation, because I joined the SUSE documentation team a little over two years ago. Technical writing is my profession now. I've been writing technical documentation at KOLUP before, but I'm going to tell you some basic rules about technical writing. These rules are not only applied to documentation, but you can use them anywhere you want. You can use them, for example, in bug reports. You can use them even in technical emails. I would argue that technical language is more or less the same. Of course there's more to documentation, but for now we just stick to the basic rules, I suggest. I've made it six basic rules. After that we can have a question and answer session. At the very end I can give you some sources. Unfortunately not all, but we have more sources on the web for what I'm showing you now. All right, before I start, a little bit of fun. Avoid alliteration, always. These tips are from a website. First I found them on Facebook. When I googled for them, I found them on a website called plainlanguage.gov, which is a very valuable resource that I would like to recommend to everybody who wants to, not only for technical documentation, but for any kind of plain language. So plainlanguage.gov holds plain language guides for various institutions and organizations in the US, but also so many resources about language. And among them there's also a few more sections where these rules are from, and there's so much truth in there. Prepositions are not words to end sentences with. Avoid cliches like the plug. They are old hat. Comparisons are as bad as cliches. Be more or less specific. One should never generalize. Be consistent. Don't be redundant. Don't use more words than necessary. It's highly superfluous. Who needs rhetorical questions anyway? Acceleration is a billion times worse than understatement. Don't use contractions. So that was just for fun. There's way more of these on this website. I can show you some of them later. You don't need to follow all of them, but there's certainly some truth in every of these rules. I think it's 70 in total. It's just funny. But I'm going to stick for, I mean, you cannot just make these, it's not enough to make the opposite of what I just told you. But there are some even more fundamental principles that you need to attire. First, you need to change the perspective. Who's the best person to write? So imagine you're a developer. How many developers do we have in the room here? Okay, basically most of you. Who's the best person to document the program or the code that you have written? You are, right? You know everything by heart. That's true. You're the best person, but you're also the worst person because you know everything by heart. You make assumptions about your code. You know everything. Actually, you don't even need documentation. Just read the code. But that's not how it works. You need to learn to look at your program from a user's perspective. And I know this is very difficult. That's why in a perfect world, everybody has dedicated documentation writers like we have at SUSE. It's similar to quality assurance. You shouldn't quality assure your own program. You need to have a different point of view. You need to know the user's expectations. You need to know your audience, your target audience, or your users. It's a big difference if you're writing for system administrators or if you're writing for other developers. If you're writing an API documentation, for example, there it's probably pretty easy for you to switch the point of view. But if it's try to think as a mere mortal desktop user who doesn't have a clue what's under the hood. So basically don't tell them how it works. Tell them how to use it. That's all. They don't care about, if you have a car, they don't care about the engine. They want to drive. And they need to know how to turn on the wipers or how to turn on the light. How to drive when there's snow. How to change the oil. So just stick to what's important for your target audience. Try to find out who's your target audience. Maybe you have a clue about this, for example, from discussions on mailing this or from bug reports. Sometimes think you are also a user. If you file a bug against a program, somebody else wrote. At that point you're a user of this program. So try to remember these situations and try to write from that perspective. But that's really the crucial part. And if you don't get your target audience right, you won't get the documentation right. There are some hints to do that or some tricks. Some people use personas. I recall in Fedora, we did that too. On the Fedora homepage, I'm not sure if it's still online. But at some point on the Fedora homepage we had the different Fedora users. We were actually introducing them. So one is a professional musician, the other is a sys admin. The next one is a developer. But then you have a musician again. They all tell their user stories, how they use Fedora. So it's all about persona and user stories. A lot of people, if you're into professional documentation writing, you try to really have these different personas. You write them up and try to look at things from their perspective. Actually there are some people who even do real world user testing who don't make up these personas, these example users. But really have some users use their program and test it. But that's why I made it the rule number one. It's the most underlying rules of all. At SUSE, we often define the target audience. At the very beginning of the documentation, we say this handbook was written for. And then you would lay out administrators or users or whatnot. The next thing is a giant pile of information and you want to structure it somehow. So split it up into chunks. First things first. What everybody needs to know. Try to make a high level summary. Like say installation, setup, first time use, maintenance, whatever. These are the four, that would be the four chapters of your documentation. And then you go further down into this hierarchy. I suggest to not have more than three levels of, more than a three level hierarchy. But that should usually be enough. And within this three level hierarchy, you should usually only have seven plus minus two items. Yes, I know sometimes this can be hard. Actually having more is not necessarily a problem. If you have a consistent hierarchy, for example, I recall a project that I was recently working on. Where we describe a lot of command line options. Yes, I think we ended up at 11. So that's clearly against Miller's law. But if your hierarchy, if your structure is consistent, then it's not really a problem. If you have something that needs to be executed in a certain order, make it a procedure. A procedure is usually numbered and a procedure shouldn't have more than 10 steps. If you have more, you can think about sub steps. Well, first of all, you can combine steps. If the next step is just click OK, then you would just add it to the previous step. If you have optional steps, that would be sub steps that you can skip. If you could actually inside a procedure, you could also start using a hierarchy. But I would recommend only using two levels there. But again, it's all about the structure. If something is unrelated, then you can have basically any structure you want. You can skip stuff. Going back to the example installation setup, first time use, maintenance, whatever. They can just jump in on chapter two because the program is already installed. They just need to set it up. So here, order doesn't matter. But if order matters, then make it a procedure and make sure you have numbers. When you make this structure, think about the reader's goals. The reader's goals is usually get this stuff up and running or get this, use it. You have a certain purpose, a certain goal that you want to achieve with this program. So try to do everything with this structure from the reader's goals to clearly achieve. Every point in the structure should help the user to achieve another goal. When the user is finished reading chapter one, he should have installed the program. After chapter two, he should have set it up and so on. When you have instructions, you usually use the active voice. You address the user directly. I know there are programs that handle this differently. For example, GNOME usually uses the passive voice in all its translations. It's a difference if you say, do you use file or should this file be deleted? In documentation, I would suggest to use an active voice. Because you are addressing the user directly. You need to install this program, not somebody else. If you say the program needs to be installed, then, well, it's not my business. So you're clearly talking to the reader and that's why you use the active voice. Again, procedures with steps. If you have something difficult, make sure that the warning is before the step and not afterwards. Otherwise, people may be very angry at you if they have screwed. I mean, if things are okay, they have just screwed up that particular step and you need to start over again. If things go really south, they have deleted data and they are not happy at all. And the same goes for background information. For example, an architectural overview or what's an introduction. Of course, all of that has to go before the procedure. Again, before the procedure, you would say, you would clearly outline the goal. This procedure helps you to install that or to do that. And if there's any additional information needed about the goal, if the goal is until or before it has to go before the procedure. And now whatever, now you actually start writing. At least that's what I hope. And keep it simple, stupid, the kiss principle. We all know it. Use simple words. That's not only simpler for you, but also for your readers. You're probably not going to translate your documentation into different languages. And you're not necessarily a native English speaker. I mean, I'm not. I know a lot of people here are not. And probably your users won't be native speakers either. So that's why you use a simple language. And even if your documentation is translated, even if it's translated by professional translators, at SUSE we have certain documentation that is translated and certain documentation is not. But even if you have professional translators, using a simple language makes it easier for them. You can be sure that the translated result is what you had actually in mind. So the kiss principle means you use simple words, use instead of utilize, show instead of indicate, requirement instead of prerequisite. I mean, there are lots of examples. It's not about, we are not talking about winning a Nobel Prize here. It's not about that it sounds nice or that yes, you should avoid, try to avoid duplications. But on the other hand, you shouldn't use 10 different verbs or 10 different words for the same thing. That goes back to the B consistent that we had before. Then grammar, click OK. The printer dialogue appears. That's straight forward. That's, I mean, as simple as a sentence can be. You have the noun, you have the verb. It hardly can be any simpler. Try to only stick one idea into one sentence. Don't use complicated sentence constructions before, after or something. If you use something like that, make sure to indicate it clearly. If then, before, after, first, second, not first, next, next, next. Again, there you would make a procedure, first, second, third. Finally, for example. And try to avoid fillers. There are so many fillers that you can avoid, that you just shouldn't be using. If you read it over, you will find out better without them. Even if it doesn't sound natural at first, because you think it's too simple. But again, simple is good. B consistent, we just had that in the how to write good rules, but something that is very, very, very important. At SUSE, we have the SUSE style guide, and actually we have a terminology there, or in all projects that I've been working with. I've also been working with the XFCE and the LXSDE translations. I was the coordinator for the German translation team. So you usually have a dictionary or a terminology to make sure you are consistent. And it's really surprising how many different words you can find for the same thing, or how many different spellings you can find for the same thing. So really try to be consistent here. Okay, parallel constructions. Why white space is important. You see, it doesn't work here, right? You can hardly read the next lines. And that is not only because of the strike-through, but it's also because we have totally different stuff here that is not really related. Again, let's go through it one by one. If you want to emphasize a certain sentence, make it a paragraph of its own, even if it's only a single sentence, there's nothing wrong with that. If it's a step in a procedure, or if it's something the user must not miss, then it's definitely a paragraph of its own. So white space before and white space after helps to focus the attention. It separates the different sections. And again, it helps you to break the content into the different chunks that I was talking about earlier. And now I'm coming back to plain language. Avoid interruptions. Last year I was at a conference that is called Write the Docs in Prague. And there was a guy who gave a very interesting talk about how our mind works. And as most of you developers, think of our brain as a compiler, or think of your documentation like code. The code needs to be readable, or our brain needs to be able to compile it. And in order to make that simple, of course, you can understand. Just look at the sentence. There are not, however, marked as installed. However, there are not marked as installed. It's not a big difference. Everybody here can understand both sentences. But you will surely agree that the second sentence is simpler to understand. Because you're not interrupting the train of thought. Try to avoid this wherever possible. The next, the same goes for fragile verbs. Shut the server down. No, shut down the server. It's as simple as that. Even if it only takes a microsecond, if you only save a microsecond, even if it only makes this single sentence, it's a tiny bit easier to understand. There's a lot of potential. And they actually made tests when it comes to understanding or the reading speed for a certain paragraph. There's so much that you can gain with it. Yeah, think again, like a compiler, you're optimizing your code, basically. Then please use real-word verbs. That's something that especially the developers often do. SSH into the administration node. That's a real-word sentence in a pull request from a developer. Often changed it to connect to the administration node using SSH. This also has the nice little benefit that you avoid the capital SSH. I mean, the command on the command line is called SSH lowercase at the beginning of the sentence. You're running into a problem. If you write it lowercase at the beginning, it looks stupid. Again, tiny, tiny little difference, but don't use, I mean, know that if you're familiar with a certain piece of technology, it's very common to use program names as verbs, especially, I mean, in the English language, you can turn everything into a verb, right? We can't do this in German, but in English you can do this. Please don't. Stick to simple verbs, stick to real verbs that everybody knows. And last but not least, order matters. We have two sentences here. Refer to suzer.com. slash doc for more information or for more information. Oh, there's actually a capital R that shouldn't be there. For more information, refer to... So why is the second one better? Because you start reading. In the first half of the sentence, you see what it's about for more information. And in the second half, go there. I mean, it's, again, it's one of these tiny little differences that speed up compiling in your brain by a microsecond. And I'm almost through. Oh, I'm quicker than expected, but that leaves us more time for a Q&A. Last but not least, take your time. Write a draft, sleep over it, read it, or even better, have somebody else read it, and then edit it. You know Stephen King. He's a famous author, and he once said to write as human to edit is divine. The longer you stare at a text, the harder it gets. Or the longer you work on it, the harder it gets. Sleep over it. Usually there's this 80-20 rule. You can make a draft that covers 80% of the information, or that is 80% good. You only need to improve the last 20%. And this can be very, very, very hard. So take your time. Do something else. Start working on something else. Write the second chapter, third chapter, whatever. You can even leave the text aside for a week. It's actually better to look at the text after a week, and then you think, oh, what did I write there? So take your time, and that should help you to solve most of the problems. All right. That's the six basic rules. We could make it even more rules, but that's enough, and I think that's pretty universal. Are there any questions? Rule number one was... Oops, sorry. Change the perspective. Are you a developer? Formerly. Okay. You're a former... Formerly developer. Okay. The thing is, if you were a developer, don't look at your program from a developer's perspective. On the one hand, you're the person who best knows this program, therefore you are the best person to document it. But on the other hand, you are the worst person to document it because you are the bad person to know it by heart. You know the inner workings, you know what's under the hood, you know this perspective, and changing the perspective is... That's why it's rule number one. It's the hardest part sometimes, and it's the most basic part. If you don't get this right, if you don't know your target audience, know who you are writing for. If you don't know that, then you have no idea. If it's easy, if you're writing an API documentation, then it's easy. You're a developer, you are writing for other developers, but if you're writing for end users, that can often become a sum for developers. And that's why, in a perfect world, or in big organizations at least, you don't have the developers writing the documentation, but you have dedicated documentation writers or technical writers, just as you have quality assurance. I mean, you're not supposed to test your own programs because you will always cheat. I recall once upon a time when I was still working at Collab Systems, we actually outsourced some testing to India. And, can I say the word click monkey? I know it's not politically correct, but these people there were not, I mean, they were professional testers, but they were by no means familiar with our software. And it's unbelievable how many problems or bugs they found just because they were not familiar with it. Just because they stick, they strictly stick to our instructions and we had just made certain assumptions. We had just skipped certain steps or we had just assumed that everybody would be connecting to the mail server over SSL and not over an unencrypted connection and yeah, suddenly that didn't work. We just tried to change the perspective or if you can't do that, yeah, try to get a real world user. If you have already written it, give it to a real world user and ask them for feedback. Does that cover or answer your question? Okay. Any other questions? Any other questions on other rules or on that world? How do you start creating the persona? So you basically interview the users or roll out surveys or just make assumptions and test if they are working with you? Frankly speaking, the question was how do you make up the personas or how do you create the personas? I actually I accidentally already gave the answers. In most situations they will be made up. I don't think that I think only very little projects have actual numbers or user surveys or something solid data that they can gather that's on this one. So they will just make people up. Usually you can think of certain roles. Don't think of personas as the first step but think of roles like the CIS admin the network engineer or whatever. And from that, personas are even more fine range than a role. The next step would be we are not thinking in terms of the CIS admin but we have the junior CIS admin and the senior or we have the CIS admin who used to be a Windows admin and just got his first training or so. That would be a valid persona but as a first step you just think about different roles and then you can make it more fine-grained. It would be nice if we all had that user data, if we all had surveys. I know that Infodoro, we did that. I know that other organizations I think Godzilla for example they do real world testing they test it with somebody said it's so simple even my grandmar can install it and they tested it on their grandmar. So if you have a grandmar who's willing to be your test animal then go for it. Dictionary or Translate? Great question! Translate for several previous projects and it would be so nice to have an operating system in every operating system the same now to be consistent. I'm going to repeat the question the people who are watching the stream so the question was is there a dictionary especially when it comes to translation I mean first of all it's consistency in the native language and then it's consistency in the translations you said you're a BSD translator ideally things would be consistent throughout programs, consistent throughout desktop environments consistent throughout operating systems unfortunately the world is not perfect everybody has their own terminology but at least within these projects you usually have consistency because they have some dictionaries I can show you some there are for example the GNOME translation guidelines which are very solid and then cover a lot of stuff then there are I think in XFCE we had the same well we had similar guidelines but we had difference we started from the GNOME guidelines but we worked them slightly I think at some point Ubuntu had their own guidelines I mean when it comes to German so Ubuntu always wanted to have this human touch and they were ducing their users instead of Z so that's something very German that doesn't work in English but it's just two different forms of addressing a user one is more formal and the other is more informal and in Ubuntu we are all French so they use the informal language the informal addressing the user in an informal way if you have a particular question I can show you some dictionaries but unfortunately there's not the one side fits all the dictionary that's why we have a recycling bin with a trash bin or yeah but there are some resources that are very valuable I think the ultimate resource is the IBM style guide that's just a giant dictionary it's been published for I have no idea how many years already it's just massive you can look up everything there there's also the global English style guide that is more into translation as well we have the SUSE documentation style guide which might help you as well yeah any other sources that I forgot and yes the plainlanguage.gov website that I mentioned earlier plainlanguage.gov plainlanguageoneword.gov that's one of the best online resources not necessarily printed resources but online resources is one of the best for plainlanguage in general not necessarily for technical writing but it already goes a long way I think are there any other questions if not I think we can just call it a day thanks everybody for showing up you all had a great first day of this vlog yeah and last but not the least it's a pleasure for me to be here even though I am no longer a blue guy but a green guy yeah it's great to be here I'm grateful to be back again by the way SUSE is still hiring questions if you're looking for a job we have over 300 open positions please talk to me thanks