 Thank you very much everybody for coming. I didn't expect such a large audience Although I see some people from my team. So if you have any questions Those from my team expect I would have left them your way I would like to start by saying if you were to vote myself. My name is Jeremy. I'm one of the managers in content services I've been with right at since 2010 and I started as a technical writer So a lot of what I'll be talking about is still dear to me and I had chance to experience part of it Myself although I still feel that I'm lucky as manager because I'm learning from my talented team or much smarter than me I don't have a slight for cut take Attracts in April 2016 in the same team and this is the best job my life Awesome, thank you So I wanted to start by just qualifying few things about documentation if you were listening to mark move out We very likely are tired of that But I just want to quickly clarify a few things because documentation is a broad term when people say documentation You imagine absolutely anything that is written documented with video audio content anything and Product documentation teams you really focus on a tiny little piece of it. I copied this from our internal module It's our mission and our mission is to write documentation that helps customers what they want to accomplish If you work with Linux, there is no shortage of documentation. There's absolutely no shortage of documentation There's so much information everywhere else and you are very likely able to find Information about what you would like to do The difficult part is finding information that you need to accomplish what you want to do with it or figuring it out yourself So what we do is we write documentation that is targeted at customers people who pay for our products People who use our products in production to achieve something amazing on their own We are paid to learn our products I don't believe that you can write documentation that is targeted to customer without having a clue of what you're writing about We communicate with other teams because we are not in direct contact with our customers So we use our teams to figure out what our customers are doing with our products so that we can then figure out what to write about I don't have it on the slide, but when I have a new hire I usually describe our role and hope that I won't scare them as we suffer So that nobody else ever has to again So we figure out what is needed and try to compile the documentation in a way that makes sense and hopefully it's easy to read We how many of you are tech writers at the moment? What we don't do we are not translators We are not editors and we unfortunately don't write manual pages, but we have a good reason I think that the helpers are not there at that That's our excuse We are also our team is not just technical writers. We have a whole lot of other roles. I will not Spend too much time on this one of them is of course cardiac with my boss Always fun to present it from my boss. I Want to start I want to show a few things how we evolved our documentation And I think that the important thing is to start not necessarily at the very beginning But keep a little brief look at the history. So we're going to impress the next our biggest documentation I think still on our portal We had 44 46 books 38 keep repositories all written in the book XML which people hate and I Will point at those 46 books. So if you look at our documentation, this is what we traditionally expect if you look at our The list of the books I don't think that you will notice anything wrong because there's Installation guides system administrators guide networking guide security guide and all of that in reality when you are doing absolutely anything with Pretty much any piece of software You need to read to or more of these books to find all the information that help you accomplish what you're trying to accomplish So we're doing that we were doing terribly there If we zoom in and look at the one guy, this is Criticizing my content. I am responsible for this. This is my fault but we tried to focus on customers and we thought about things like topic-based offering and use cases and Stuff like that, but we failed because we still focus just on individual components. So it's if you Just want to learn about system D great There's a huge chapter about that and you learn everything how to use system D in isolation Chances are you don't need to learn the whole system the chances are you just need two commands that you need to Run to enable and to start and enable a service and forget about the rest So we're wasting your time by making you navigate our documentation so that you can figure out All you needed in the first place was those two commands Also, the books were big books are big and finding that information is not as trivial as it should be I Summit up here. We have artificial isolated information in reality If you want to set up absolutely everything my favorite example is a web server. You need installation guide You need system administration guide to learn about how to install that software in your Subscriber system install it in the in your system how to start it you need networking guide You need a security guide and our documentation is not helping you need to figure out what you need We also have way too much content and when you look at study sticks, not all of it is read as much as it should be So we're possibly wasting a lot of time. It's also very difficult to keep up to date I will not go into the book SML because there may be people in the room who actually like it I am one of them for the record But more importantly no matter what I think this is what our customers think and we kept hearing about it over and over again so at some point We realized well, this is what it feels like. This is a favorite example So imagine you are a pilot of an airplane and all of a sudden something happens and your airplane goes nose down And you have few seconds to react and somebody tells you oh great For this component here's one book for this component is one book the information is there figure it out By the time you are out of the shock you're dead What you need is somebody to tell you exactly you are in this situation great Press this button this for this and this is it and you need to be able to do it quickly That's what we try to do with our documentation and We're not delivering This is a little look at look look back even before and you will see that we kept repeating the same thing We always felt like this. We're evolving. We're adopting. We're doing something New but what ended up happening is that we kept reshuffling the information that we begin with and never questioned The content. This is an evolution of one book how it evolved over time But if you trace anything in the documentation Usually it is there because it was relevant in ground three or even before that and we always had it there And it's technically accurate. So let's keep updating it for every single release that spends so much time Keeping it up to date This is how we got there So for real eight we realized that's okay and for other products as well I will be talking about all eight because that's our team majority of people in this room There are still not in this room majority of people from my team on in this room are working on rail That's what I feel comfortable talking about and if I could decide something I can point at things that I wrote So for well eight we did it slightly differently And we realized we need to make some changes not only In the level of content and how we approach the content, but also how we Develop that content enables to do the dog book structure of books all of that was holding us back So one rule that we established is all of our documentation No, no exceptions are based on user stories If it is in row eight means because we found the user story somebody is using it somebody's doing this I'll talk about who uses three is in a second We put everything in one of it for one product in one repository so that we don't have that artificial separation of content and duplication of content across several different books and we adopted something called modular Documentation which means that we write small pieces. I'll talk about it a little bit in detail But we write small chunks of information That are used all over that can be used all over the place so if you're reading documentation on how to establish how to work with how to Set up a web server and Part of that is starting the service and enabling it We put the information right there There is a module that tells you that if it involves setting up firewall again You get the information in one documentation that guides you from point a to finished running web server that you can trust because We document the supported way and we started writing it as kiddo Which is much more flexible than the book and easier to train people with so if you look at throw eight title This is a typical title. It is based on the user story. It had been knows who's target audience is and a side effect of this is most of it is relevant to you if you if you find this title if for the reason that you This title the for the purpose that this title is trying to fulfill most of the information should be useful for you should guide you and As an effect also most of our titles are focused some of them have less than pages in the 20 pages. I Took Yes, I just wanted to add that we have also begun this service called big documentation feedback When you go to a portal you are going through some documentation and if you have a question or a suggestion You can just right-click select that type of text and You can tell that we are unprepared What your documentation I want to talk a little bit about it and I hope there mark didn't talk about that because modular documentation is Something that helped us pull it off It allows writers to focus on small bits of small bits of information a module is something that has a clear focus and is It's a logical chunk of information and notes. It's no good purpose There are three types of modules that we have procedure assembly procedure reference and concept Modules are grouped together in assemblies to complete certain user story to document a certain user story user story I have a Long text here, but in a sense. This is all you need. I stole this from our content strategist user story tells us who you are What you are trying to do and why and for us that is very important because unless we know Who you are and what you are ultimately trying to accomplish. It's very difficult to find What to write about we guess a lot the real seven documentation We just try to look at everything you can possibly do with the tool and hope that what you are trying to do with it is there So user stories everything that is in roll a documentation now means that we identified found User story for that and are confident that we are doing it right And that those three types of modules that I don't want to go into detail of that There's a concept module general information about All the playground information that you need to know to understand what you're reading about We don't try to teach you this is another big thing about about our old old ways when you look at all of our guides for all seven and pretty much everything that redhead offers You will notice that most of the books have a guide in their name Because our ultimate goal was to take your hand and take you with us on a journey and guide you Safely to what you wanted to accomplish and we felt at that miserably because most when you start reading them You realize that we are Trying to teach you and we assume that you have all the time in the world to Care about all these components and study them and then figure out how to make them work together In reality, that's not the case. I myself and terrible at reading documentation when I need to set up something the last Time I need to migrate data from my phone. I Have the first article that those three steps. I didn't care about anything else So conceptual module is important, but when we present it We always think what is the minimum that you actually need? We don't want to teach you about everything that you can possibly know about this No, we want it to be relevant to what you're about to read Equip you with enough background, but not more not more This is an unprecedented I'm translated slide. I'm sorry. I was doing it a five o'clock in the morning and I stole it from a different presentation, but illustration of what a conceptual module can look like We have procedure modules Which are pretty much the majority of what we have and those are supposed to Guide you through some action. They require you to do something. They hope that you do something They have prerequisites as an explicit thing Which is a good thing because whenever I read documentation that randomly pulls out things that I should have set up And I did not because nobody told me and now I need to find how to do that thing so that I can go back I hate it. We try to be upfront about it If you need some equipment if you need to pre-configure something we should tell you before you even start procedure And then we are very careful about using steps so that you can clearly See this is step one this is step two I can see that this will take seven steps and I can assume whether it will take an hour or two days Again an example of a procedural module and reference modules are those who reference data is important reference information It's very important as well So all those table all those other options that you might need things like that we put in reference modules There are support to complement complement the documentation that we have in other modules and again To what do you need this is an example of a reference module and when put together we ended end up with focused clear titles and We can reuse many of these modules in different contexts Well, we do all of that in GitHub in a ski dog It is one caveat It's Sounds easy when you think about Small documentation, but our documentation is massive the last time I checked we had three thousand modules something like that So a lot of information it's We're getting in problems that That wouldn't be unsolvable without a few tools that we use so we use get get lab and continuous integration I Was keep this slide because I don't have time so get you probably know it If not, if not what it allows us for it allows us on a rail We have over 30 writers working on multiple things at the same time the last time I checked we were working on 60 different things at one time It would be mess it wouldn't be we would ever be able to publish if we had to do all of that in Just a file system, so we was good and we's branches so that everybody can work on their happy way and get Hopefully manages to resolve everything and put it together whenever we need To publish something it allows us to develop nonlinear in a nonlinear fashion We use guitar good luck so that we can easily contribute It has a nice feature that is called magic was which we use to keep track of all of our work So the number that I mentioned how many things we are working on I can look at merge requests And I see that we have this many merge requests open and most of them are in working progress So I know that these are the things that people are actually working on it also provides a great web user interface So that it can supplement offering software for people who are not as familiar with kids And this is the one that I want to suppose on continuous integration because people associate this with development But we successfully use it for documentation. There are many things you can do with continuous integration But for us one important thing is I mentioned many times that our modules are in multiple contexts What if I usually when I work on a module I get to it from one particular context I look at documentation and see okay this guy this information is missing this module is the right place to put it in So I need to update it How do I know that I didn't break anything else? So we have continuous integration set up in a way that whenever somebody pushes changes to Their topic branch that has a merge request associated with it Continues integration automatically picks it up Validates it and builds preview for all titles that use this module and gives you links So that you can always see oh oops I wanted to just update installation in this information, but I updated five different books as well and It gives you a chance to look and see if that information still works If you didn't break anything sometimes you break things sometimes you use something refer to something that is not available in that Assembly and the build breaks. So again, you immediately have a chance to see that and react before it ever gets into our main main branch Additional feature is that these previews are available absolutely anybody so we very often refer Our subject matter experts people who review our documentation people who care about our documentation to these they can practically always see Okay, so this is the latest that you've done. Did you implement my changes my suggestion said not and they can engage in conversation in the comment section or comment on our code allow us collaborate more smoothly and Because they very often use get themselves. They sometimes probably push their changes to us directly so I rushed through this because normally I do this in an hour Play I didn't rush too fast So I want to thank you for your patience and bearing with me But instead of having this useless life as much as I like looking at my cat I want to leave with this slide, which is the documentation feedback and if you can if you don't remember anything that I say Remember that if you ever happen to read our documentation We have this enabled and you can give us feedback and it's not point plus to give us feedback because we take it very seriously Thank you Yeah Based on How do you take Yeah, so we asked our development to the team to implement this for us They knew how to do that. So they basically look at what is different between the master What are to change it? They're unique to this branch. They look at which files changed and then the script looks at what Titles include this So we have predictable directory structure, you know where the titles are based on the change twice. Yes, exactly How does the feedback look on your end again? What kind of tool shows not does job and what kind of context do you get? Yeah, so you usually select piece of text and add a comment It opens a bug for us. It quotes the line that you commented on and includes your comment It also is clickable. So that it leads us back to your comment there, which is My what I recommend everybody to do when this gets to your cue you get this assigned react on it Click that link we press it back figure out what the comment is actually trying to say and take a note Because it sometimes takes a little bit of investigation to get in your head what you meant by And just use it but We're trying to switch to JIRA Yes The question was if it's a custom solution to direct documentation feedback or if it's something that other people can use I do believe it's in-house. It's custom for our customer portal and if not deployed unfortunately on all products Still in file mode relevant is important and has What's the assembly and then the second question is how do you deal with Reusing and discovering we use the content Right, so I'll try to answer it quickly and get to you So assembly it's an ASCII doc file that has its includes and includes all the modules that it needs So on the level it's relatively simple. It also has some No, no, we're working in one repository, so it's just an include and with the relative path to the modules There is additional markup for if you want to structure presented in any other way usually there's some introduction Specific for that that assembly To your other question This is a thing that you're trying to solve Our team is working on a technical solution for that for now We are careful about annotating our Our our modules you have hierarchy that allows us to quickly find where it belongs and So if it is about networking, we have Directory for that, so at least we can quickly find it and we have very strict naming conventions So usually it's it's looking for keywords quick grab for quick search So far it works, but we are at the edge of where this is Barely good enough, so we'll desperately waiting for the tool. It will help us Make sense Now I'm so tempted to let one of my writers answer Because they've been through this But they're trying they're not looking at me so probably they won't don't know that So this is the private investigation part We want to make sure that we are not coming up with anything if you think about it You can manufacture absolutely anything if you put a little effort in that so we partner depending on where the prompt comes to us Sometimes it comes from from engineering leads. This is a new feature This we implemented it based on this kind of request So it's the first tool for us, but usually we try to understand ourselves and then ask People who face customers support delivery teams solution architects consultants people who are in the field with customers and we inquire with them Is this work use? Is this correct? What would you expect and validate with them? It's a lot of effort User Yeah We don't start from the feature with that if there's a new feature we ask ourselves, so when would you use it? Why would you use it and try to figure out in which? Contexts and where it belongs in the documentation then figure out it usually spawns multiple stories Something that may be used in different contexts. We don't limit ourselves to this is this feature and This we need to develop documentation for this feature We try to find where it belongs Can we talk to Yeah We are out of time so it's there is never a right amount of documentation