 Hi everyone My name is Paul right and I'm going to talk about documentation But first let me Tell you something about myself When I grew up when I was growing up my father owned a bike shop with his brother George that was the right brothers. They had a bicycle shop. So naturally I taught You know when I grow up I'm going to an event something like the airplane that didn't work out because Terrible fear of heights and public speaking. So please bear with me as we go through this talk By the 1980s I was living in Germany and Some friends of mine or start were basically how they were working on an aerospace startup And I was working as a technical writer So I had access to the tools computers and printers and as a favor to them. I Designed their logo here, which is the kind of Escher type Representing three T's if I remember correctly it was telecommunications Telemetry and technology that they were joining in this in this startup and they sold that company for 42 million in 2011 But I didn't get a penny but But they did give me, you know, I did it as a favor. I didn't mind that at all But they gave me a modem When when they you know when I did the job for them and that kind of sent me on the path to work in in towards the internet and All that that was involved When that modem broke I Went down to guy and bought the v32 base modem if anyone remembers that And that was a fantastic upgrade and the guy that I bought it from Was a Internet startup in Ireland that later became the biggest ISP in Ireland and I later got a job from that So despite not getting a whole lot of money from the initial job, it was My first experience of the community and how it might benefit me in the longer term working with people I'm getting through it So today I have a confession to make I didn't actually write this abstract And I got some help with it And I was wondering how how am I going to? How am I going to present this and I thought about this from the point of view of DevOps so With documentation with the code this flow this continuous flow makes a lot of sense and From a documentation point of view we can we certainly plan instead of coding we write Tank, you know most times we do build documentation sets We test our documentation Which is very expensive from a person point of view to test documentation It's very hard to automate anything We you know people actually have to sit down and read the documentation in order to test it That often falls to the end user to do the documentation Instead of release and deploy We normally call it publishing and we publish the documentation they the operators where we Mesh with the software so as the user is operating the software They're also reading the documentation Monitoring is Mostly Feedback from the user about the documentation. So it's a kind of person person communication rather than something automated So I'm going to try To where we also have the same goals as DevOps in so far as We'd like to eliminate repetitive tasks and reduce friction and try to automate as much as possible I'm going to concentrate on the the extremes here today the the build process on the left and the Operate process on the right which in the software world is is Are very far apart? But I think with documentation. They're actually a lot closer together but I wanted to have a team for the stoke and And I was thinking that one of the big blockers we have is terminology terminology is the biggest sticking point with Documentation because people have different concepts when they see a word on on the page They already have a predetermined notion in their head about what that is So I wanted to Terminology terminology terminology I wanted to do it visually and I came up with With this as my diagram to represent the the terminology and I also got to reuse that logo Another so thinking about the left-hand side of that diagram the DevOps diagram at the beginning We we had a build step. So traditionally With documentation, it's written in some sort of source format in our case It's ASCII doc and then we build it in order to produce HTML to Show it to the end user but this little project here is where I'm using ASCII doctor JS to We should remove that build step. So instead of Building the documentation you can just throw documentation into repo and the GitHub pages will automatically publish it So just a hands up how many people know what ASCII doc is is it familiar to everybody in the room? maybe not half of the people and Just introduced it has been Marked it's very similar to markdown except it fixes some of the problems associated with markdown and You don't have to edit any HTML in order to produce a site with with this tool You just throw your markup files at the repo and it It renders them It uses pattern flow in order to to actually render the HTML and that gives us some advantages that you you get a responsive design and This whole process means that you're really only using a Gate as the content management system. So in traditional content management systems, there's all sorts of processes there With this that gets pushed that Problem gets pushed to gate and people have to be familiar with that But once they are familiar with it then it's it's it makes it It makes the rendering the publication side of it much easier. So back to the original oops The original problem so In agile We're trying to continuously push things out and that's That involves the build system we've already automated the the build we've taken out the build step by drawing ASCII doc directly at the ASCII doctor.js then it renders the HTML and that allows us to use that same JavaScript in order to automate testing for syntax and for structure And we're using gate for version control the One of the questions that I had for somebody one time because I kind of think as of Gate the number I think of when I Think of github is the 100 million repos on github that represents the huge amount of Usage of github. It's the most common use system for for software control for version control But somebody said to me they think of github on gith in general and they think of the number nine Which I was wondering how did you get nine from that? Well, they said there's In gith when you're working in gith, you've got the working tree You've got the index tree and You have the head tree and tree trees is not So I don't know whether that makes any sense, but I'm going to keep going The next questions after we've pushed the ASCII doc and displayed it to the user In the browser is could we possibly Add some more to that You know, what if the browser knew about your environment? So if you're logged into an application such as the umpchip console then obviously the browser has a Certain knowledge about the configuration of your application and the next step is to use an API and Inspect the environment and include that in in your documentation So as we were working on this particular project This is a link to the web app which Basically runs a light alongside the shift console in its own name space and but it allows the us to render the documentation within the context of OpenShift and thereby resolve a lot of Questions that the user might have so the user might be looking for the URL for a particular service that's already running in OpenShift and with With this particular web app That means the documentation automatically knows about the routes to the various applications and presents them in line in the documentation So when you click it on the Amq online link then it it brings you directly to that application the other thing it can do is it can resolve certain Environment variables in the Environment so if the doc if normally in the documentation we would sort of say maybe drop to the command line and Find out the value for a particular environment variable But with because we're rendering on the fly we can inject that value into the documentation while allowing the technical writer to remain writing in the Style in which they are accustomed so it doesn't require any programming skills or any extra Skills involved for the technical writer to be able to reference Environment variables CRDs routes Etc. We There were the UXD team Red Hat UXD team also were able to add some logic to the To the application so that we could ask the user if They have been able to succeed in their task and if they haven't succeeded in their tasks then They're able to we're able to present more information to the user So this reduces a a procedure from being a complex thing for the end user to complete and We just down into a nice experience and all of the code examples are rendered in such a way as they can Copy those from the browser If they need them in another context for instance another application Are on the command line? So how do we actually achieve this so on the right hand side? I've got some ASCII doc. It looks very similar to mark down It just has a slightly different syntax and the Unit of work in this In this application is a walkthrough This is a walkthrough called doing stuff You create an ASCII file You put in a level one heading to describe the walkthrough a level two Describes any particular tasks and if you want to to Break it down even further. You can create subtasks and these you push those to a github to a repo and Get hope get lab whatever and then the application renders a home page which shows all of the Walkthroughs and then you can read the introduction you can You know navigate the tasks and then there are also There's those questions that I showed you earlier there Know as verifications and then there are links that appear on the right hand side Which are either walkthrough resources that are global to the walkthrough our tasks resources that are only Useful in the context of a particular task so the the Red Hat UXD team were heavily involved in in working with this going back to the agile aspect of this whole talk they It wasn't just the engineering team or documentation We're also Working closely with the UX team UXD team and they are actually In the venue today. I'm going to look it up They're in the sea building by the docks whatever that means. I'm not sure Somebody just sent me a message. I put a call out because they moved from where they were yesterday And they are actually interested if anybody has the time and the interest to if you could drop by there and sign up because they Want to know more their testing alternative approaches for you know What happens when we have dozens and dozens of walkthroughs? We already have maybe 20 walkthroughs there in in this application and How would a user? Navigate all of these different walkthroughs How should we display meta data on that page? So every walkthrough is associated with certain services How and comes from a particular git repo? How do we display that and and they're also Very interested in the overall usability of the of this system, okay Now I'm going to take my life into my hands and Show you what it would actually look like Confined the page so this is the The web application that I mentioned there are a whole set of walkthroughs here and Actually, I'm gonna switch to this one because It's looking good in the Oops, oh, yeah, I need to how do I do that and pull it over here is it? Yeah, okay So I can maximize that so there there are various walkthroughs here But I have Just created this new walkthrough It's a very simple walkthrough And it has one extra component that I haven't mentioned earlier, which is that as There's a walkthrough ASCII duck file But beside the walkthrough ASCII duck file you can have a JSON file and in that JSON file You can provision new services in this case, I want to basically provision a PHP mySQL application When the user use you know reads the introduction And clicks getting started it actually in the background open shift provisions that service Now we you know as part of the task we're going to task which is in the next stage we're going to ask the user to To basically run the application and click on the URL but the URL isn't available at this point because the the Service hasn't been provisioned so You might see just as this gets rendered you will see the ASCII doc attribute that That is in the ASCII doc code And then as the service is provisioned you'll see that resolving to the URL It just resolved we didn't get to see it. That's it. That's been unfortunate, but I can show you the source code for that particular task and that might Kind of give you an idea of what is going on. I've got three screens all of a sudden Okay, you're just going to have to trust me on that one that the when you When you write the the code you don't know the URL for the the application but you can just put in an ASCII doc attribute and When the service is provisioned it Resolves to this URL and just to confirm that that actually doesn't work which is Which is disappointing Now now that that time you actually saw the attribute there for a second and when we click in it still doesn't work Okay, well, it's not really that the point of it anyway, so Let's go. Okay. That's this is why I don't do talks And I'd also love to know why I am not able to share the code Okay Move on. That's what they say okay, so So these this is What what happened as part of that process then as the team worked on this was that we discovered that We're not going to be the only people who want to write these waters that the community in the larger community Would also want to contribute to and and be able to publish their own waters and our tutorials and So we found that we were suddenly writing Doc walkthroughs about how to write waters how to find walkthroughs how to basically Increase the number of waters that are available to the Community as a larger at the moment the web app is very specific for a particular purpose but I hope that we could remove some of the Specific parts out of the web app and be able to make it more generally available for anybody who's running OpenShift That's and it could be used then for general OpenShift documentation our Documentation which is a specific to an OpenShift use case that that we haven't anticipated And the other question that I haven't resolved in my own head But I'm kind of investigating is how we could take this technique and pull it out of OpenShift and use it in the context of Perhaps Fedora like how would this look in cockpit as a way of Mingling the documentation and the actual application together in a single task That that's whereby we could have a more going back to the DevOps approach where We can basically push documentation to the users quickly as possible Remove the notion of building a documentation set and publishing it but rather integrating it into the Into the environment in which users operating giving them the information that they need and also been able to query the environment and give them the information without having to write a big procedure about how they have to Perform certain tasks in order to get a value which they're then going to paste into some other location and some other application Okay, I think I'll just pause there and ask for if anybody has any questions because I'd love to be able to figure out how I did this but if anybody has any questions now is a good time okay, I'm just going to go back to the To the code again, and this is the code. This is the ASCII doc for the The very simple walkthrough that we looked at there. It only has one step And it's Navigate to the URL this is the URL that we to the PHP app and It's related to the JSON file in so far as the JSON file calls for this service to be To be provisioned and then we're able to derive an ASCII doc attribute from that service name in order to be able to show it to the user So it's quite simple for a technical writer to kind of look at the JSON file pull out that value add You know prependable route and appendage with host and now they have the ASCII doc attribute name that can be used for the route and that same technique Can be used for other variables and other resources that are in the open-shift environment If we wanted to add a Some walkthrough resources to that particular Walkthrough then we can just add them in here So this is all standard ASCII doc any ASCII doc processor and I'm thinking of Antora or Our other systems similar systems And they will just ignore these these this annotation that we're using and it will It will just appear as a as You know basically exactly as if it was in the preview here if I open the preview I Can show you that It just basically creates a block With a link there But if we push that into an actual environment Which I'm going to do Here and I'm just going to restart this Then when we look at the walkthrough Then we see that Walkthrough resources have been added and the links appear on the right-hand side So there are other annotations that you can put into the ASCII doc to Perform different functions For example the amount of time that it takes to perform each task and Then that gets aggregated up to the task the amount of time that will take to complete the whole walkthrough Okay, if there are if anybody has any interest in this Please contact me and I can show you more of the the actual annotations and the And how they add certain functionality Especially the verifications And then there are also task resources, which is way of linking off to to further detailed documentation And but I Want to call it at that Anybody have any questions? Yeah, too. I'd like to claim one disclaimer here I introduced it as like the site list as if the site list came first when the site list came as a an idea after the web app was developed with and a lot of the the web app wasn't me it was UXD and Engineering from the Warford of Red Hat office Right. So and that's related at the moment We're not rendering any metadata at the moment, but most of the critical part of the metadata is there are two types of Water there are official published, you know core waters and then there's your stuff if you know what I mean So you can customize it all you want in OpenShift The in order to add something to your You know in order to publish a walkthrough Then all you have to do is edit this walkthrough locations here and add a gift reference to a to a repo so So people will be able to put in Into their cluster now into their own cluster. They'll be able to put in Their own walkthroughs that may not have been fully tested You know by us basically so But as long as we label them correctly so that when you're starting a walkthrough that you realize This is a tested fully, you know supported walkthrough as the same from this is Jimmy's walkthrough that he wrote on the bus on the way home or whatever and then you know, I think that's fine Can you talk a little bit about the interactions with the development team? So there's a new app coming down the road Instead of waiting for you to get a drone over the fence When do you come in? Because clearly you can come in a lot earlier here from you know when the Ideas after coming about so Yes, I can Yeah, so I suppose the whole point of all this has to think from the traditional traditional tech writer experience is you You you've given a project and they say to you, you know You have to document this and then you go down to the developer and they say it's not ready yet And you go back a week later, and it's not ready to be consumed yet And then suddenly, you know, they sort of say well, there you go It's all working now. You're good to document it. Oh, and by the way, we're releasing next week So that is that's the traditional approach As each of these walk these waters involve Multiple complex moving parts that are changing, you know Typically a water would involve three different products and those products are new versions of those products are being released at the same time So We with this is and we can get first draft out really quickly, you know You know just it's just push it in to get and hey press so where we're up and running now we can As I mentioned earlier one of the most expensive Parts of the documentation process is testing so we can get that in front of as many people as possible as quickly as possible and And we're working with engineering instead of against engineering in that process And we're getting feedback from you XD as well. So it's it's a much more inclusive process rather than a Segmented process which was the old way of doing things Anybody else? Okay. I'm going everybody gets to have a cup of tea early. Thanks everyone