Documentation: Do's and don'ts
CC Attribution 3.0 Germany:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal purpose as long as the work is attributed to the author in the manner specified by the author or licensor.
Strack, Sven
In the beginning we will learn why documentation is important and how it can help you and your customers. From here we will move on to the main topic of this talk. With the help of real world examples, we will discover the good, the bad and the ugly. This will cover items such as: - Header - Line-length - File-length - Wording - Audience - Consistency - Code examples - PEP8 and friends - Many more In the last part we will talk about structure, planning, helper tools and such. This talk will use real examples out of the Plone world, but it is not limited to it.
 Hello and welcome. I'm Bec and I'm now going to just again with interesting facts about documentation. And this is basically because first I don't want to give the talk at all, but then Victor convinced me that was really important. So basically, this are my findings in the training documentation because for the last eight weeks before this conference basically we were preparing the trainings and so we found out lots of interesting and funny or less funny stuff about documentation. And well, this talk is about how we improve that and what we find and why even we can see the reason why people did stuff, how they did it. These are maybe not the best solutions to work on documentation and we will explain that. So first around me I do that because everyone seems to do that. I'm working with PlonTemps 2006. I do documentation for Plon other projects since 2012 and I'm kind of involved in different communities who have to do this documentation that is mainly write the docs, API the docs and test the docs that the best of these three communities were doing lots of different things with documentation, how documentation is important for your company, how we test towards how we teach developers to write on documentation and stuff like that. And that's really important. I really like to complain. Most of the time it's not me personal and most of the time my communication is not really good but I made it because I'm German but I really, really like to complain. And then this is basically a picture from three weeks ago from the write the docs documentation in Prague and people don't know what it is. Write the docs is a series of conferences and meetups focused on all things related to software documentation and technical writing and test the docs. This is an output from CI integration. It's a spin off basically of write the docs and it's a really small community. It's at the moment something like 10 people and we have basically the theme write, drunk, edit, solve and test automated because we like automated testing of documentation and we do lots of tooling to make testing possible but also make our life easier for better tooling for writing documentation. And let me start with this claim. This is not limited to PLOAN. We will use examples from PLOAN but you can also translate them to Drupal, WordPress, your private software products, stuff like that. This talk is also not from the developer point of view because I'm not a developer so I do dev of stuff or documentation stuff. So this is more from our normal user let's say this documentation and experience documentation and there's so much to talk on. I can talk the whole day but we only cut a small list of things with some interesting issues. And this talk is heavily opinionated. Some thing I may say it's possible that you don't like that. And some people may recognize their own commits. It's possible. But no personal meant you're still awesome but I need some examples. And first we start with something positive. I want to thank to Fulfio and Thomas because for the training docs for example the public request about the theme documentation they were really glad it was a place to review. It was easy, fast, following style guides and stuff like that. If anyone should do that all the time we had the best documentation ever. Thank you. And now I like to get into my audience. Let's get over a few. Let's do Paul. Who actually here is writing documentation before they start coding? Raise your hands. Some people that's nice. Who has all the documentation included in the release process of their products? Some people even better. And who does quality insurance of the documentation before they release it? Some, some, there's hope. So all of you let's see about what we talk. We will cover really short why our documentation are important. It's really short because I told that already multiple times on multiple conferences. Then we will see some funky and funky as meaning as not that really great examples of our existing documentation and how people did stuff there. And later on we will talk about reasons why this was maybe not the best idea and we will also find out about solutions. And also one other really important part is we will talk about the sexy fact of documentation. Documentation can be user appealing. It's really important. Later on we have some things about tips, tricks and tooling to make your life and my life easier, basically. And of course the famous last words. So let's start with the importance of documentation. Why is documentation important? One thing that's really important basically is because it's important for the success of your software product. You can have a great product but if your documentation is not there at all or really, really bad, most of the time your users are not happy because they are not able to find stuff. They are annoyed when they are calling up your head desk or sending open tickets in your head desk and that's not nice and basically that means your user is not satisfied with your product. And this is especially for some developers. I'm really sorry but documentation isn't this day part of your marketing and product branding. It also will help you to do marketing and product branding. That meaning you can make money actually with it. So sometimes it's worth to spend extra time to have nice documentation. And if you have good documentation, it will also save you money because you are now code after five months later you may not remember why you wrote it like that. So it's not only safe in your money because you remember stuff and you can look up faster stuff. But also for example, you are less busy with answering user questions about things in the user interface what they cannot find or not understanding or you hire a new developer and he has to get up to speed. So hand over the documentation, this is our workflow, this is our documentation. Way easier and way faster than sitting for five weeks next to this person and explaining all the stuff and then you find out, oops, I can't remember why we are doing it like that. And this is my personal opinion. It always depends on the product. But basically if you have no docs for your product, your product is basically at least my opinion broken. With that, I mean, that doesn't necessarily mean you have to write always a book. Sometimes just, I mean, script can also be a product but then you need at least some documentation even if it's either comments in the code while you're doing that. I mean, like I said, it depends on what is your product in this case. And let's stay with a really funny tale of finding different kinds of plan documentations and enjoy the nice. I tried to use nice nature pictures to calm us all down because nature is important and quiet and peace are important. So let's talk some examples. You see the last bit and the really ugly examples. And yeah, like I said, no offense, it's not personal. So if you recognize your own commits, it's really not a personal thing. I still like you and hopefully you like me later. So this is now especially to to plan, but you can easily translate that also to markdown or if you use ASCII doc to read ASCII doc syntax or whatever. But I try to say here, he stuck attacks so as other markdown languages or markup languages, they have a syntax and the syntax are there basically to make sure you have later if you compile it to HTML or nice formatting and CSS is working and all the stuff. So it's like Python. You should know the code. You should know what you're writing. And you should use syntax linter in your editor. This for example is a classical mistake. I think I fixed that something like more than 300 times in the training documentation. It's basically you have to pay attention about spaces and tops. Otherwise, the women work. And the same as some people try to be really, really smart and include dot RST. Don't do that. I mean, it really comes down to if you write something and doesn't matter in which language, follow the rules about the syntax and the language. It's like Python. And Python use PEP8 or Flake8 or something else. Do the same in your editor with RST. And this seems less important, but actually this is one of the results why the training docs looked not that nice in the beginning because people thought they did it right, but sorry they did it wrong. And it took something like weeks to fix all this small stuff. So then links. Lots of time, I still see that people use click here. I mean, I know it's really short. You mean click here on this word or button and then you get there. That is nice, but it's really bad for your user. It's way cooler if you say something like check out our theme training, for example. Then the person who is reading the docs knows exactly where to end up in the documentation. Way better, way better for sale, by the way, also. Helps a lot. Yeah. Talk trees. Who doesn't know what talk trees are? Okay. Let's explain that first. Basically, talk trees in RST or markdown that create your table of content. And there are certain rules how you use talk trees. You can then, and spilt for example, you can use them with numbering, sort, follow with alphabet, stuff like that, or even hide them. But if you start writing the documentation, you should settle on one style. Don't make the styles. So here, for example, we have the result of two things. One thing is we had nested talk trees that we use in the main index of your whole documentation. We're starting five by the way. You use talk tree and then later on in some sub, sub, sub, sub document, you use again, number it in talk tree and then because how things build documentation, you get fancy, funny results and how the order works. We had this for really, really, it was really annoying to debug that. So don't do that. Think about from the beginning what kind of talk tree, what kind of table of content, how I want to see it for the user, follow the alphabet, do numbering, really important. Then this was the best one. Include. Include in documentation basically works like include in programming. The meaning I can include in my part of the documentation. I'm writing here for example, something about the theming. And then I need some stuff from JavaScript. Oh, there are documentation about JavaScript. Let's just include that piece because I'm lazy, I can include meaning I don't have to write it myself. That's basically the idea. The idea is not bad, but it's tricky to do because you can do it, but then basically I first to check the file which you want to include for different things like the tone of voice, how it is written, which kind of wording is used. Does it actually meet my audience? For example, it can be that I do my theming training is more for basic stuff or beginner, but I include a piece which is from JavaScript for hardcore JavaScript. We're working since two years full time with patterns and projects. And then you can have funny situations suddenly in your documentation for beginners, they're using words like I don't know, which are really specific for react patterns and you never ever explained that in your theming documentation because it's a theming for beginners. So what I want to say is if you use include, be really careful about tone of voice, file length. Does it meet my audience? Is it written in the same style? Do we use the same hidden types? Do people understand it or are there suddenly terminology or term that I never used before? All the stuff. It's better. The other important thing is you depend later on on the docs. Imagine half a year later someone is changing the JavaScript documentation and this file, what you include is moving. That would also mean your docs are breaking. So you can use it by, I say it's not a good idea. Then, heatings. Heatings are also fun. Here we see a classical header from the solar training. It's not fixed. Can someone tell me what's wrong here? Besides the RST syntax, which is one, two. Sorry? Yeah, that's RST, I do. Really good. This is basically not a heading that sets a novel. That's a kind of a story. I'm telling everything in one line. And even if I can see the point why the person tried to do that like that, it will not help. And it's really annoying for the user because it looks horrible. But also, a header is there to give you a really short overview of what's now the next couple of lines that's coming. This is way too long. And you also use headings in search. This will give you basically nothing or at least not a good result in the search. So I'm really, really sorry. And besides that, I've already told the RST syntax is bad. So the builds will anyway fail. And the other thing is you are mixing styles. If you do headings, we have to cover the later on, decide on one style. Meaning I use like sentences. Meaning I start with the capital letter or every first letter of my word is a capital letter. There are various ways and there's nothing wrong with rights. Everyone has a different opinion that I try to look that up. But Facebook is doing different from GitHub. GitHub is doing different from Google and Microsoft is yet again doing different. For example, in May it soon has, I don't know, 50 sites about that. So yeah, there is no right or wrong. But if you decide to one style, stick to one style through whole docs. This one was another really good one. Can someone tell me why that is maybe not a good idea? No? Yeah, there are a couple of things. First thing is someone tried to use RST syntax for an RST command on a header. Because this backslash basically means RST for things you mark or command. And that is not good, but who is searching for commands in a header? So it would be better to just name it site actions and then second line say it's a command. This is, I'm really sorry to say that, but that's a typical developer stuff. I can see the point from the form, three of a developer, for a normal header that's not the smartest way. And okay, that's certainly a bit strong. But also like I said before, my CI integration tells me this is wrong and will fail in red. I know it's hard to read. Yeah, but yeah. It's red. It's broken. And yeah, no, we don't like that. Sorry. And talk to me with this in Bristol, the rights Bristol conference a couple of years ago. Funny talk about documentation. There was all the top 10 of the most wrong written words. So you remember acquisition. It's still called acquisition. It's still the number one, but we have now from the training docs in number two as a word and not the number two. And this is where we start talking about consistency. I found, and that's not all. That's only the top list of how people write through the web, meaning TTV in the documentation. And this is, I'm really sorry that this completely confusing for you. That's the reason why you have a style. At first you define how you use it and then you use to the whole box. But besides, yeah, we're using lots of different styles of writing and some of them even with typos. Not that handy, let's say, because it can lead to confusions for users, especially if you sometimes use them even with underscores that can also mean, oh, it's certainly a command or what you mean. And let's tell you again, this is how we do it in Plone. This is how we decided to do it. This is in the style that please just follow it and make my life easier, which ultimately makes your life easier because I will less complain. And the next one, who's using the PEP 8 or whatever, PEP 8 thing for your Python code? It's really cool. Stick to it. Stick to it, please, but only for Python, not for documentation. Text or documentation in PEP 8 makes no sense at all. I'm really sorry. If you can configure your editor for PEP 8 for Python, you can also maybe hopefully are able to configure your editor for RST in this case. If you're not, ask me. I have examples for Wim, E-Max, Namor, Atom, Subline, Visual Code, whatever you use. And if I don't have them, I will create it for you. And this is from the deployment training. Can someone tell me why that is maybe not that handy or good? I know that you can. Yeah. It is if you structure by a time bank, it is probably readable on an editor. Thank you. Thank you. This is really, really hard to read even if you have to refute it. And here even though there are also typos in it, it is hard to read. It is hard to fix. It is hard to maintain. It is really, really annoying how to translate. So stop using PEP 8 and friends for text files. And now we're going to the cool part. The way to be happy is to have a good time. I'm going to start with the document. And the first thing that we do is we need to plan and we need to structure. Never, ever start writing documentation without thinking before what you actually want to do. So the first thing is, in my opinion, is define your audience. You really have to know your audience. Is your audience a developer? Is it the beginner? Is it someone who never worked with computer before? Is it the designer? So adjust your documentation to your audience. It's really, really important. We still need that in plan. Then also make a list of the topics in your training or in your certain documentation which you want to cover. You don't have to or you also can't cover everything. Make a list, make a structure of points and start with them. And also think about the order. It is better to think first about the order than later write whole parts and then moving them around. Also terms. If you use, it's also coming back to audience and structure, be clear and certain about your terms. Make sure you explain terms. If you use something like ZODB acquisition and all the stuff, make sure that you have a glossary where you link to and explain it. This is also going back to audience. If you write documentation for a developer, she may know already what acquisition is. But if you use the word acquisition in theming docs for some reason, make sure you explain it. Also requirements. Tell from the beginning the requirements people need to install it. Not hide somewhere beneath. Make from the beginning clear from that we need and you always can later extend information and documentation and other stuff. So in short, be really clear from the beginning. Address explicit audience. Talk to the audience. The other thing, give a short introduction in the beginning of the file. Like the next, we will talk now, we will explain now certain part of the thing or the content of this part of the documentation is. Because lots of time people scan over the files and they want to know in the beginning if that part interesting, if they include what they want or not. Point. Also this is really important because it's good for search engine optimization and stuff like that. And also it makes your doc way more appealing for the user. Now we will go to fighting. Use active voice. Like I said before, use good headings. Short sentences. One line, one sentence and one line usually around 120 or 100 signs. Not too long. People don't read that. They want to short sentences. If you search something short sentences. Don't write documents with thousands of lines that brings up the sexy factor. This is really motivating for users. Try to keep your document short and create more documents and be consistent with wording and terming. And yeah, create magic moments of the sexy factor. If you do training, for example, write training documentation, short white files like that, this is overwhelming for new users or anyway users. Make them short. Make short chapters and then in the end they have some kind of an aha moment and they are really happy that they are shift something and then moved on. Otherwise you will lose them in something like an hour or two. Then active voice. Make clear who is performing the action and then there are some examples what's good for active voice. It really, really, really makes a difference. I know active voice is hard. I also mess it up over time. But it's way, way, way better. Again, back to headings. I already mentioned that at least two times. Headings are important because they are used in search and people look at this part now covering what I mean. So makes them clear short and stand out that they are easy to scan. Star guide. I totally beginning using star guide. Actually I write something I start with for star guide. I usually test the docs for star guide. So that adds also efficiency for example for refuelling because you can have that automatically in CI integration. It creates also consistency. It is good for your branding of your company and stuff like that. So you really create a product and your name for yourself. And language. Language is important. Most of us are not native and new speakers. And everyone has different educations depending on culture, money and where they came from. Have that in mind if you write documentation. Documentation should be or training documentation should be understandable for all levels. It's really, really important especially if you are a native and new speaker that sometimes tend to forget that what is so make them approachable. First thing, nothing avoids certain words. Like in the training documentation I don't know how many times I remove just or easy. Of course if you are writing the training and doing that for years you know what you are doing and for you everything is super easy. I just start to write out. I just write this XML snippet or Python code and then it's done. But that is for you. But for you it is maybe for me really, really hard. And you take two minutes may take myself like two hours. So I avoid that word. It is not helping at all. I really do not think because it is unfriendly because the user may think I am less smart than other people that are so annoying. They are also not with things. Some people try to use them. But they sometimes create the impression of laziness or sometimes they are not careful to throw through and actually insulting or offensive or hurting. And okay it is hard to read. But examples are for example we are back on track or you are doing it too long. If you are native, maybe it is not that clear or in your culture it means a completely different thing. Be careful with that. Don't use them at all. English Prime, this is another one that is really good as I like that. English Prime can really lead to confusions of people. If you are not native, for example, it is always that we are right the whole thing. We are or who is, it is not always clear for everyone. So be clear and straight with the language. And weasel words. Who does not know what weasel words are? Weasel words are basically words which people use in writing to add something. Like it is really, really that I mean that. So weasel words are words of praises used to write being forthright. Weasel words basically used when the speaker wants to make it seem like there is an answer but I just add more words to make it look like more, even more important or stuff like that. So the list is actually really long. That are only the most found. It is really, like we had for example it is really easy to do that. It is not really easy. What is really easy? It is very cool that I can install that. It is cool that you can install it but what is very cool? I don't know. So, avoid them. That is also hard and I don't check strict on them but try to avoid them too. And the other one is dictatorship and discrimination. If you write, please think about your wording. Execute is not always that friendly. Also obviously in order, they are also not the really nicest words to use. And I just read a talk even on this conference where you still using master and slave. I mean, there are better words for that. All this annoying thing is blacklist and whitelist. On the other meaning, yes, on the whole sentence. And then, quote examples. Yeah, that was a good one. You remember the better than me. I remember that one example using what looked like very technical words. That was actually in the Mozilla documentation. There was pill all orphan to the Cuffries. Maybe not what you want to have as a corporate leader. So after my time is running out, quote examples. We all like to use quote examples in the documentation. It's fine but make sure they are wallet. Meaning they are wallet in your syntax language. In our case, that would be our structure text. Because of not highlighting is not working, your brakes falling and other stuff. And also make sure they are working. Some people just copy some lines and they use that. But people tend to do copy and paste. And then they are wondering why the example is not working or breaking. If you decide to only use a couple of lines, then make completely clear in the comment style for your language which the quote example is, like a hashtag or whatever, depends on the language, that this is not the full example. Say that to the people. And we are starting now to test the quote example, the documentation, Python examples against the paper and flake it and all the stuff to make sure that they are trying to improve our situation of quote examples. Which brings us to my love of the CI point. Since I kind of like CI integration. Basically, we have some rules. The rules apply to documentation as to code. Do not break the build. If you broke the build, fix this. Don't commit your broken build or don't merge a broken build. Dogs like code. Now for the trainer, a couple of times that even the build was broken, they merged it and then with the comments and get up, please fix it later because currently it's broken and giving me warnings. It's nice that you have these comments, but why you merge in the first place? If I dare to do that on Plankor, for example, I have to buy the next conference or sprint lots of beer and I apologize to lots and lots of people. The same goes for documentation. Fix it first and then merge. Configure your editor. This is hard to read, but this is my setup for writing RST. Like I said before, most of you have your editor configured for Python or for other languages or the stuff. You know, you can do the same for markdown or RST. So please, please do that. It will help you a lot. This is, for example, I have lots of linters for wording and grammar and I have SpadeShake and I have automatically built the file I'm working on in the CSS of Plonedocsorg that I can actually see the file in the right CSS and which brings another next point, tools to make your life and my life easier and better. First, we start with the editor. Use linters. Use linters for us, Tshake. Use one for SpadeShake. They are also grammar shake really important. And for writing guidelines at all, they have grammar checks, but they have also like head in way, which is telling you that if you replace that word with another word, it's better. You can do the same. What we use on CI and use there, it's basically a style guide. I have my style guide hooked up in my editor. If I use one term, basically, a style guide is checking already in my editor and telling me it's when you are wrong. And also, linters for code examples. Meaning, for Plonedocsorg, it may be easier because you already have your editor setup for Plonedocsorg or Python. It will be help. And also, you can do HTML previews. If you think just CSS preview is not enough, you can also have a shortcut in your editor to do checks with, for example, HTML test of HTML proofer, which basically will check even if your HTML is valid and according to HTML5 guidelines and stuff like that, which is really, really nice. And now we move to the demo time. How is that working? How can I swipe? This is my editor. I'm sorry. I use Atom for writing, but it's also working for record, sublime, Wim, e-max, visual code, whatever fancy editor you like. And here, for example, you can see I have my 3-year-old open and I work on Docs to Plonor, asking for help. And then, basically, you see my editor. You see, really, is that working? Yeah. If I click that, it's giving me all my linters and telling me this is not good or few is not good and stuff like that. So I immediately know, maybe I want to change that. But now, I also want to see how that looks like basically in Runnert HTML, because it's always interesting to know. And I just can't fire up my editor, which I, Neton, I basically wrote yesterday. And this is giving me only this document, Runnert in HTML, with the CSS of Docs to Plonor, so I can see immediately if it looks like OK or not. So if I want to see more and make it bigger, and this is actually kind of nice, at least for me, I like it, because it helps a lot. And also, it saves time because I'm sorry if you're still using Spinks and every time you do make HTML, it will take a long time and it's really annoying because you only want to see this one file and not the whole documentation, right? And we go back. And further with tooling, it's my new best friend, by the way. Content structure, yeah, create personas, create personas, meaning I want to write theming documentation for new developers. You never, ever work with Plon what they have to take care of. You can also start with mind maps, create a mind map about exactly the order of stuff. Further on with tooling for writing, use templates. Templates are really nice because you speak to your prior FHRs, T templates, which give me automatic the writer, header style and description style, so I just have to fill it in. That saves me every time already a couple of minutes because I have already the base structure of my document set up. The same with glossaries, rules at the moment, cookie cutter template was creating that, re-write it maybe to Mr. Bob, but it's really, I really tried, it's really, really nice. Use intros and also important at the end of the file, use a recap and tell the people again, now we talked about that, the result is you should have learned that, blah, blah, blah. And for media, include media, this also gains sexy factor, make your videos and docs appealing, use pictures, use video if possible, use askinamers or animated gifs or even drawings, doesn't matter, but if you have something that adds value to your documentation and breaks through this boring long text file, use it. And the most important tooling with that, what I like to call the Unia interface, who knows what I mean with it. Okay, I thought so. You can do lots of stuff with automatic testing and linux and whatever, that meaning you have no typos, you have correct grammar and all the stuff, but there's one of the things if the user is not understanding what you wrote at all. So with Unia interface, maybe it means let real people test your documentation. The best is you are supposed to be part of the audience and try the documentation where you have to speed up. And then continuous integration, since I'm involved in test docs, we like continuous integration. We do all that what I just mentioned, automatically in CI. So we do link check, page check, RST check, line length, file length, style height check, top tree check, HTML validation, and image checks, automatically in CI. So it's really, really helpful. The other thing is karma testing. Karma testing means you write in a document, you make a pull request. The first check on only your pull request, and if your pull request is green, you get the front digreter from, hey, cool, thanks for your contribution and so on and so on. And the second test is running on the whole docs, and then you get a mail from, we're really thankful for your contribution. Maybe you also want to change the other part, but nothing is more annoying and demotivating for users. If you write on one small piece of the documentation, and this part is okay, but the test fades because someone else, somewhere else in the doc there is some broken stuff. That's what we call karma testing. And in short, we plan and structure carefully, know your audience, use the right words, and test, test, and again, test and even test more. And we have also some announcements. So, 4th of December, we have the first conference for API docs. That's a one-day conference about writing and testing API documentation. It's in Amsterdam. It's really, really cool. And we will cover topics such as why is Swagger back and sucks on our levels from the documentarian point of view, not from the developer point of view. It's important difference. And then we have next year at, well, I will do it later. And then we have also at Foster, next year in January, we have the first test docs. We have a death room at Foster. And we will death the whole day of talking about testing documentation, tooling for documentation, and stuff like that. And now I'm done. Thank you. Thank you very much. Do you have any links for the tools you are using, like grammar checking and whatever? Yes, I will upload them and tweet that to and link to all the blog posts and explanations and how tos and stuff like that. Any more questions? No? And thank you very much. And just a reminder from my side, we will take a picture later after the next talk in front of the building at the stairs. So please make sure that you all show up there. Thank you.
 Hello and welcome. I'm Bec and I'm now going to just again with interesting facts about  documentation. And this is basically because first I don't want to give the talk at all,  but then Victor convinced me that was really important. So basically, this are my findings  in the training documentation because for the last eight weeks before this conference  basically we were preparing the trainings and so we found out lots of interesting and  funny or less funny stuff about documentation. And well, this talk is about how we improve  that and what we find and why even we can see the reason why people did stuff, how they  did it. These are maybe not the best solutions to work on documentation and we will explain  that. So first around me I do that because everyone seems to do that. I'm working with  PlonTemps 2006. I do documentation for Plon other projects since 2012 and I'm kind of  involved in different communities who have to do this documentation that is mainly write  the docs, API the docs and test the docs that the best of these three communities were  doing lots of different things with documentation, how documentation is important for your company,  how we test towards how we teach developers to write on documentation and stuff like that.  And that's really important. I really like to complain. Most of the time it's not me  personal and most of the time my communication is not really good but I made it because I'm  German but I really, really like to complain. And then this is basically a picture from  three weeks ago from the write the docs documentation in Prague and people don't know what it is.  Write the docs is a series of conferences and meetups focused on all things related  to software documentation and technical writing and test the docs. This is an output from CI  integration. It's a spin off basically of write the docs and it's a really small community.  It's at the moment something like 10 people and we have basically the theme write, drunk,  edit, solve and test automated because we like automated testing of documentation and  we do lots of tooling to make testing possible but also make our life easier for better tooling  for writing documentation. And let me start with this claim. This is not limited to PLOAN.  We will use examples from PLOAN but you can also translate them to Drupal, WordPress,  your private software products, stuff like that. This talk is also not from the developer  point of view because I'm not a developer so I do dev of stuff or documentation stuff.  So this is more from our normal user let's say this documentation and experience documentation  and there's so much to talk on. I can talk the whole day but we only cut a small list  of things with some interesting issues. And this talk is heavily opinionated. Some thing  I may say it's possible that you don't like that. And some people may recognize their  own commits. It's possible. But no personal meant you're still awesome but I need some  examples. And first we start with something positive. I want to thank to Fulfio and Thomas  because for the training docs for example the public request about the theme documentation  they were really glad it was a place to review. It was easy, fast, following style guides  and stuff like that. If anyone should do that all the time we had the best documentation  ever. Thank you. And now I like to get into my audience. Let's get over a few. Let's do  Paul. Who actually here is writing documentation before they start coding? Raise your hands.  Some people that's nice. Who has all the documentation included in the release process of their products?  Some people even better. And who does quality insurance of the documentation before they  release it? Some, some, there's hope. So all of you let's see about what we talk. We will  cover really short why our documentation are important. It's really short because I told  that already multiple times on multiple conferences. Then we will see some funky and funky as  meaning as not that really great examples of our existing documentation and how people  did stuff there. And later on we will talk about reasons why this was maybe not the best  idea and we will also find out about solutions. And also one other really important part is  we will talk about the sexy fact of documentation. Documentation can be user appealing. It's  really important. Later on we have some things about tips, tricks and tooling to make your  life and my life easier, basically. And of course the famous last words. So let's start  with the importance of documentation. Why is documentation important? One thing that's  really important basically is because it's important for the success of your software  product. You can have a great product but if your documentation is not there at all  or really, really bad, most of the time your users are not happy because they are not able  to find stuff. They are annoyed when they are calling up your head desk or sending open  tickets in your head desk and that's not nice and basically that means your user is not  satisfied with your product. And this is especially for some developers. I'm really sorry but  documentation isn't this day part of your marketing and product branding. It also will  help you to do marketing and product branding. That meaning you can make money actually with  it. So sometimes it's worth to spend extra time to have nice documentation. And if you  have good documentation, it will also save you money because you are now code after five  months later you may not remember why you wrote it like that. So it's not only safe  in your money because you remember stuff and you can look up faster stuff. But also for  example, you are less busy with answering user questions about things in the user interface  what they cannot find or not understanding or you hire a new developer and he has to  get up to speed. So hand over the documentation, this is our workflow, this is our documentation.  Way easier and way faster than sitting for five weeks next to this person and explaining  all the stuff and then you find out, oops, I can't remember why we are doing it like  that. And this is my personal opinion. It always depends on the product. But basically  if you have no docs for your product, your product is basically at least my opinion broken.  With that, I mean, that doesn't necessarily mean you have to write always a book. Sometimes  just, I mean, script can also be a product but then you need at least some documentation  even if it's either comments in the code while you're doing that. I mean, like I said,  it depends on what is your product in this case. And let's stay with a really funny tale  of finding different kinds of plan documentations and enjoy the nice. I tried to use nice nature  pictures to calm us all down because nature is important and quiet and peace are important.  So let's talk some examples. You see the last bit and the really ugly examples. And  yeah, like I said, no offense, it's not personal. So if you recognize your own commits, it's  really not a personal thing. I still like you and hopefully you like me later. So this  is now especially to to plan, but you can easily translate that also to markdown or  if you use ASCII doc to read ASCII doc syntax or whatever. But I try to say here, he stuck  attacks so as other markdown languages or markup languages, they have a syntax and the  syntax are there basically to make sure you have later if you compile it to HTML or nice  formatting and CSS is working and all the stuff. So it's like Python. You should know  the code. You should know what you're writing. And you should use syntax linter in your editor.  This for example is a classical mistake. I think I fixed that something like more than  300 times in the training documentation. It's basically you have to pay attention about  spaces and tops. Otherwise, the women work. And the same as some people try to be really,  really smart and include dot RST. Don't do that. I mean, it really comes down to if you  write something and doesn't matter in which language, follow the rules about the syntax  and the language. It's like Python. And Python use PEP8 or Flake8 or something else. Do the  same in your editor with RST. And this seems less important, but actually this is one of  the results why the training docs looked not that nice in the beginning because people  thought they did it right, but sorry they did it wrong. And it took something like weeks  to fix all this small stuff. So then links. Lots of time, I still see that people use  click here. I mean, I know it's really short. You mean click here on this word or button  and then you get there. That is nice, but it's really bad for your user. It's way cooler  if you say something like check out our theme training, for example. Then the person who  is reading the docs knows exactly where to end up in the documentation. Way better, way  better for sale, by the way, also. Helps a lot. Yeah. Talk trees. Who doesn't know what  talk trees are? Okay. Let's explain that first. Basically, talk trees in RST or markdown that  create your table of content. And there are certain rules how you use talk trees. You  can then, and spilt for example, you can use them with numbering, sort, follow with  alphabet, stuff like that, or even hide them. But if you start writing the documentation,  you should settle on one style. Don't make the styles. So here, for example, we have  the result of two things. One thing is we had nested talk trees that we use in the main  index of your whole documentation. We're starting five by the way. You use talk tree and then  later on in some sub, sub, sub, sub document, you use again, number it in talk tree and  then because how things build documentation, you get fancy, funny results and how the order  works. We had this for really, really, it was really annoying to debug that. So don't  do that. Think about from the beginning what kind of talk tree, what kind of table of content,  how I want to see it for the user, follow the alphabet, do numbering, really important.  Then this was the best one. Include. Include in documentation basically works like include  in programming. The meaning I can include in my part of the documentation. I'm writing  here for example, something about the theming. And then I need some stuff from JavaScript.  Oh, there are documentation about JavaScript. Let's just include that piece because I'm lazy,  I can include meaning I don't have to write it myself. That's basically the idea. The  idea is not bad, but it's tricky to do because you can do it, but then basically I first  to check the file which you want to include for different things like the tone of voice,  how it is written, which kind of wording is used. Does it actually meet my audience?  For example, it can be that I do my theming training is more for basic stuff or beginner,  but I include a piece which is from JavaScript for hardcore JavaScript. We're working since  two years full time with patterns and projects. And then you can have funny situations suddenly  in your documentation for beginners, they're using words like I don't know, which are really  specific for react patterns and you never ever explained that in your theming documentation  because it's a theming for beginners. So what I want to say is if you use include, be really  careful about tone of voice, file length. Does it meet my audience? Is it written in the  same style? Do we use the same hidden types? Do people understand it or are there suddenly  terminology or term that I never used before? All the stuff. It's better. The other important  thing is you depend later on on the docs. Imagine half a year later someone is changing  the JavaScript documentation and this file, what you include is moving. That would also  mean your docs are breaking. So you can use it by, I say it's not a good idea. Then,  heatings. Heatings are also fun. Here we see a classical header from the solar training.  It's not fixed. Can someone tell me what's wrong here? Besides the RST syntax, which  is one, two. Sorry? Yeah, that's RST, I do. Really good. This is basically not a heading  that sets a novel. That's a kind of a story. I'm telling everything in one line. And even  if I can see the point why the person tried to do that like that, it will not help. And  it's really annoying for the user because it looks horrible. But also, a header is there  to give you a really short overview of what's now the next couple of lines that's coming.  This is way too long. And you also use headings in search. This will give you basically nothing  or at least not a good result in the search. So I'm really, really sorry. And besides that,  I've already told the RST syntax is bad. So the builds will anyway fail. And the other  thing is you are mixing styles. If you do headings, we have to cover the later on, decide  on one style. Meaning I use like sentences. Meaning I start with the capital letter or  every first letter of my word is a capital letter. There are various ways and there's  nothing wrong with rights. Everyone has a different opinion that I try to look that  up. But Facebook is doing different from GitHub. GitHub is doing different from Google and  Microsoft is yet again doing different. For example, in May it soon has, I don't know,  50 sites about that. So yeah, there is no right or wrong. But if you decide to one style,  stick to one style through whole docs. This one was another really good one. Can someone  tell me why that is maybe not a good idea? No? Yeah, there are a couple of things. First  thing is someone tried to use RST syntax for an RST command on a header. Because this  backslash basically means RST for things you mark or command. And that is not good, but  who is searching for commands in a header? So it would be better to just name it site  actions and then second line say it's a command. This is, I'm really sorry to say that, but  that's a typical developer stuff. I can see the point from the form, three of a developer,  for a normal header that's not the smartest way. And okay, that's certainly a bit strong.  But also like I said before, my CI integration tells me this is wrong and will fail in red.  I know it's hard to read. Yeah, but yeah. It's red. It's broken. And yeah, no, we don't  like that. Sorry. And talk to me with this in Bristol, the  rights Bristol conference a couple of years ago. Funny talk about documentation. There  was all the top 10 of the most wrong written words. So you remember acquisition. It's still  called acquisition. It's still the number one, but we have now from the training docs  in number two as a word and not the number two. And this is where we start talking about  consistency. I found, and that's not all. That's only the top list of how people write  through the web, meaning TTV in the documentation. And this is, I'm really sorry that this completely  confusing for you. That's the reason why you have a style. At first you define how you  use it and then you use to the whole box. But besides, yeah, we're using lots of different  styles of writing and some of them even with typos. Not that handy, let's say, because  it can lead to confusions for users, especially if you sometimes use them even with underscores  that can also mean, oh, it's certainly a command or what you mean. And let's tell you again,  this is how we do it in Plone. This is how we decided to do it. This is in the style  that please just follow it and make my life easier, which ultimately makes your life easier  because I will less complain. And the next one, who's using the PEP 8 or whatever, PEP  8 thing for your Python code? It's really cool. Stick to it. Stick to it, please, but  only for Python, not for documentation. Text or documentation in PEP 8 makes no sense at  all. I'm really sorry. If you can configure your editor for PEP 8 for Python, you can  also maybe hopefully are able to configure your editor for RST in this case. If you're  not, ask me. I have examples for Wim, E-Max, Namor, Atom, Subline, Visual Code, whatever  you use. And if I don't have them, I will create it for you. And this is from the deployment  training. Can someone tell me why that is maybe not that handy or good? I know that  you can. Yeah.  It is if you structure by a time bank, it is probably readable on an editor.  Thank you. Thank you. This is really, really hard to read even if you have to refute it.  And here even though there are also typos in it, it is hard to read. It is hard to fix.  It is hard to maintain. It is really, really annoying how to translate. So stop using PEP  8 and friends for text files. And now we're going to the cool part. The way to be happy  is to have a good time. I'm going to start with the document. And the first thing that  we do is we need to plan and we need to structure. Never, ever start writing documentation without  thinking before what you actually want to do. So the first thing is, in my opinion, is  define your audience. You really have to know your audience. Is your audience a developer?  Is it the beginner? Is it someone who never worked with computer before? Is it the designer?  So adjust your documentation to your audience. It's really, really important. We still need  that in plan. Then also make a list of the topics in your training or in your certain  documentation which you want to cover. You don't have to or you also can't cover everything.  Make a list, make a structure of points and start with them. And also think about the  order. It is better to think first about the order than later write whole parts and then  moving them around. Also terms. If you use, it's also coming back to audience and structure,  be clear and certain about your terms. Make sure you explain terms. If you use something  like ZODB acquisition and all the stuff, make sure that you have a glossary where you link  to and explain it. This is also going back to audience. If you write documentation for  a developer, she may know already what acquisition is. But if you use the word acquisition in  theming docs for some reason, make sure you explain it. Also requirements. Tell from the  beginning the requirements people need to install it. Not hide somewhere beneath. Make  from the beginning clear from that we need and you always can later extend information  and documentation and other stuff. So in short, be really clear from the beginning. Address  explicit audience. Talk to the audience. The other thing, give a short introduction in  the beginning of the file. Like the next, we will talk now, we will explain now certain  part of the thing or the content of this part of the documentation is. Because lots of time  people scan over the files and they want to know in the beginning if that part interesting,  if they include what they want or not. Point. Also this is really important because it's  good for search engine optimization and stuff like that. And also it makes your doc way  more appealing for the user. Now we will go to fighting. Use active voice. Like I said  before, use good headings. Short sentences. One line, one sentence and one line usually  around 120 or 100 signs. Not too long. People don't read that. They want to short sentences.  If you search something short sentences. Don't write documents with thousands of lines that  brings up the sexy factor. This is really motivating for users. Try to keep your document  short and create more documents and be consistent with wording and terming. And yeah, create  magic moments of the sexy factor. If you do training, for example, write training documentation,  short white files like that, this is overwhelming for new users or anyway users. Make them short.  Make short chapters and then in the end they have some kind of an aha moment and they are  really happy that they are shift something and then moved on. Otherwise you will lose  them in something like an hour or two. Then active voice. Make clear who is performing  the action and then there are some examples what's good for active voice. It really, really,  really makes a difference. I know active voice is hard. I also mess it up over time. But  it's way, way, way better. Again, back to headings. I already mentioned that at least  two times. Headings are important because they are used in search and people look at  this part now covering what I mean. So makes them clear short and stand out that they are  easy to scan. Star guide. I totally beginning using star guide. Actually I write something  I start with for star guide. I usually test the docs for star guide. So that adds also  efficiency for example for refuelling because you can have that automatically in CI integration.  It creates also consistency. It is good for your branding of your company and stuff like  that. So you really create a product and your name for yourself. And language. Language is  important. Most of us are not native and new speakers. And everyone has different educations  depending on culture, money and where they came from. Have that in mind if you write  documentation. Documentation should be or training documentation should be understandable  for all levels. It's really, really important especially if you are a native and new speaker  that sometimes tend to forget that what is so make them approachable.  First thing, nothing avoids certain words. Like in the training documentation I don't  know how many times I remove just or easy. Of course if you are writing the training and  doing that for years you know what you are doing and for you everything is super easy.  I just start to write out. I just write this XML snippet or Python code and then it's done.  But that is for you. But for you it is maybe for me really, really hard. And you take two  minutes may take myself like two hours. So I avoid that word. It is not helping at all.  I really do not think because it is unfriendly because the user may think I am less smart  than other people that are so annoying. They are also not with things. Some people try  to use them. But they sometimes create the impression of laziness or sometimes they are  not careful to throw through and actually insulting or offensive or hurting. And okay  it is hard to read. But examples are for example we are back on track or you are doing it too  long. If you are native, maybe it is not that clear or in your culture it means a completely  different thing. Be careful with that. Don't use them at all.  English Prime, this is another one that is really good as I like that. English Prime can  really lead to confusions of people. If you are not native, for example, it is always  that we are right the whole thing. We are or who is, it is not always clear for everyone.  So be clear and straight with the language. And weasel words. Who does not know what weasel  words are? Weasel words are basically words which people use in writing to add something.  Like it is really, really that I mean that. So weasel words are words of praises used  to write being forthright. Weasel words basically used when the speaker wants to make it seem  like there is an answer but I just add more words to make it look like more, even more  important or stuff like that. So the list is actually really long. That are only the  most found. It is really, like we had for example it is really easy to do that. It is  not really easy. What is really easy? It is very cool that I can install that. It is  cool that you can install it but what is very cool? I don't know. So, avoid them. That is  also hard and I don't check strict on them but try to avoid them too. And the other one  is dictatorship and discrimination. If you write, please think about your wording. Execute  is not always that friendly. Also obviously in order, they are also not the really nicest  words to use. And I just read a talk even on this conference where you still using master  and slave. I mean, there are better words for that. All this annoying thing is blacklist  and whitelist.  On the other meaning, yes, on the whole sentence.  And then, quote examples. Yeah, that was a good one. You remember the better than me.  I remember that one example using what looked like very technical words. That was actually  in the Mozilla documentation. There was pill all orphan to the Cuffries. Maybe not what  you want to have as a corporate leader.  So after my time is running out, quote examples. We all like to use quote examples in the  documentation. It's fine but make sure they are wallet. Meaning they are wallet in your  syntax language. In our case, that would be our structure text. Because of not highlighting  is not working, your brakes falling and other stuff. And also make sure they are working.  Some people just copy some lines and they use that. But people tend to do copy and paste.  And then they are wondering why the example is not working or breaking. If you decide  to only use a couple of lines, then make completely clear in the comment style for your language  which the quote example is, like a hashtag or whatever, depends on the language, that  this is not the full example. Say that to the people.  And we are starting now to test the quote example, the documentation, Python examples  against the paper and flake it and all the stuff to make sure that they are trying to  improve our situation of quote examples. Which brings us to my love of the CI point. Since  I kind of like CI integration. Basically, we have some rules. The rules apply to documentation  as to code. Do not break the build. If you broke the build, fix this. Don't commit your  broken build or don't merge a broken build. Dogs like code. Now for the trainer, a couple  of times that even the build was broken, they merged it and then with the comments and get  up, please fix it later because currently it's broken and giving me warnings. It's nice  that you have these comments, but why you merge in the first place? If I dare to do  that on Plankor, for example, I have to buy the next conference or sprint lots of beer  and I apologize to lots and lots of people. The same goes for documentation. Fix it first  and then merge. Configure your editor. This is hard to read, but this is my setup for  writing RST. Like I said before, most of you have your editor configured for Python or  for other languages or the stuff. You know, you can do the same for markdown or RST. So  please, please do that. It will help you a lot. This is, for example, I have lots of  linters for wording and grammar and I have SpadeShake and I have automatically built  the file I'm working on in the CSS of Plonedocsorg that I can actually see the file in the right  CSS and which brings another next point, tools to make your life and my life easier  and better. First, we start with the editor. Use linters. Use linters for us, Tshake. Use  one for SpadeShake. They are also grammar shake really important. And for writing guidelines  at all, they have grammar checks, but they have also like head in way, which is telling  you that if you replace that word with another word, it's better. You can do the same. What  we use on CI and use there, it's basically a style guide. I have my style guide hooked  up in my editor. If I use one term, basically, a style guide is checking already in my editor  and telling me it's when you are wrong. And also, linters for code examples. Meaning,  for Plonedocsorg, it may be easier because you already have your editor setup for Plonedocsorg  or Python. It will be help. And also, you can do HTML previews. If you think just CSS  preview is not enough, you can also have a shortcut in your editor to do checks with,  for example, HTML test of HTML proofer, which basically will check even if your HTML is valid  and according to HTML5 guidelines and stuff like that, which is really, really nice. And  now we move to the demo time. How is that working? How can I swipe? This is my editor.  I'm sorry. I use Atom for writing, but it's also working for record, sublime, Wim, e-max,  visual code, whatever fancy editor you like. And here, for example, you can see I have  my 3-year-old open and I work on Docs to Plonor, asking for help. And then, basically,  you see my editor. You see, really, is that working? Yeah. If I click that, it's giving  me all my linters and telling me this is not good or few is not good and stuff like that.  So I immediately know, maybe I want to change that. But now, I also want to see how that  looks like basically in Runnert HTML, because it's always interesting to know. And I just  can't fire up my editor, which I, Neton, I basically wrote yesterday. And this is giving  me only this document, Runnert in HTML, with the CSS of Docs to Plonor, so I can see immediately  if it looks like OK or not. So if I want to see more and make it bigger, and this is actually  kind of nice, at least for me, I like it, because it helps a lot. And also, it saves  time because I'm sorry if you're still using Spinks and every time you do make HTML, it  will take a long time and it's really annoying because you only want to see this one file  and not the whole documentation, right? And we go back. And further with tooling, it's  my new best friend, by the way. Content structure, yeah, create personas, create personas, meaning  I want to write theming documentation for new developers. You never, ever work with  Plon what they have to take care of. You can also start with mind maps, create a mind map  about exactly the order of stuff. Further on with tooling for writing, use templates.  Templates are really nice because you speak to your prior FHRs, T templates, which give  me automatic the writer, header style and description style, so I just have to fill it in. That  saves me every time already a couple of minutes because I have already the base structure of  my document set up. The same with glossaries, rules at the moment, cookie cutter template  was creating that, re-write it maybe to Mr. Bob, but it's really, I really tried, it's  really, really nice. Use intros and also important at the end of the file, use a recap and tell  the people again, now we talked about that, the result is you should have learned that,  blah, blah, blah. And for media, include media, this also gains sexy factor, make your  videos and docs appealing, use pictures, use video if possible, use askinamers or animated  gifs or even drawings, doesn't matter, but if you have something that adds value to your  documentation and breaks through this boring long text file, use it. And the most important  tooling with that, what I like to call the Unia interface, who knows what I mean with  it. Okay, I thought so. You can do lots of stuff with automatic testing and linux and  whatever, that meaning you have no typos, you have correct grammar and all the stuff,  but there's one of the things if the user is not understanding what you wrote at all.  So with Unia interface, maybe it means let real people test your documentation. The best  is you are supposed to be part of the audience and try the documentation where you have to  speed up. And then continuous integration, since I'm involved in test docs, we like  continuous integration. We do all that what I just mentioned, automatically in CI. So  we do link check, page check, RST check, line length, file length, style height check, top  tree check, HTML validation, and image checks, automatically in CI. So it's really, really  helpful. The other thing is karma testing. Karma testing means you write in a document,  you make a pull request. The first check on only your pull request, and if your pull request  is green, you get the front digreter from, hey, cool, thanks for your contribution and  so on and so on. And the second test is running on the whole docs, and then you get a mail  from, we're really thankful for your contribution. Maybe you also want to change the other part,  but nothing is more annoying and demotivating for users. If you write on one small piece  of the documentation, and this part is okay, but the test fades because someone else, somewhere  else in the doc there is some broken stuff. That's what we call karma testing. And in  short, we plan and structure carefully, know your audience, use the right words, and test,  test, and again, test and even test more. And we have also some announcements. So, 4th  of December, we have the first conference for API docs. That's a one-day conference  about writing and testing API documentation. It's in Amsterdam. It's really, really cool.  And we will cover topics such as why is Swagger back and sucks on our levels from the documentarian  point of view, not from the developer point of view. It's important difference. And then  we have next year at, well, I will do it later. And then we have also at Foster, next year  in January, we have the first test docs. We have a death room at Foster. And we will  death the whole day of talking about testing documentation, tooling for documentation,  and stuff like that. And now I'm done. Thank you.  Thank you very much. Do you have any links for the tools you are using, like grammar  checking and whatever? Yes, I will upload them and tweet that to and link to all the  blog posts and explanations and how tos and stuff like that.  Any more questions? No? And thank you very much. And just a reminder from my side, we  will take a picture later after the next talk in front of the building at the stairs.  So please make sure that you all show up there. Thank you.
Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_0_131.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_132_251.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_252_431.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_432_683.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_684_1835.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_1836_3383.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_3384_3959.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_3960_4823.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_4824_12899.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_12900_13751.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_13752_14387.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_14388_14507.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_14508_15323.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_15324_16055.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_16056_16235.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_16236_16367.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_16368_17147.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_17148_18659.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_18660_25307.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_25308_26567.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_26568_27131.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_27132_27479.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_27480_27551.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_27552_27659.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_27660_28283.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_28284_29483.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_29484_30143.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_30144_30251.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_30252_30839.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_30840_31895.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_31896_32267.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_32268_32435.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_32436_35051.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_35052_35519.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_35520_36107.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_36108_39419.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_39420_42587.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_42588_42683.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_42684_43823.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_43824_44675.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_44676_46295.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_46296_49067.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_49068_50531.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_50532_50843.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_50844_51683.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_51684_54011.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_54012_54095.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_54096_54803.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_54804_54995.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_54996_55067.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_55068_55151.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_55152_55703.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_55704_55763.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_55764_55871.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_55872_56543.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_56544_56591.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_56592_57155.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_57156_57515.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_57516_58295.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_58296_60587.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_60588_63395.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_63396_64847.png Day_3__Sven_Strack_-_Documentation__Do_s_and_don_t_N4kyGM3IYfo_64848_64967.png