 All right, so hello everyone, my name is Robert and I work as a technical writer at Red Hat. Thank you for interest in this topic and in the topic of documentation in general and It is kind of unfortunate that this talk wasn't scheduled before polls before if you've been here before for Talk polls documentation talk. I'm going to talk about how to actually write documentation Whereas he talked about more of the process and how to get the written documentation out there anyway In this presentation what I'm going to be talking about first I'm going to quickly touch upon terminology what I mean when I say old documentation or legacy documentation and what I mean by those new tricks or a new documentation also, I'm going to briefly mention why even bother white Like to be interested in that then I'm going to outline what I perceive as the problem and Also what could there should be our solution? so Let us get started About the terminology old documentation. Well, it doesn't really have to be old and I have to admit that I very much like the title of teaching old docs new tricks But you know this old documentation that I'll be talking about that can also sometimes be called legacy There's really nothing wrong with it. But what I mean by it is the sort of big administration guides installation guides or Networking guides that kind of stuff those Sometimes are called even books and as I said nothing really wrong about them there Tent to be comprehensive the criterion for Quality is there the completeness they want to describe every last feature that there is Meaning that they really are feature-based They want to describe everything there is to be described about a specific project or a product or a piece of software Now such documentation could be very useful for a person who for example needs to pass a test or Gain or a certification or something like that on the other hand the fact that it really needs to be complete Otherwise, it's by definition incomplete Means that it takes a lot of time and so forth I'm going to go into that later on but there are very many problems with that especially with maintenance of such documentation so To get around some of those problems The new documentation or the documentation that new tricks have been applied to Would it be an opposite of that it does not strive to be complete and comprehensive Instead it tries to be as much targeted and a specific as possible it's Berlin it tries to be very concise and it's not usually grouped into big books or Guides instead they it is presented and also written as a very Short or to the point articles or units or pieces of docs that try each on it on their own to solve a specific problem to Answer a goal answer answer a question how to how to get towards a specific goal So that's about the terminology now about the why Well part of it as I mentioned is that there are some definite problems with Maintaining documentation that is based on teachers and that tries to be comprehensive and complete also there are some There are some considerations with regard to the fact that Nowadays It's not so much about The software or the system it's more about What the user is trying to accomplish with that? So while we still have for example the monolithic distributions that I'm mentioning here such as fedora Buntu Debian and so forth and also other systems such as Android or other ones they do exist but The way they are being used such as in containers or that Android if you Ask your average cell phone user what they're using on their cell phone They're probably not gonna be able to tell you that it's actually Linux meaning that The specificity of that particular piece of software or system the fact that it is some sort of a software It does not really concern them does not really bother them Therefore they're not gonna be interested in Linux documentation They're going to be interested in documentation that tells them how to accomplish stuff how to get rid of a Specific task that is on there to do meaning that the packaging of software and of the products that we're used to is changing and The documentation that has been designed for those big distributions such as you know could be your Linux administration guide does not really cut it for you know such landscape also hand-in-hand with that goes the way the software is being delivered because While we still have some release cycles. They're not really being that important and also there are some Applications or even entire systems that are not being released as a version 1.0 1.1 1.2 Then there's another major version and so forth while maybe the underlying system or the application That is actually facilitating the achievement of a goal does have you know somewhere underneath Beneath the hood there still is a versioning system what the user sees is a continuous deployment and that application or that system or Service could be deployed several times a day every time you push a fix to the repository It goes through some sort of a CI CD process and gets deployed and the user gets to use it all of a sudden or As soon as they you know re-allowed the web page or something like that So if we have a documentation a piece of documentation or a guide or a book that addresses how to use That piece of software with version 2.0 Well, it's not really cutting it for this sort of an environment because the user is not really interested in that and also That piece of documentation grows stale very quickly. So it becomes obsolete before you even finish writing it and Therefore There comes the advantage of those, you know lean concise units pieces of documentation which can be updated and kept up to date with much less difficulty So I'm getting into what the problems are with this sort of old documentation Well Even though I'm a technical writer you probably would not expect me to say that there is too much of that documentation That's a weird thing to say because usually people tend to think that you know documentation is missing But the fact is that if anyone ever gets to write this piece of documentation such as the administration glider security guide well that Because it tries to be complete and comprehensive is just a lot of content So not only it gets difficult to maintain it also tends to lead to duplication because You know while something may be described as security guide well a piece very similar to that Could be described with a networking guide as well our system at Richard administration guide so all in all it tends to lead to the content rod because as much as we would like to we always have limited resources we Don't want to have that many people to maintain That documentation so we're trying to get down whittle down the documentation cut away the pieces that don't really need to be there and Only document the stuff that really needs to be documented I'm gonna get into that another piece of the problem is that the documentation is really hard to navigate because Not they would be particularly difficult to locate the documentation But if a user wants to accomplish a certain task or they're being given A task by their boss and you know they need to finish it yesterday They're not really interested in learning a whole lot about a particular system Instead they just need to get to a certain point They need to go from A to B without really needing to understand you know the rest of the alphabet So how did they know how to do that? Well for example if they need to do something with a I don't know Perhaps a file server. So is that gonna be a part of the administration guide? Is that gonna be a part of the? Security guide perhaps if that file server needs to be secured Is that gonna be a part of the? Networking guide or some sort of a general user guide Well, the truth is that it's very likely that pieces bits and pieces of the required Information is going to be in all of those guides in one, you know, there's gonna be this little bit There's gonna be that a little bit in the other guide and in the end the user is going to be asked The very unlikely, you know scenario that there know the entire contents of those guys So they're gonna have to hunt around and piece those puzzles together Themselves instead of being able to follow a single piece of documentation that takes them from that a to their B so what we are trying to solve, you know by by actually, you know being aware of this problem and then trying to do something with it is to Make it easier for users to consume the documentation make it easier on them so that they don't have to be, you know that they don't really have to be Very knowledgeable about Entire pieces of software about about entire operating systems And you know as I mentioned here instead of you know trying to locate all of those pieces of the puzzle They just give up and they Google it and they end up going to stack overflow or something Which in and of itself is not a bad thing except it you know kind of reflects poorly on the written documentation because it's not Being used for its purpose So what could be the solution or what is the solution as we try to identify it well As I mentioned we only try to document the stuff that the users really need What they want to have documented or what they want to read because you know as everybody knows nobody Really likes to read documentation especially if there is a lot of it So we try to identify and make sure that such user stories as we come up with are really valid That they're the ones that the users are really interested in and that they do not a contain any fluff And also they do not try to educate the user Unnecessarily about all kinds of different problems Instead they only focus on the stuff that they are really interested in and in the process Well, we try to cut on the amount of cut down on the amount of content so that There is less to maintain and also it's easier for the user to consume Therefore we're using our resources better because we're always going to have limited resources be it a product be at a company or Open-source project. There's also gonna be too few people and for documentation that you know that holds true as well Well, maybe sometimes even double Another part of that solution what could be is what we like to call modular writing and that means not only making those pieces of documentation or articles of documentation, you know lean and concise and Those units being you know as small as possible But also making it making the entire process of the documentation easier for people or for new people who come on to the project So that they can get on board it really quickly and they can start With whatever, you know, they're good at so for that for that particular thing We have developed templates that make that writing of the documentation easier It does not you know me having a template that you can you know fill in the blanks as Could be even considered that does not really take away the Responsibility from the technical writer the technical expertise is still required and it's still required to you know Make sure that you're actually documenting something that needs to be documented The fact is that such a template makes it easier for even an experience writer to get started it's then some sort of a structure and another thing is that if Documentation, you know that those units or modules of documentation are based on specific templates It makes it makes that the entire result of the documenting process More consistent therefore if you know one writer why writes one piece of documentation another writer writes a Continuation of that piece of documentation both of them using the same template It means that for the user it's going to be easier to consume because If they're both following the same template that documentation is just going to follow the same structure It's not going to be not only easier on the eyes It's just going to be easier to understand and comprehend because it's going to follow the same the same flow the same structure Last but not least as I mentioned up front It's easier for new people to get started with that because they're not being asked to you know fix the administration guide or You know write a new chapter for the security guide or something like that They can take these little pieces, you know They only document a certain procedure or they document a certain concept that they're familiar with or that they can learn about relatively quickly, so is that sort of a low hanging fruit and By making it like this, you know by turning the entire body of documentation into this templated modular Documentation we're basically turning the entire volume of the documentation that we need to have Into low hanging fruit because it's just easier to pick up so those modular pieces make it Make it just simpler to get started Therefore we save time again use our resources more efficiently and make it easier for a new contributor is to whatever documentation project there is to to get on board so When I was talking about feature based versus user based or use a story based documentation I've put together this slide whereby I try to you know Make sure you know to drive down the the differences I'm going to let you read through those, you know on the left you got those features on the right you got a user story I've tried to pick something that that could be only accessible and easy to easy to understand It's about onions as you can see now. I'm going to come back to what I've said before There is nothing wrong with feature based documentation in an ideal world We would have both pieces or both kinds of the documentation We would have enough resources to be able to afford to Deliver to the users, you know both feature based and user story based documentation that would be great However in real world We are always short of resources and therefore we're trying to choose the way that delivers You know that there is a bigger bank for the buck basically We're trying to make sure that we direct those resources to something that is really going to help users With their particular pain points that they have right now We're not trying to educate them anymore about those whole pieces of systems or you know whole software Distributions instead. We're trying to you know, handhold them as they're trying to achieve their goals They're trying to walk, you know from that a to b Therefore as you see as I said nothing wrong without, you know learning all there is to know about onions And how to use those onions and how to use acts and that kind of stuff But if a person wants to make an amulet, well, no Well, they're probably going to figure it out sooner or later Maybe they're gonna have to you know, we read some other pieces of documentation that also talks about You know all that other stuff that you actually need to know about you know making an amulet but in Converting or adapting, you know the documentation that we already have into users into this user-based approach We are just making it a whole lot easier for the user to follow those instructions From start to end so that they can actually accomplish their goal by following those instructions instead of trying to piece together Those individual pieces of the puzzle And as I mentioned down here that user story could be You know as an amateur crook I want to make an onion amulet so that I can impress my friends I'm sure you're all familiar with that agile formula for You know for for a user story as you know some sort of a user I want to accomplish some sort of a goal so that Something you know gets in the process resolved So that's the same that's the same user story that we're using over here I just wanted to put this slide here So to make it to make it you know really clear what I considered difference between a feature-based documentation a user-based Documentation and again emphasize that there's really nothing wrong with either one of those but in order to you know maintain our sanity and also be be able to support the users who actually consume the documentation We want to choose the choose the approach that Delivers the value more quickly and with less difficulty So How do we go about that and how do we you know ride those user story-based pieces of dogs? well, we have developed as I said a set of templates and Those templates are for the so-called assemblies and modules well by an assembly We call you know that is The already documented user story We have a user story that we have identified and we have validated it We have made sure that that user story is actually Something that the users are interested in and that they need to have documented and then you know when we have formulated it we Take an assembly template and that template calls for the inclusion of modules as you see here We could have you know a module for a concept module for procedures and so forth We have some other templates as well the point here is that really it is something that can be thought of as Like a kids play, you know, you just put those pieces together and you can mix and match therefore You know one procedure module could figure in this assembly also in another assembly Making it easier to single source and reuse those individual units of documentation So every assembly slash user story would have some sort of an introduction that introduction usually would not be Reusable in other pieces of docs because otherwise we would make it into a for example a concept module But other than that that there would be a concept module But it's not necessary But sometimes it is better to describe some sort of a concept to get the users to understand the context And there could be one or more procedure modules that actually outline the steps And I'm going to describe later on what all those could look like and at the end there could be Again to tie it back to the other pieces of documentation that we have been writing So there could be a section with additional resources Meaning that we link to other assemblies or other modules, or we may be linking to other external pieces of information and as I've already said the assembly would be you know a Documentation of realization of a user story We have a user story that is being formulated and we create an assembly to Document that user story into that assembly. We put this introduction Therefore there needs to be some sort of a title to make it unique such as making an an amulet We should also describe the purpose if that user stumbles upon that piece of documentation. They should have They should have clarity with regard to you know What is it for what I'm going to accomplish if I actually go down this road and if needed we can list some prerequisites What needs to be already in place so that that particular user story can be followed to a successful conclusion? Now comes the first reusable piece of Information the first documentation unit that can actually be single source to a different different user stories Now here I've chosen a concept module again It would have a title it would describe the con the concept and it could in and of itself also have Links to additional resources that you know like like any other module In this case, I've chosen understanding the importance of omelettes and French cuisine now you don't really need to know that in order to be able to to fry an omelette on the other hand if You know if the end goal is to impress your friends You're definitely this course some more points if you actually understand the importance in French cuisine and that there would be the procedure modules And again those would be try those would try to be very lean and concise They would only list what needs to be in there They would tell the user specifically what to do go there open this configure that set up that Delete that thing and so forth and you're done with that particular procedure Of course again, there would be a title there might be a purpose or prerequisites if desired or required and An important thing as talking about those modules in order to be able to reuse them in other pieces of documentation We need to make them Self-sufficient so they need to be able to stand on their own if a user navigates to an Individual module that gets displayed on their web page for example They need to immediately know where they're being what they're being told so such a module for example cannot really Say well you for you know you read this far So now you already understand all that needs to be understood now Let's go forward because that wouldn't really work because we need to observe that principle that you're probably familiar with That every page is page one So if a user navigates to a piece of that documentation They happen to stumble upon in middle of something that we consider a piece of docs They need to understand that either they really are in the middle and they need to start meaning You know there would be those prerequisites and they would understand immediately that they have not met those prerequisites or They would be able to start right from that space They would be able to you know either continue or start the whatever procedure or a task From the piece or from the page to the to which they have navigated Therefore each of those modules needs to stand on their own Also, it wouldn't make any sense if you were to create a module that would only make sense in one assembly Slash user story because then that module would not really be a piece of reusable documentation You would you would have no use for that in any other assembly and therefore I would defeat the purpose and If such a piece of Information was really really required for that particular assembly Well, you would need to put that in true for example that introduction piece that is specific to that particularly user story and Finally we would have those additional resources that I said before it could be links to other related modules or pieces of documentation it could be links to other websites manual pages whatever you you know or perhaps other onion recipes and You know, I'm including this link over here So that if you'd be interested all of this stuff is already online and on github and can be used and reused by anyone who'd be interested in those Templates for all of the modules and assemblies that we have put together are pretty self-explanatory and they include their internal comments and Documentation so it should be very clear to anyone who would want to use this system How to actually do that but on top of that this particular github repository that I'm linking to also includes Documentation, you know some some sort of a reference manual that that goes into a little bit more depth about how to use those individual templates so One thing that I want to mention Not really go into much, you know much much depth But what this really allows us also to do is not only to make the documentation easier to write and easier to consume but There is another avenue that can be explored and that is a modular Presentation of the documentation so we're not only looking at the source code of the documentation here but it also looking how to exploit that The fact that those you know individual pieces of documentation can be mixed and matched in In the way we're presenting the user to doc to in the way we're presenting to the user that documentation so instead of what we have now or you know what are the traditional ways of Treating documentation when it gets published and it's you know, it could be an article It could be that book or it could be some sort of a paged Structure that you can you know flip through or navigate through this modular This modular stuff this modular Structure of the documentation would allow us to work much more efficiently with metadata and therefore being able to filter the Entire volume of documentation that we have based on that metadata so that for example if a user would be only interested in security topics about a specific piece of software in specific Part of the life cycle meaning for example only the configuration part or only the maintenance part or something like that they could select that in the using the metadata and When they do only those particular pieces of documentation those modules those units that Pertain to all you know to those topics that have been filtered by the metadata get displayed some Logic could be also built into that bit of artificial intelligence that would For example work with you know, what sort of user is that for example if that would be on the redhead customer portal it could work with the Idea about you know, what sort of software what sort of licenses that user has so that the Metadata could be pre-selected for that particular user. Also, it could be based on you know based on a customer accounts for example Saved, you know for that particularly uses preferences So you would know that that user only uses open stack is not really interested in any of the other middle of stuff So, you know, we would not include that stuff in his search results and so forth and so for it really let's lends itself into into Lots of ideas and we already started working on those but I have not gotten really far but it's all in paper at this point and with in only some Some very proof of concept implementations, but it looks very promising and it's something that We're very pleased to learn that that modular structure of documentation Lends itself to So to wrap it up, I Just want to you know emphasize some of the main points that I've been talking about here going from the old to the new So a or most importantly the old documentation or the legacy documentation Is based on features and therefore if not all features are described that documentation is incomplete therefore, it's not really you know, it doesn't really work for the user if It's not entirely comprehensive on the other hand with the new documentation or with the new approach We're not striving for completeness instead. We're just striving for very specific particular targeting We're trying to make sure that the stuff that we document is only the things that the users are mostly interested in Of course, we're not gonna be able to satisfy everybody There's always going to be that person who will want to use Fedora on their you know Fridge in the kitchen or something like that and we're not going to be able to you know document those user stories that that particular person is interested in but we're going to be probably able if we are very careful and meticulous with the Identification and validation of the user stories. We're going to be able to cover Some some very nice percentage of of users and therefore of the user stories that the general user base is interested in That leads into the cutting down on the amount of content. We try to reduce the amount of content Not only because it is hard to maintain It is hard to navigate it is hard to wrap your head around about where that particular piece of information should be found so We try to focus on small pieces of documentation Making it both easier for the widest to write as well as for the people for the people to consume And last but not least there is the there's the modular presentation There's the there's the sort of a new new generation of how to present documentation and that is Trying to go away from the static navigation that usually does not lend itself much to customization into Into this modular presentation where it can be highly hierarchical It can be based on metadata and the navigation could be much more dynamic than it is now So that brings me to the end of my presentation if anybody has any questions I'd like to try to answer them now. If not, I have some discussion points that Frequently come up Looks So the question is very understanding correctly is that if Some prerequisite steps or points are included not only One time at the beginning of a user story or an assembly But they're also included for every individual module then it might get confusing for the user because they're not really Able to understand what those prerequisites are or why they have not been included in the first place at the beginning of the entire user story Is that correct? Right So that the question or piece of feedback actually is that if you include in you know For example a procedure to a prerequisite that says you must have completed procedure one in order to be able to continue here It gets some you know, it looks funny because it looks unnecessary Pete you know people who have already been following that assembly right from the start they they think it's obvious So yeah That that is a problem and there are several ways or several approaches to to to solving that or true to trying to to mitigate that problem And that is one if you really want to make sure that as I said, you know Every page is page one meaning that every one of those procedures Can be or can exist without Actually, you know having some sort of a dependence on on a particular procedure right in front of it Then then you really have no choice. You have to include that there So I understand that it can get you know Confusing or not maybe not confused might look looks arbitrary in that particular piece of Documentation what you're trying to explore is for example with the new presentation is that all of these pieces all of these sections of the templates and thereby of the of the modules would be collapsible and therefore you know the the logic if And the logic would be that if a if a module get displayed gets displayed right after another module It's not being displayed on its own Then these prerequisites would be by default collapse They would not really you know stand there and take up space if the user would be interested in or I just wanted to make sure they could you know Click a button or an arrow or something and that you know that section would be displayed to them as well But it would not be displayed by default whereas if if the browser or the system would detect that You know this module is being displayed on its own and therefore the you know every pages Which one principle would need to be Observed then this you know none of that would be collapsed and it would all be displayed in its entirety by default And therefore it would serve its purpose So yeah, it could be a problem, but we're trying to you know work around that and still we're recognizing that it's our You know less a problem than not having it any other questions Well, it's not and I'm going to thank you