 Okay, so the next speaker is Robert Trakti and he will talk about how to improve documentation. Hello everyone. Thanks for your interest in this topic. I apologize for the technical difficulties. It wouldn't be a conference without any of those. Anyway, the topic of this presentation is reaching the gap between legacy documentation and modular content. What I mean by that is basically two aspects of documentation that technical writers at Red Hat are trying to solve. That is the user experience with documentation. At the same time, the amount of work, the maintenance work that documentation writers have to do. So first I would like to outline what I'm going to talk about in this presentation. I will try to provide an introduction about why we even do that. Why do we think that it's time to rethink the way we do documentation. I also talked about the terminology, what's in the title of the presentation, what I understand when I say legacy documentation and what I mean by modular content. I will then outline what we think is the problem with this so-called legacy documentation. I will try to explain why I even think that there is actually too much of the documentation. And I will explain why it is hard to find and how we hope to fix that. And in the main part of the presentation, I will try to introduce what we think could be a solution to one of those problems and to all of those problems that I mentioned. First of all, we will try to cut down on the amount of content that we actually maintain and that the documentation entails. By documenting only what the users really need to have documented. We will also talk about how to facilitate single sourcing of the documentation so that we can bring upstream and downstream closer together. And in the main part, what is modular documentation? And how do you hope to achieve all of the above by switching to a modular form of documentation? Last but not least, I would like to at the end say some time to invite your questions and to have a discussion about what your experience with documentation is and what your project or your organization does in this area and if you are facing similar problems and so on. So, let's get started shall we? About the introduction. First of all, the question is why? Why do we think that it is high time that we rethought the way we do documentation? I like to point out two main aspects of that. I like to illustrate that on two problems or two areas in which the software landscape is changing and that is software packaging and software delivery. We've been for a long time used to these big monolithic, mostly distributions where there would be hundreds or even thousands of packages. They would be sitting in repositories or you would get a CD or a DVD. You would install the thing and then you would have to sort through it and find the stuff that really matters for you. If you were concerned about performance or security then you would have to cut down on that. You would get rid of all the stuff that you don't really need. That is changing. Not that all applications would be containerized now but that is definitely a big part of how applications are being deployed and how they are being packaged. There are other ways to package applications that are not the same as they used to be and the documentation needs to reflect that. You need to try to make the documentation work with those new scenarios as well. With regard to software delivery, again we've been used to more or less regular release cycles. It could be that the distribution or piece of software or project would have a release every 6 months, every 12 months or even if the cadence of the release would not be in any way regular it would still follow the sort of a traditional versioning scheme. 1.0, 1.1, 1.2 then there would be 2.0 and the documentation tended to follow that. There would be a release of documentation for the 2.0 version and then there would be another release of documentation. But then there came rolling updates and nowadays there are web applications that are being deployed multiple times a day. And the sort of documentation that is tied to these release cycles is not exactly covering that. It doesn't really cut it for these scenarios. It should be the way the documentation is released and presented a lot more fluid, flexible and multi terminology. The legacy documentation, I mean the sort of documentation that I touched upon with those releases the documentation that is tied to individual releases. It's those big guides or books and they tend to be comprehensive and complete. While there's nothing wrong with that, it tends to also create a whole lot of amount of documentation and they're based on features. They describe every individual feature that the project or software has that can be used. And as I said, it's important to emphasize that there's nothing inherently wrong with that sort of approach and in an ideal world you would have that as well as at the time of documentation. But in a world where you have to choose where we spend our resources it might be time to look for something else. Where modular documentation comes into picture and that documentation differs from the sort of guide-like documentation and that is based on individual user stories. So it doesn't strive for comprehensiveness. It doesn't even try to be complete. Instead it tries to be highly targeted. It goes after specific goals and it's in concise independent standalone self-sufficient units of content that can be grouped and regrouped in order to achieve documentation that describes specific purposes that goes after specific goals. Now, I would like to illustrate the difference between feature-based documentation and documentation that is based on user stories and a simple example. On the left here there is a silly example of a feature-based documentation. It tries to describe all the features. It tries to be comprehensive. I'm going to give you a second to read through that. Now, are we good? Let's compare that with the example on the right. This one is based on a specific user story and it tries to describe how to take the user from A to B. It's about a specific goal. It's about accomplishing a concrete task. Again, take a second to read through that. Now, when you're looking at those two sides, those two examples, as I said before, it's important to recognize that there is nothing wrong with the one on the left. Its feature-based documentation is the sort of reference kind of guide and it has its users. However, for many users, unless they're really well-versed in this sort of project or features or distribution, for those users to find their way around this sort of documentation, they need to be experienced. They need to have a lot of time on their hands and it doesn't make it very easy for them to use this documentation to accomplish specific tasks. So as I said, in an ideal world, we would have both. We would have the one on the right that would guide the users when they need to solve a specific problem and when they need it to be done yesterday. Then, of course, we would also have the one on the left that would be there to describe the stuff as it happens, how the system functions, what the background is, how the features are laid out. So as I will talk about it in the later part of the presentation, we try to facilitate a scenario where the one on the right takes the user from A to B, but at the same time, the sort of modular documentation that we create would allow the user to experience the same sort of experience that they have with the example on the left. And by the way, as I included down there, when I talk about user stories, I tend to take the sort of a standard agile-alike template, meaning I'm a sort of a user, I want to accomplish something so that I have some sort of an outcome. Are there any questions at this point before I go any further? Okay, cool. Now, let me try to describe what the problems are, the main aspects of the problems with the legacy documentation. The sort of documentation that is based on features and that is compiled in those big large books or guides. Now, in that first bullet, there's a sort of a cliché that nobody likes to write docs. Well, it's not really true that nobody likes to write docs. The problem is when there's too much of that. When the content accumulates over time, where you have multiple versions and then you have to maintain documentation for that version and another version, and over time there's just too much of it. It becomes very difficult to maintain and nobody's really excited about maintaining stuff that has been valid three or four years ago and it's still valid for certain users who still have that deployed somewhere. But when there's a new contributor, they usually want to work on something new that they want to describe stuff that they know about. They want to describe how to perform a specific task. So, there comes the cliché. Nobody likes to write docs because it has become tedious to maintain those guides. And it also invites a lot of duplication because there are different sets of docs for different versions and the content tends to be used, reused, but not really nicely. And if it's updated in the new one, it tends to be overlooked in the old one. Anyway, it leads to documentation that tends to become obsolete. That's a problem. Secondly, the documentation is hard to find and by that I don't mean that it would be hard to Google for documentation and you wouldn't find, for example, in Fedora we have an administration guide. We have an installation guide, a security guide, a networking guide, but when there is a user who wants to configure SSH to be able to securely connect to a remote server, what do they use? Well, they probably need to find something in the installation guide, as well as in the security guides about security, after all. It's also about networking, so they will have to find something in the networking guide and the system administration guide. Well, there's probably going to be a little bit of that as well. In reality, they would need to sort of cherry-pick pieces out of all of those guides. And while it's possible, it's certainly not exactly user-friendly and it takes to take a lot of time and the user needs to be familiar with inside all of those guides. Well, so what do they do? Well, they Google it, they end up going to somewhere as a stag overflow or something like that. And while there's nothing wrong with finding your answer at stag overflow, it tends to indicate that there's actually some deficiency with your documentation because the user, instead of being able to find the documentation that you have produced, it tends to go somewhere else. Lastly, documentation is very hard to navigate because those guides tend to be very long and while it's useful for, you know, control F searching, it's definitely not useful for navigation. There's no hierarchy usually and the experience is very hard to customize because when you take those guides and you want to save them, for example, for offline use, you can use PDF or a huge pile of HTML that you have to browse. You cannot really find and take only the stuff that you want. So, well, of course, it leads to people saying this which may or may not be true but we're not exactly happy about that. Any questions? About how we would like to go about solving these problems? We're not going to go into the general size but we tend to think from experimentation and from conversation with support people and with communities that it could be a way to go forward. So, first of all, we would really like to concentrate on the stuff that the users really need and in order to do that, in order to be able to cut down on the amount of content to ease the maintenance burden, users' stories that are really valid for users. We need to work with the community, we need to work with the engineers, we need to work with support organizations and find the users' stories that the users really are interested in and that tend to solve the majority of the problems not the majority of problems but the most common problems for the majority of the users. And by that, we should be able to achieve a more efficient use of our resources. That doesn't mean that there still wouldn't be some sort of a maintenance burden but by trying to cut down on the amount of content and by communicating with the users about the users' stories that they're really interested in, we are able to slowly reduce the amount of maintenance work. Also, when we try to bring upstream closer together and even single source the documentation than upstream downstream users, we not only save time by avoiding duplication and not only duplication of content but of effort but we're also able to bring new contributors on board because it just becomes easier. Upstream may not be at all concerned about how the project or software is being productized by company or some other project but when they have the possibility to contribute to a single source repository it's a very good thing and it also helps to bring the developers on board. Now there's another cliche that developers don't like to write documentation and of course some of them they like coding better and they tend to think that documentation is definitely not across the board and when we make it easier for them to contribute to the documentation it becomes a whole new different story. And lastly about the module of authoring and presentation of the documentation. This is basically the method that we're using to achieve all of the above. Now I will talk in the next series of slides about what the modules and assemblies that I have here listed the main components of our module of documentation what they are, how they're formed and so on. But first I want to touch upon the second bullet about the so-called curated assemblies and ad hoc docs. Now by that I mean and as I'm going to explain a little while later an assembly in our terminology would be a realization of a user story and there exists a user story that has been identified, has been validated we know what the user wants to achieve we write or adopt some modules and we assemble them, we collect them combine them in a so-called assembly and that becomes a description of the user story a realization in documentation of the user story. And of course such assemblies that are based on user stories that have been properly identified and validated they could be called curated because we've put a lot of effort in them and we've made sure that they make sense however we recognize that we're not ever going to be able to identify all of those user stories there's always going to be the guy who wants to install his Linux distribution on his internet-enabled refrigerator and use it to drive his home cinema or something like that it's unpredictable so we recognize that and we also want to allow these users to experience the sort of stuff, the sort of experience that they would have with the reference documentation with the one that's based on features so we try to come up with a really solid system of metadata that would be assigned to the individual parts of the modular documentation and we would allow the user to browse through the entire body of the documentation that we have based on this metadata it becomes highly hierarchical and it becomes possible to select the bits and pieces of the documentation that pertains to the particular problem that the user is trying to solve or the particular area that they're interested in so I choose here to call it ad hoc what this allows us to have the presentation of the doc's dynamic it's not static anymore, it's not one huge page or guide it becomes possible for a user to dynamically select the kind of stuff that they are interested in and go away with that and use that again, questions? cool let's describe those assemblies and modules these are really the main components of what we call modular documentation as I said before I touched upon shortly when we have a user's story and we want to document it we think about the realization of a user's story as an assembly it's a whole bunch of modules and other stuff that is being put together combined in a coherent way to form an assembly I have a short node here purposefully avoid the word topic even though many people say topic-based documentation but we found that it's too loaded the word is just too ambiguous everybody thinks that topic is somewhere something else so that's the reason why we're not using it anyway, so we have an assembly and we have to populate it so we have some sort of an introduction that should have a title what is going to be accomplished by following that piece of documentation might also have a list of prerequisites some sort of conditions or steps that need to be taken before the user goes and follows this piece of documentation the title should be very specific it should be oriented towards a specific task, action oriented such as it was before making an omelette something like that it would then be followed it could be a conceptual module it doesn't have to be there and as an example I've chosen here understanding the importance omelettes in French cuisine now you know that it's not really important or perhaps it's not necessary to understand this kind of stuff to be able to flip an omelette but there are many scenarios where it may be very useful for the user to know the background and by being able to include these conceptual modules into our assemblies we're also recognizing the importance of the sort of feature based documentation that we're supplanting, not really doing away with and if we would combine only the conceptual modules we would end up with something similar that we had before so we don't want to discard that we want to keep it then there would be an explanation of the concept of the background and there could be a list of links to additional resources then would come the real need of that piece of documentation one or more procedural modules they would have again action oriented titles they would describe steps that need to be taken to accomplish a task and as I said there could be one there could be a bunch of them it really depends on how granular is that particular assembly how wide was the user's story when we have started with it the steps in that modules should be very explicit they should be commands they should say edit, open, copy something like that and again each of those modules could have additional resources same as the assembly as a whole points to other pieces of documentation related modules, related assemblies related onion recipes stuff like that and you may notice that the structure of that template for the assembly is the same as the template for the module that is intentional those individual pieces of the documentation are all designed and written or adopted from existing documentation to be self standing it's necessary to have those modules in a way that they can be combined and recombined in different assemblies those individual partial steps may be used in very many different scenarios many different user stories so that is the reason why we're providing a sort of a rigid but at the same time flexible in what the content might be template for these components questions I'm sorry could you use the microphone please how to cope with a great number of assemblies that came out in the project history so if with legacy doc we have big manuals I guess with this approach we will end with having a great number of these documents so you're asking how to organize the assemblies that we're going to end up with and maintain and maintain them that's a very valid question I actually have that included in one of the latest slides about the discussion that's something that we have to apply a lot of planning for we try to come up with content strategy that would allow us to keep organizing this we have explored many different ways to keep track of what user stories are being put together what assemblies are being populated in order to describe these user stories so that we don't lose track let's say that we would have a whole bunch of assemblies for beginners but we would be lacking the more advanced stuff or we would have user stories that would be identified for a specific area and some other ones so what we have come up with is for different products or different projects that we're documenting mind maps that would allow us to keep a visual overview of what we have available what is missing and what still needs to be done and how it all relates together so that we don't have an overly limited one part of a project and then big gaps in another part thank you really short quick question you're doing this in dog book in the formats that you're using for structuring your documentation is that dog book that you're using or the question is whether you're using dog book or a different format so I'm a technical writer at Red Hat most the majority of our both upstream and downstream documentation is either in ASCIDOC or in dog book so we're sort of in the middle of a transition from dog book to ASCIDOC but we have these templates in all of the formats that we're using for in order to be accommodated all the different writers who want to work with them there was questions cool let me wrap this up we're going from legacy to modular now as I said before by legacy I mean the kind of stuff that is based on features that is included in big long guides and that tends to be complete comprehensiveness as I said before nothing really wrong with that but we want to sort of reposition the documentation into stuff that is being based on user stories that describes specific tasks that is action oriented and that is based on this modular approach as I said before the modular approach allows us to have the same sort of experience or not the same but a very similar one as with the feature based documentation when we make rich use of the metadata that we apply to the individual modules secondly this allows us by identifying the user stories that we really want to use that the users are really interested in to reduce the amount of content to ease the maintenance burden of the documentation writers and also to attract new contributors because the learning curve is not too steep for them when the documentation is in these modular pieces because it's very hard for a person who comes and is new either in an open source project or in an organization to start contributing to documentation when it's all about those big guides you know you get a system administration guide and you have to first read it so that you know what's in there you have to become familiar with that it's very daunting when you present people with the opportunity to actually document short user stories the kind of stuff that they're already familiar with they have figured something out now they want to share with others so they can document they can provide a procedure that would become a module they can provide a bunch of modules they can even populate an entire assembly slash user story so not only are we cutting down on the amount of content we're also making it easier for people to pick the pieces that they want to document and start right away and thirdly improve the experience for the end user by making it easier to navigate the documentation and by taking it from static documentation into dynamic presentation and that is being accomplished by heavy use of metadata which allows us to present the documentation in a highly hierarchical way starting from the top where it's not really granular through a hierarchical structure based on the dynamic presentation of the metadata-based documentation yes there are two questions there can you please before you get on to maybe a more technical side the thing that I've been trying this technique a little bit myself and the thing that bothers me slightly and maybe the next talk is going to go into a bit that's a bit more is how to keep things modular and still maintain a kind of consistent storytelling narrative that doesn't just sound a bit disjointed with steps that sound like they're written by different people or in different styles and just maintaining that a document still sounds like a cohesive whole I suppose right so the question is how we go about making the modular documentation still coherent still that so that the different pieces are not disjointed it's still sound like something that the user would like to read understand it correctly well so as I mentioned before when I talked about the so-called curated assemblies those are the ones that we focus on when we put together the individual user stories and in between the different parts of the assembly the different modules and the introduction and perhaps the conclusion where there are links to additional references we are not against including you know sort of stuff that I could call you know fluff stuff that you bridge you over from one module to another the kind of stuff that would make it easier to read now those would be the curated assemblies those would be the one that we spend time on at the same time as I said it's not possible always to be sure or to identify or to document all the user stories that the users would really need so it may be that there is a certain topic or an area that people are interested in which we haven't covered in this curated assembly that is easy and nicely read so then it would be with the understanding that the individual pieces are being compiled in an ad hoc dynamic manner and then of course there wouldn't be the nice experience that we offer with the curated assemblies but as I said we try to work very hard to identify and validate the user stories that we put effort into so that the experience would be nice for the user so we are definitely talking about documentation in times of processes and something like that what's your recommendation where should I maintain such kind of modular documentation is it alongside the source code just another piece of the source code in the same repository or something like that so the question is where to maintain this sort of modular documentation whether it would be in the same repo as the project code or somewhere else well this really depends on what sort of project or community it would be a part of we have no strict rules or guidelines about that now we are part of many different numbers of communities and we don't really want to impose on them some template or rigid structure that they would need to follow we try to accommodate the request of the community that said what we try to encourage all communities or projects that we are involved in is to use a specific structure of a repository we are using Git for those repositories of a repository that makes it very easy to combine and reuse the content we have this structure which we have available for anyone to use that can be included either as a separate repository if that's the preference of the project or that can be a part of a larger repository that includes also code or other artifacts so it's very flexible and it really depends on what is the common ground what is the understanding in a particle project it has so far worked very nicely for us in both ways both separate repository for documentation and repository that includes both code and docs just one thing it's not clear in the dynamic presentation when you create a user story this is composed by several parts but these parts are made only for that user story or are still part of small sub pieces because I was just wondering if I could create my own user story using these sub pieces like picking up smaller amounts that you use of information that you use to create your user stories and making it because if the user story that I'm looking for is not existing can I make it up or not well the question is whether you can come up with your own user story that is not part of what we have been documenting is that correct on the one hand we try to encourage documentation writers not to rely on themselves only when identifying the individual user stories because they as documentation writers might have very different ideas about what is necessary to describe as a part of documentation as opposed to what the users really need so we always try to encourage collaboration in on all the different levels and trying to involve as many people as possible in identifying those user stories that said if there is a user who has a specific use case or has a specific task that needs to be accomplished and so they identify user stories for themselves and then they want that user story to be documented we either accept that as a bug or an enhancement that needs to be done or we invite the user to be the one to start the documentation and document that user story does that answer the question Chair? It's a bit of a plug we're working on an open source Drupal distribution for doing modular content that allows you to pull topics or modules or however you want to call them from different repositories and then compile them into one single website that publishes your documentation so that you could combine documentation from different projects if there's anybody in the room who needs a system like that just come and see me Any other question? I do have a remark a question sort of I think that something that is hard with the modular approach is to be able to oversee all the modules and how they can be reused so if you have one user story I agree that it's much easier to change it somewhere but there is a new role which is assembling in assembly all those modules and having an idea of what should be specific what should be generic and I think that that's a role that really needs to have an overview of even more even wider overview than in the legacy documentation do you have something to say about that? So the question is how we track where the different pieces of the module documentation are being used basically? and also to have an idea of what needs to be done and what can be reused people start with their own stories so they do their own modules and then it's nice if some can be brought together because they are similar maybe they just need some little stuff to be different at the beginning and overseeing all that kind of process that seems to be quite hard to do and really need some very big overview of a lot of things I understand so two levels of an answer to that question first as I mentioned before we use mind mapping software to keep track of the different parts of the project or the aspects of what needs to be documented to keep track of what we have already documented and what needs to be still done but at the same time as I mentioned the metadata based hierarchical presentation of the documentation allows us to very easily filter for what for different pieces of documentation so for example if you are interested in security documentation it's very easy for us to filter all the pieces of documentation that we already have that touches upon security and you can go deeper, more granular the deeper you go the narrower the selection is going to be but it allows you to very easily see what sort of documentation already exists in what areas so that when somebody wants to document a user story they first go through the available body of documentation and they see whether some of the procedures for tasks have already been described and whether they can reuse them so that they wouldn't do it over again and as I said the hierarchical structure makes it quite convenient to browse through that documentation even though it starts out as a very large body of documentation you can easily get down to what you're really interested in Hi, you mentioned moving from dot book to ASCII doc did you consider also I like ASCII doc, I do like it but did you also consider markdown, is it too simple or just not as a fully feature so the question is whether we also consider markdown as a format for documentation and yes we do, some of the communities that we work with do use markdown for various reasons for example I have now been trying to figure out a way to work with markdown in combination with ASCII doc because the Go language has many different tools that allow the automatic generation of markdown reference documentation and we need to find ways to sort of make that work together with other parts of ASCII doc documentation so there's nothing really that we would have against markdown it's just that ASCII doc provides us with more options, it's more flexible, it's a little bit more complicated but it's still very easy to learn the markup of ASCII doc is quite simple to learn so it was just a conscious choice to go with ASCII doc because the tooling around ASCII doc such as ASCII binder and other pieces of software are very convenient and allow us to do a lot of things with it What sort of tooling do you use with ASCII doc? So for ASCII doc, for rendering we mostly use ASCII doc as I mentioned we also use ASCII binder in different projects to actually present the documentation on websites and then we have many different in-house tools that are out in the open on github and stuff and that solve different problems and provide different templates for individual pieces of documentation I can go into details if you're interested afterwards I would suggest we have just one more I think perhaps Excuse me Another question Do we have time? I haven't heard the last Okay, sorry Can you speak a little bit more about more media sort of video do you see that like I mean don't get me wrong I think that the majority of the users are like beginners or entry level so they like rather watch videos than documentation and even if you do your modular approach and you synthesize a very small they still tend to go and see a video so how do you counter I apologize I'm having a hard time to understand could you try to speak up please I thought that you hear so my question was how do you approach some sort of emotion other way of expressing documentation because these users despite your modular approach I think that they tend to go to look into videos instead of reading documentation so are you asking how we work with videos okay so I believe that's that's a whole larger question which we probably don't have much time for at this point but I really happy to discuss that with you we have in several projects we've encountered a problem and we have worked with videos within ASCIDOC with mixed success but I'd be happy to talk about that more actually my last slide was just a couple of points for suggestions for discussion which we have gone through I'm afraid we are out of time at this point so if there are any more questions please feel free to find me down here I'd be happy to discuss with you