[Music] all right we got lots of screens we're gonna see what we can do with them all right we got it we got I I'm gonna start out with a demo that I mean a slides and then I'll get into a demo so wish me luck that I get the screens right all right hey everyone thanks for coming my name is Dan Allen I'm a business owner open source project lead and tech writer and my main focus right now is on documentation tooling in addition to a ski doctor which some of you may know me for I recently launched a new project named an Tora and I'm here to talk to you about that today so aunt Ora simply put is a documentation site generator for sulfur teams more specifically it's a static site generator that's focused exclusively on documentation sites but also those that cover numerous products and versions of software so we're really talking about producing Enterprise documentation or documentation at scale if that's you know if you need to get to that point so en tour belongs to a category of software known as static site generators and specifically a software that implements an architectural pattern known commonly as gem stack and that stands for Java Script api's and markup which you just think of as old-school web sites everything that's old is new again but you can see some of the architectural principles listed here that that classify something is being part of this family of tools but an tor is unique in that it's architected exclusively for documentation and specifically documentation that may live in multiple repositories so we're kind of extending from that set it's also entirely based around the markup language asciidoc unlike a lot of its cohorts so if your preference is to write documentation in a lightweight markup format that I really think that that asciidoc is the way to go so let's recap what we've done so far so we so far the idea is you write content in ascii doc you feed that content to an torah and outcomes a static documentation site that's the general contract underneath the covers and tor is using ASCII dr. Jessica invert the asciidoc to HTML and then it takes that converted HTML and use handlebars to set that into a page layout and it gets information about how to do that from an torres UI model which we'll talk about later so at a high level you have asciidoc for authoring and you have an taurah for publishing just so you can get the tool straight now when I say documentation in this context I'm mostly referring to long-form documentation such as guides tutorials concepts those types of things so in other words it may look like this site might look like this or even this just to give you an idea now what all the sites I just showed you have in common is that they were created by software teams for software users and they got there by integrating the documentation processing it from from creation to publishing into the software development process and it's a methodology we refer to as DOCSIS code so you may have heard this so I'm going to I'm going to show you how software teams can use an Torah to create those documentation sites in this way but first I want to talk just briefly about DOCSIS code and why we're advocating for it so every group in tech interfaces with the docs in some way whether there are creators consumers or both and you can see just some of the teams that I've highlighted here in this diagram but the documentation ends up being the hub it's what's in the middle and that makes Doc's truly integral to the software process whether you're acknowledging it or not it's it's there it's part of everything that we're doing so we can't lose touch a bit the other aspect is we can't forget how important Doc's are to the to the user but ultimately to the success of the software so in many users minds when they see the documentation the quality of the documentation reflects the quality of the software it's the visual thing that goes with the software which is oftentimes doesn't have a visual component and it certainly paves the way for them to discover new features when a when a new release goes out so really they're forming their first impression about your software from the documentation they visit that if they don't get a good experience maybe the software is not good so that's why I like to say the documentation it's like the curb appeal of your software it's they see first if whether they're gonna buy the house or not they've determined almost right away oh this is not the house for me so you don't want that to be a bad experience you want that to be very smooth and you want to put your best foot forward now in a more serious term documentation can actually be the difference between a release going out on time and the release being held up you know we've all used software maybe that's skipped that right and they just did the release anyway but then you only increase the the cost for support because then users don't know how to install the new software or they don't know how to migrate so they're gonna call up support so that cost is going to show up somewhere you know I've even seen Doc's teams put under immense pressure that in the final week where the software goes is about to be released and then they turn around the docs team and ask them to write all the documentation for it and is the first they've seen it so we can't have that type of situation right we need to integrate this further upstream and it shouldn't be any surprise that polls tell us that poor insufficient documentation is the most prevalent problem and open source and certainly in software development in general so for these reasons Doc's simply cannot continue to be treated as some sort of satellite effort or to be honest not taken seriously we feel strongly that that those Doc's need to be brought into the software development process and hopefully as early as possible so that's what Docs is code that's what we mean when we say doc Cisco that's what it's all about it's to produce documentation by sharing not just reusing but also really sharing the conventions processes tools etc for software development in other words the documentation cites again made by and for documentation software teams and when I say software teams I'm also referring to tech writers I'm not saying oh now sulfur developers write all the code I'm saying we need to take tech writer and they need to go in the dot the software team they're part of it so and I believe going beyond this if I believe that making the doc source open transparent and easy to participate in that's also going to translate to higher quality more accurate Doc's so when you do this doctors code you're not just taking the processes but you're bringing it into the culture and and just like we benefit from having open source software we should benefit from having open source Docs so an tors goal is really to be the go-to solution for this and given the fact that it's just focused on documentation sites I think it's well positioned to be able to do that so let's examine some of just movie this society let's examine some of the features of an taurah that helped achieve this goal so first and foremost it's having distributed content and that follows a standard project structure so keep in mind an taurah is a multi repository documentation site generator in other words it speaks version control and specifically get so what that means is that ant or itself can draw documentation from a batch of source repositories and even branches and those source repositories and so those repositories could be exclusively for hosting documentation they could be the software or repositories themselves or some sort of combination of both some sort of hybrid now the inventory of these repositories you describe in a file we call the playbook which you can see here so the playbook really first and foremost the tells an tour where to go and get content from and you can see it mentions repositories it mentions branches and it even mentions paths within those repositories and if there's some configuration that's that you're not seeing above and below that as well so after collecting all of the content sources listed in the PlayBook and tor goes on to organize the files in the content catalog now the content catalog it serves as a virtual file system and that's for the documentation site is built from that so once the content is organized in this virtual file system and tor never goes back to the file system or never goes back to the git repository it's all there all the metadata about all the files is there so if you're a software developer it's done sort of application server type of work you'll you'll see this model it's being copied from that so a key part of making this work is that content files themselves are organized and you know it's interesting we take this for granted that software projects have a standard project structure but when you get to documentation it's just wild west so we're trying to bring some order into that and this structure not only allows an tour to be able to find okay I recognize this this is you know what is the the famous line oh this is Unix I know that's right this is a documentation project I know this so we can we can pick that up but it's also easier for writers as well because the writer will come into a project let's say Couchbase hires a new writer and like oh yeah I know I understand this I understand this project structure I can just start writing right away I don't have to learn this esoteric system now a critical part of building software documentation is versioning I mean the the software's version so the documentation needs to be version as well it's very unfair for the user and again or support but a lot of documentation tools just totally skip this AJ just published the latest Docs and that's it it's a deeper story so we're not talking about processing just some elute a loose assortment of files we're talking about processing files that have it can be categorized by product by version and so on and so forth now the version content typically it's sourced from branches that's not a requirements on a hard requirement it could be folders but branches is is really the best way to go and so if you if you want a new version of your documentation you have a new version you have a new branch and you add that to the playbook now within that branch you have a very small simple descriptor here that we call a component descriptor and it first and foremost it identifies the name in the version so this is how the files in this tree get categorized in the content catalog so in a typical setup the documentation would live in a branch that tracks the software releases so you may actually see as you do in this example 6.0 you may see that the documentation version is more coarsely grained than the software version which might be 601 because patch releases we typically don't need documentation just for those those are bug fixes and stuff so we have a slight difference and it's very important that you can continue to add documentation even after the release is done because you'll learn things and the user will learn things and you need to add that to the documentation this documentation lives on after a release and then what an tour does is it provides in the user interface it provides a version selector so you can toggle between different versions the documentation so while versioning is is definitely a complex issue and tor really tries to simplify the problem now another aspect of doing a documentation site is being able to make references and again this is the content catalog it's going to come in here because it not only provides this virtual file system but it provides a unified unified system for making references everything every resource in the site gets a unique ID implicitly and that's basically where it got taken from and it's path and you know it's product and version all that it's implicit okay so now we have a way to reference any page in the system and in fact any resource in the system and given the fact that an taurah understands these references it can also validate them so if you have any invalid reference it can say look I don't know what that is so when you make a reference to a page the family is implicit so you'll see that that this one is a little bit more complex than this one so that the idea is that we start to pare it down you don't have to specify all the information you only have to specify the information it's relevant for the context so what's unique and then the the system will fill in the rest so where you see this page ID most commonly uses when you do a page to page reference we'll just call that an xref so notice there's no URL here we're not interested in the URL the URL is irrelevant what we want to know is what page are you linking to what other resource are you linking to and then the URL is computed automatically it could even be prettified by the build system so you can have you know index off' ID urls or whatever extension this urls but what an tor is actually outputting is relative paths and that allows you to view the documentation site offline so it's not doesn't matter where on the web server it's going to be hosted or what domain you're publishing to it doesn't matter because all the links will work and you'll see that in the demo so just to show you how that works inside of a paragraph that's how an xref might look notice how i'm just specifying the path because i just say it's the file next to me the rest of its we share the same context so don't let that resource ID scare you it's just to let you know that implicitly that's that's how it's identifying the resource now you can also use other ways such as in an include so if you wanted to include an example or some sort of a shared piece of content you can use the resource ID again to pull that in so you don't care where the partial is located you just care what its ideas and you can pull that in all right so the other aspect is that ant or separating the build and the content I mentioned that already it's separating the content in the presentation so the UI is a completely separate software project it's not part of your site it's that that's a different software project so why would we do this well having if you manage the UI separately you have a couple advantages number one the web team can just do web projects they don't care about the documentation they just make a pretty documentation interface and when they're done they can export that and then you take that UI and you can apply that UI to all of your products and versions and that this provides a lot of room for customization because the web team can totally change everything about the user interface and brand it and make it look like your your company's style and aunt or it doesn't care about that you you just provide the assets it passes them through so then what happens the web team will publish a bundle they could publish the NPM they can publish it to a Jenkins server tube in trait whatever and then you to specify the URL in the playbook and antor will download that zip file that zip file it's pre computed UI materials so while you could certainly stick with the default theme which is what you see on the screen now circling back to those screenshots we saw earlier you can see how different you can make the user interface look when you sort of toggle through some of these screenshots and I'll mention notice in if I go to this particular site the navigation left-hand side is just for this product but what mule self did is they made their navigation left-hand side include the navigation for all products so that's an option that you have and Dodge's code wouldn't be complete without using the same tools and processes that we use for code now we've been talking about get but what else so first of all you you write content in plain text so content looks like code and this is very natural for programmers to jump in and help with now again it doesn't mean you get rid of your tech writers it means you add your developers and it's not just content pages that are in asciidoc the navigation that you so on the left-hand side is just a nested lists of asciidoc with references that we saw earlier so and at its heart and Torah is this modular pipeline of functions so we designed it this way to make it very open and hackable so unlike hugo for instance which is just this binary that you get and you just run it and that's how it works and torah is actually just function function function function functions so if you want a new function just add something in between you can do it so if you're a programmer trying to extend an Torah you know you can do whatever it is that you want we're providing sort of a framework for doing site builds now to publish a site it would live in a CI pipeline and so you can kind of see how an Torah you know will get installed the little taco chip there is an Torah so you install and then you run it etc and then you eventually sync it to s3 so again that you you use CI servers just like you do for your software and you might actually kick off those jobs based on sulfur releases all right so enough talk let's do some demo so just give me a second here while I reconfigure we need to be able to mirror the screen so I'm not looking behind me oh let's see enter in action looks good okay all right so my notes here so if I type ant or aversion okay I already have installed I forgot to undo it but if I didn't it's just distributed as an NPM package so I would just install it globally now I don't install just one package actually install - you'll see site generator default in CLI again this goes to that idea that an tour is very modular so the site generator is that sequence of functions so if you want a different sequence of functions just make a new site generator and you can have your own sequence of functions the CLI is separate from that so just so you understand why I'm installing two packages okay so if I type an Tora help write I get okay now we know and tours installed and the actual command that we're going to be working with is generate because the CLI could do other things maybe it has a validate command you know maybe maybe it can do publishing etc so there are other things that the CLI might do one day so we left room for that alright so that just gives you familiarity with what that commands all about alright so we mentioned there's going to be a playbook so here's the yamo file and what's important to notice here is we have three URLs we're going to take the home page which is its own repository we're going to take the operator which is a product the Couchbase makes and then we're going to take sync gateway which is another product and we're going to pull from some branches so we take the master branch for one we take the one point one branch for another etc so we can have all kinds of different branch patterns or whatever ant or can can understand all that so all we do then is we run an tour on the playbook and the very first time it's going to clone those repositories and it pulls them into a local cache and then once it's done cloning the repositories then it goes on and builds and so we know it's doing something because there's errors how would we know if software is doing anything if there weren't errors right so now we have the documentation site so this looks like what's published on you know on the production site but this is just running off my own computer look at the URL bar its file colon slash slash now you'll notice that some of the xrefs look like they're they're broken that's because we didn't build those things and you don't have to build everything and it would just basically say yeah there's no page for that but over here we have an actual page that was built so let's look at the parts of the page so we have on the left hand side this is the navigation to get from page to page on the right hand side we have the TOC for the current page so as I scroll I can see it following along and the breadcrumbs here would follow where I am in the navigation so if I went to deploy cluster for instance we would see yeah that it's that it continues to extend the breadcrumbs these though or all what you want to do if you don't want the breadcrumbs get rid of him if you don't want the thing on the right hand side get rid of you want to put on the left hand side okay so you can do those things but these are just that's what the UI model is giving you it's giving you a backing model for you to be able to lay information out all over the screen and if you want for instance to have this edit this page you can you can have that experience and then they'll go through the workflow and be able to see it on github and maybe they can make changes or if you don't like that you can just get rid of that it's up to you so that's the general layout now notice we have a sync gateway 2.1 but we only have one version of the documentation okay so let's add another version so go back to the playbook and we're gonna add another branch now a branch isn't necessarily a version right branch could be contributing more of the same version or it could be contributing new there's a decoupling between branches and versions but suffice to say if we add the materials we're gonna have a new version show up all right so now we go back and we see now we have we have two versions that are being offered but also notice and tour now knows hey this isn't the latest version there's a greater version available so it knows not only the references within the version but it knows hey there's other versions and which one's the dominant one so if I click view latest boom now I'm on the 2.5 version okay let's make sure we didn't miss anything so to do two component selector oh yeah so and then if we want to get two different products we have this version selector now Couchbase has a custom version selector so because they wanted a custom layout but if you but the model would just be able to just give you a flat list if that's all you wanted and we can jump so here we go to the autonomous operator and now we can jump between them so again it's very important that I can view this whole whole thing offline and here I have it the operator if I didn't want the operator yeah I can just get rid of it and build the site again now I have no operator so I can build like just one part of the site and not have to build all three gigs right so that's very important because the writer is probably only going to be focusing on a couple branches and a couple products so that's a it's a key value proposition of an taurah okay so we did that so let's say yeah let's do a page okay so what we're gonna do now is so right now we're just building directly out of github that's not going to be all that helpful for writing so we're going to do is we're gonna make a workspace and then we're going to clone one of those repositories so I'm going to clone the Couchbase operator repository oops that's not how you do it what am I doing wrong oh yeah because it's it's putting some spaces in there so now we're going into what we call author mode so what I'm going to do is I'm going to say alright I'm going to work on the one point one version of the documentation so the first thing I might do is just build the site to make sure I can still build it alright so we have a separate playbook file and this looks exactly the other one the difference is the URL in the second position is now a local a folder and the branch is specified as head which means whatever branch is checked out locally just use that one so now I'm going to run on that so we would clone the two repositories I don't have and then it would just use the folder for the one that I do have and so now I'm there so once again but now if you look at edit this page it's pointing to the local file so if we go back to the terminal and we edit that file so we can say like hello deadlocks yeah and then let's build it again oh we don't have to clean every time so now we have that so now let's prove that we reading locally so we have this mix of local and remote which is actually quite interesting alright so let's say we want to create a new page so it's as simple as this you just say an new page yes I do everything in vim so you might use atom right okay don't watch what I do I only use vim for everything so I'm do a new page and this is the page content and we'll build this site again but we won't clean it now you might ask what about automate automatically yeah alex has this question what about automatically building a site yeah it's we haven't gotten there but we can just run the thing in the background so it's always building the site but for now we're doing it this way all right so we just go to new page and there it is but the problem is is that how do we get to the new page well we got a link to it okay so let's let's go back to the overview page and we'll make a link to it so see xref now again because I'm in the same component and version I can just say new page and that's enough so back back to the intro and then new page now I can get to my new page but what if I want it over here I want in the left hand side so then I can just go to the navigation file so again I said navigation is described in asciidoc - and you should be able to recognize the hierarchy here so let's just put it at the top and it's not a feature yet but we have it where it'll automatically use the title the page in the navigation we just haven't implemented it okay so now we have a new page in the navigation now what if we want to link to a different component so let's go back to here and we say I want to I want to actually link to see a sync gateway getting started okay it's a sync gateway and I want to do 2.1 version 2.1 so I do 2.1 sync gateway getting started and so what that says is it's the version 2.1 of the sync gateway product it's implicit that it's route which is sort of like the default module and then there's this path within it so the only time you actually get to the doing filesystem stuff is when you're doing the path part the rest of it is all part of this abstract ID so we'll build it again and then on the introduction we should see sync gateway but notice we're going to sync gateway to point 1 but what if we want to link to sync gateway whatever the version is that's latest well simple solution to that problem we just say well I won't specify the version because ant we're already knows what the recommended version is so just have it put the version there and so now if I go back and click through now I'm on 2.1 version every 2.5 version okay so that's the the shorthand is really important there because we're trying to have it to the writers have to type as little as possible and to round this thing off we're going to do two things we're gonna totally change the UI and then we're gonna look at search so let's say we want to do okay we're building the couch based site but we want to look like the meal soft site okay so what we do is we just say use a different UI bundle and so you'll soft publishes their UI bundles to github so we can just use them now let's go back to here whoa now looks very different yeah so that just shows you the UI in the content or two completely separate things and what's interesting about that neill soft is they came up with like this little version selector that integrates into the navigation so they don't have a separate version selector everything's all their navigation is done in this one one part so that's kind of neat so we can do very different things and okay so what about search so this is just a static website so search anything that can crawl your website can provide search for you so there's a really great product by Algol yo called doc search and it's it's a search index that's really optimized for doing documentation it's a simple JSON configuration value which you say here's the URLs I want you to scan give me an index and then you can have a little JavaScript component that you throw into your page provides the search box so what I'm going to do here is I'm gonna build the documentation site but I'm going to link to a couch basis production in index and let's go ahead and clean just just to be just to be sure now there is a bit of a decoupling because the search index is not my local pages it's the actual production search index so if I clicked on one of the search results I would actually go to the production site but now I can do something like data sink and I get this autocomplete experience and I can basically click through and get the results now like I said those search results are actually happening on the production side but you could run you could run the Algol yo scraper at the end after you build the site you right in the scraper and then you can get your own index from Algol II and then you link to it so you just connect it up but again even the search is decoupled so this that's an important point there so let's let's wrap that up so there's the demo that's ant or in a nutshell oops and let's say go to the end here so so in conclusion so what an tour is doing is it's it's helping you integrate documentation production directly into an existing agile development workflow you know bringing everyone under the same roof so to speak so it's it's code first it's open it's modular it's DevOps friendly and it's really ideal ideally suited for doing everything from small scale to very large-scale documentation sites so if you're interested in you know in sort of taking your documentation to the next level and being sort of an innovative company with documentation definitely check out in Torah so thank you very much for your time and I hope you enjoyed it [Applause] [Music]