 Okay, welcome to my slightly amended talk. I had my own continuous integration system over here, checking my spelling when I changed the title. It was a bit slow, but thanks very much. I've changed the title slightly mostly because I kind of had the idea. I've experimented with this idea a little bit since the call for proposals. So I've changed it a little bit, but it is still about automating things, maybe a little less about testing, but most definitely about automating or making things simpler. So I'm one of those strange people. There, go for it. I used to be a programmer, but then I kind of realized I was better at explaining things than actually doing it. So now I'm basically a full-time technical writer, technical blogger, a bunch of different things. This presentation is based on some experiments and also some blog posts I wrote for Codeship, who are a CI tool. Originally Austrian, based in Boston, so-called and Bostrian. A series of blog posts that I wrote about kind of automating some documentation that's just finished, so you can read a bit more on those if you want on their blog. But let's get started. So what is one of the first things you look at with your new project? And I'm going to use project to imply product, module, library, whatever. This is called a project. API. Stack overflow. Well, they're all documentation. They're different places, but they're all documentation. So I think most developers and most product people especially acknowledge that documentation is important and yet it often gets overlooked. I've got a couple of little quotes here. So this is kind of a nice ideal of where you're getting to with documentation. This is from Ken Williams, the founder, original creator of Pearl. So documentation is complete when someone can use your project without having to look at its code. And this is common. Often when you don't understand the documentation, you dive straight into the code and try and figure it out. But why is this? This is another quote from someone possibly slightly less well-known, but a guy I met from Wikimedia. When I was doing a similar talk to this, he said documentation is like housework. We all know we should do it, but we don't really want to. So what this talk is kind of about, it's not about better documentation per se. I actually have another talk on that and it's related to a blog post that you can find on my website or a Medium, which has actually been very popular, which is good because that was the point, which is kind of a crash course in documentation for developers. Just simple things to make a documentation better without having to think too hard. So this talk is kind of another side of that. It's actually about what can we automate? What can we make simpler? What can we have a bit of fun with instead of just writing? You might have seen my chinchilla earlier just as a guy with a fox hat walks in, which is very cool. I looked up for pictures of chinchillas doing experiments. Looking up pictures of animals doing experiments is not a good idea because you get some very not-so-pleasant pictures. So this is about the best I could find. It's a chinchilla reading a book. So basically this talk is more of just a list of experiments and ideas. It's a little incohesive. It doesn't really have much of a narrative. It's some ideas I've tried. Some ideas I haven't completely tried. Some ideas other people have tried. And I'm going to use tools and methods that are not necessarily the only way to do these things, kind of get inspiration from them and find a tool chain that works for you that does a similar thing, basically. So spelling, catching all those little mistakes. And one of the things about spelling is, yes, spelling doesn't necessarily affect the quality of the content, but it shows a certain level of care, professionalism, especially if you're working on a commercial tool or a commercial open source project or that has a large user base. It just shows that little bit of extra care that you go for. Spell checking is not new. Actually, I mean, spell checkers have been around for quite a long time, but what are some of the tools we can use to automate some of that? Well, one that I have been mostly using sort of, I'll come to this. One of the kind of grandparents of spell checking is Humspell. It's used in LibreOffice, OpenOffice, lots of Mozilla products. It's even used in Chrome. It's also used in Mac OS. It's used in, oh, what else? I've got a long list here, InDesign, apparently. I don't know if that includes other Adobe products or just InDesign, Opera, and a whole bunch of other applications. So the cool thing with this is you can keep consistent dictionaries as well. Especially in technical documentation, we have a lot of buzzwords, a lot of words that are incorrect but are actually correct. So we don't want to flag those as spelling errors. And the advantage of using something standard like Humspell is not only can we put it in build systems or in text editors, we can actually give it to people who use OpenOffice, not Office, unfortunately, but OpenOffice and other tools as well. So they also have access to the same list of custom words. So all our documentation can be consistent. So if you want to use Humspell directly, it's in most Linux package managers. It's also in Homebrew. Windows, you can get it in Sigwin, but it's not so easy as is usual with Windows. And then basically, this is a sort of the command. I'm actually just going to run this and then I'm going to kind of talk through what it is and what happens. And I'm going to keep switching backwards and forwards the demos. So I do apologize, but... So Humspell and Humspell are kind of loosely based on similar things. The main reason I stick with Humspell is just some of the tooling that uses it, which I'll come to in a minute. There's just more of it. That's basically it. Okay. So this is that command. The blue gets a little bit unseen. This will probably take... do quite a lot. So this has been running it locally. Of course, if you were going to do something like this on a CI, you would probably want to tidy this up a bit. I'm... Oops. Yeah, I'm doing all the node modules as well. That's probably not a good idea. Let's go to something more... a little smaller selection. There we go. Okay. So there's a lot of noise here. And I've intentionally done this example to kind of demonstrate some problems we have here, first and foremost. But let's look at this command first. So this is just checking recursive markdown files, setting the default system dictionary, which in this case is US English. And I've forgotten what the H is. Yeah. Oh, sorry. I've forgotten what the H command is. Maybe it'll come up in a second or we can of course always consult the documentation. What is H? HTML. Yeah. Okay. Good. But we still got here a lot of things that were not quite right. There's a lot of code being highlighted as spelling error. There's a YAML front matter in the markdown file being sparked as problems. And this is so default, by default Huntsbell isn't really designed for checking code. So this is not so useful to us at the moment. Obviously, there are ways to get around this and this is why I intentionally showed this first because the next one I'm going to show you is one that kind of respects markdown at least. Depending on what you're spell checking, this could still be a valid option. But what I've been using especially for markdown and there are equivalents for this for other markup languages, ASCII doc, RST, et cetera, et cetera is an MPM module called markdown spell check. And you can see some of the commands are slightly similar and it will respect the markdown formatting. So let's try that one. And that for some reason is not good. That's all right. The module is called markdown spell check but the command is empty spell, which is slightly confusing. But in this case we get firstly a much nicer output and secondly it's respecting code blocks. But we can still see there are some words in there that are correct but not correct in kind of default English. So how do we handle things like that? So this MPM module in particular uses a dot spelling file. I won't zoom in on it. It's just a list of words. That's it. Basically it's a dot spelling file for this module that you can put all the custom words that should be accepted by. There is a reason for that. I'll show you something I haven't done which is it's in the wrong place. It should be the annoying thing with this module is it always wants to file on the top level. So in my Travis files in this case we have it clones it and then moves it up. So in this case we get less errors. Yeah, didn't move. No, I mean the wrong folder. That's it, yeah. Yeah, I mean the wrong folder. Yeah, you just need to move it to the top level of the folder basically. And so I must admit the markdown support for this is the better one but there are other options for it. That dot spelling file though is not actually a recognized dictionary if you wanted to use this in open office or something like that which is annoying. It's a shame that the module uses a slightly different format to normal Huntsville but I found this blog post with this very memorable URL and it's quite an old blog post but it does work that shows you had to convert the dot spelling file to the AFC and dot-dick files that open office and et cetera, et cetera expects. So you can put that into your build system too. It's just bash commands and you can have kind of everything available to people to use as you add new words. The other advantage is Huntsville is pretty well integrated with lots of code editors so I use Atom a lot personally. There's a module for it. A lot of the other text editors have it by default again and it's available as a module for most others. So again you get that nice consistent experience of the same custom words, the same flow everywhere you use it. Okay, spelling. Actually I will, no I think you could get an idea of how the command looks. I won't bother showing you Travis out but I think you get the idea. So the negative with some of these and it's not so much with this one but it is with the other one is deciding whether spelling errors should break a build or not. Especially because you have a lot of custom words. So firstly just deciding whether it should lead to a successful build or not and secondly if you don't want it to break a build you need to make sure it returns an exit zero otherwise it will break the build. So I have a lot of overrides. I use the kind of spelling text as a guide for now whilst I'm tuning them and I just force them to succeed and then I just go and read them later. Otherwise it depends how important it is to you but that's one note. So writing better. This isn't just grammar. This is kind of advice on writing better too and actually there's a lot of commercial tools for this as well. Grammarly is probably one of the most popular ones and unfortunately they don't have any kind of API or any sort of CI tool. It's just a desktop application or a website that you just paste the text into but also the kind of open source equivalents are things like Alex and some other modules that do similar things but unfortunately I have found that Grammarly often highlights has better suggestions which is unfortunate but a lot of these modules again are repositories so we could make suggestions. I mean it starts to get who knows best when you come to something like language is a bit of a woolly area but anyway. So again I like to use this particular module called write good which is great. Namely it combines a couple of the different tools. So for example trying to reduce extraneous words you don't need. Removing potentially insensitive words. Some of the tests can be quite interesting. It seems to highlight every country as a potentially offensive word which I find interesting. Sorry. Every country is highlighted as potentially profane which I don't quite get. Maybe like Switzerland laws. But you can see here so again it's an MPM module works in a similar way and you can by default you'll run all tests or you can run particular tests or you can run all tests ignoring particular tests basically. So again I will show a quick example of this. Just run it on everything and again this is much more sort of personal and I would probably recommend you don't break builds on this because it's a lot of it's for guidance especially in technical language. Sometimes there's certain things that are not very good English or good language that you write in but there's still the best way of saying something because it's technical language. So it's much more for guidance and it's not as quite as helpful output. I love this tool but the output especially on command line is not great unfortunately. I was wondering if with this tool and with the previous tool is it possible like for example when you have source comments you can put like comments in to squash the warning in a particular place so is it possible with those tools? That's actually something I've not looked at. So you've looked at the message you've actually put an exception somewhere. So these basically are all linters and actually if I show you how they look in Atom for example they feed into the linter in Atom and it's actually much nicer to look at than the kind of the command line output but that I'm not 100% sure about. I'm gonna show briefly another tool later that may be more useful for that but they're all basically linters but instead of code we're linting language which is much grayer of course but yeah. So that's the kind of output you get. So this is with all tests. So for example this is passive voice. This is unnecessary wording there's a whole bunch of examples there. Yeah and it's up to you whether you consider it useful or not. I would definitely use this much more for guidance. Another one and I'm gonna show this because when I did this talk before someone mentioned it is an application called language tool which is a Java program. It also works in as a Chrome extension and part of OpenOffice. I'll show it and you'll probably quite again immediately see the problem with it but it's a little slow. There's one thing. It gives some nice guidance but again the problem with it is for plain text so it doesn't recognize code. So that's a fairly big issue for technical documentation but for other documentation it may be okay but it gives some kind of better guidance instead of just sort of dumping a bunch of problems at you. So okay. Next steps with this again continuous integration is certainly possible. Annoyingly the right good module as an exit code gives you the number of errors which is really unhelpful. And I've had nightmares trying to get this to work well in CI and actually at the moment in my experience with it I've disabled it again because I've had difficulties getting it to play nicely but your own mileage may vary. And again as we just saw when I showed you quickly an atom and other text editors it's available as a linter kind of input and it's probably much more useful actually in your live writing as opposed to on build tools. Okay next screenshots. This is a cool one. So if you have an application that has a graphical interface screenshots are extremely helpful in helping people understand particular interface elements and what something means but they are extremely time consuming to make and keep up to date. If you change a CSS style in your application then theory all screenshots need to be recreated. So doing that manually is time consuming and very easily comes out of date. So can we automate it? Of course we can otherwise I wouldn't be talking about it. And this is so I've borrowed this very heavily from the Plone community. The Plone community and the Python community in general actually has really cool work on automating documentation and a lot of the tools are often Python tools as well. So they are like years ahead of everybody else which is unfortunate if you don't do Python because you just kind of are envious of some of the stuff they have but a lot of these examples I've pulled a little bit out of the Plone documentation and you can go into their GitHub repository and find how they've done it themselves because it's really, really cool so the stuff they've done. But in this particular case I'm using kind of tooling that you're probably using for other reasons and just sort of combining it. So firstly, this is basically using Selenium the web driver that lets you kind of mock up web pages. So yes, in this case this is mostly for web applications but there will be equivalents for other types of application. And then I'm using the robot framework to define tests. But in my particular case I'm not testing but of course the great thing here is you can combine this with your tests with your QA people or yourself and kind of combine the tooling. So at the moment the examples I'm going to show you kind of the screenshots are getting generated but they don't automatically end up in the documentation. You just maintain a kind of file naming standard that when the screenshot gets updated the documentation is updated. In the deployment documentation they actually have this running inside the documentation which is the really cool thing but it only works in Python. So that's not too useful if anything else. But so firstly you need a web browser on CI this is probably going to be phantom.js but if you're doing it on your machine you can use Firefox and other browsers too. And then these are the frameworks we're using. So the robot framework has actually has a screenshoting tool built into it but it just does full screenshots full screenshots all the time which is fine but we could be more precise. So I'm going to run this I'm going to show you a simple example. This is actually what I did for the Codeship blog post and some of the more observant of you are going to see my password here for my account. I'm going to trust you. So here it is. Feel free to trust us but change it up. Actually that's a very good point I could just here we go. Actually then I can't run the test I'm going to trust you I'm going to trust you I don't have any particularly admin rights or anything so all you have to do is create some projects. So it's not that interesting really. So this is a bit fuzzy. Ah good point. Okay. And we all know use one hand for the password. I'll change it a minute. Maybe I just won't go back into the other file. Okay but this is a series of tests. I'll run it first. So I do have it open here. It runs the test I've defined. It's a little slow because we're actually firing up phantom. We also have to bootstrap jQuery which is annoying but so it's a little slow. And this is also going to a live website to do the test. So we're relying on internet as well but it was just a nice example for the article. Thankfully I got a pass. And if we have a look inside that folder you'll see we have an image there. I'll actually show you because I have it also does something quite cool and adds annotations to it which can be customized. You can get rid of this sort of default style but it's quite cool. So notes. So click here login field you know actual like instructional information. So basically what it does here is you have two files. One sets up. If I go back to my password actually maybe I can remove it now. Because I'm going to be hovering on this for a very long time. I know but that was very very brief. There we go. So it sets up the variables. It sets up some keywords we're going to use. Basically. And then this is the actual test and the magic that we're interested in in particular is this. So highlight the form and you have various ways of selecting the element with CSS or other things. Add a note. Again with the text, the position, the style and then capture and crop the screenshot with a file name. Again setting the div, the class, whatever. My password is there as well. This is give up on this idea. I'm too trusting. And so at least here you can see that we can keep a consistent file name and then you can build that into the documentation. But if you look at the if you're lucky enough to be working with Python you look in the planning documentation you can see how they've actually built this straight in to the documentation. Is that your Gmail password? No, no, no. It's not my Gmail password. No, that's okay. And I have two-factor authentication on that. Okay. So the next steps there, not a lot but hooking it up to CI, of course. Making sure you have those consistent folders and files and things like that and that especially if you have a graphical application is a really, really cool feature to add in. So testing. So probably one of the biggest frustrations you've often had in documentation is you go to a page, you read a code sample and it doesn't work. Happens all the time. So maybe we should test the code examples to check that they do work. This kind of falls into two camps. I'm going to start with the easy one which is maybe tenuously part of documentation and then the harder one. So the first one is actually testing APIs, API documentation. So again, there are lots of options for this. There's various ways of describing an API, file formats. So in particular at the moment, in this example using something called API Blueprint which is kind of this weird markdown hybrid that you can also define API endpoints, expected parameters, expected output and then it's testable but it's also just marked now. So especially if you're a writer, it's quite a nice format to work with. But this swagger, this ramble, there's a whole bunch of other options and it's also of course the option of documenting your API code and working that way around. So there's a lot of options, a lot of commercial options, a lot of open source options but just for the principle, I'm going to stick with this tool Dread which is what we currently use. So in this case, we pick the file we want to test. We define the API endpoint. We have some hook files that let us do some processing at various points in the build. So for example, at the moment, there's a parse error in one of the linters of the API Blueprint specification and it breaks all the builds and they've acknowledged it's a problem. So at this particular moment, I have a hook saying skip that test because I know it's always going to break. So until I'm told that's been fixed, I'm skipping a test. And there's other things you can do there at various kind of stages in the life cycle. So again, let's have a look at an example. Let's close this horrible. So in here we have, I'm going to find the, here. This is actually the expected, the final output. There's a lot of documentation here, but the bits we're interested in are here. So defining the endpoint and some parameters, the parameters that we're going to send to it and the expected output. I've changed the structure a little bit since I prepared this. So I just need to double check it still exactly where I expect it to be. I'll tell you one second. Let's just run that because this will take a bit of time to run. So whilst it's running, hopefully, Oh dear, it could be the Wi-Fi. Anyway, you get the idea. It could be the Wi-Fi or it could be a very big problem that the company I work for. Who knows? We're not sure. But anyway, you get the idea, you see expected, and then you get a summary at the end. So April is just a commercial hoster and provider of some of the tooling, really. You can. In fact, Dread is written by April, but about 90% of the tooling they offer as the commercial product is available just as projects you can download as well. So it basically comes down to who you want to host a documentation. They have like an interactive console thing and the error reports go into their interface instead of Travis or something like that. It's kind of up to you really. But you get the idea there. They usually mostly pass. But anyway, we'll see. You see what's supposed to happen. And of course, this kind of thing is fundamentally designed for CI systems. So it's useful for running locally, but this is usually integrated into actually writing your APIs as well as just documenting them. There's other options. This one was mentioned to me before. If you're a JavaScript program, you can actually write the tests as kind of JavaScript objects which might appeal to you more. There's Postman, which is a desktop application that you may have used for testing API endpoints. And they have Newman, which is kind of you can create collections of your tests from the desktop application and then run them in a CI tool. And then there's so many others. So that's reasonably straightforward. What about testing code? Now, this, okay, I'm going to show you the example first and then look at the negatives. So I have some Python here, an RST file. And this is using Sphinx, which is a documentation system for Python code. I think you already see what the problem is here, which is really, really cool when it comes to code examples. So a lot of people say this, like, wouldn't it be great to test code examples? But there's a couple of problems. Firstly, when you show code examples, you usually just show a snippet, like make a loop or whatever. But that loop would not run in isolation. You need variables set up. You need libraries imported, things like that. So either you, in every example, so Twilio does this in their documentation, they include everything you're ever going to need, even if it's just a simple output. Or the cool thing that this does is it actually has these three, two blocks here. Sorry, the setup. So what you need to do to make the test work, but it isn't shown, the actual test that you're going to, the code you're actually going to show, and the expected output, which also isn't shown. So when you run this, yeah, it tests the code example. It wasn't very complicated, but it shows you what got tested. But the end documentation only shows you the code snippet. Now that is super cool. I think it's a really awesome way of doing it. But there is one big problem. It's only for Python. So I did tell you they have some of the coolest tools, and that is one of the coolest, and it's only for Python and only in RST. So if you're not using those two, you're a bit stuck. I haven't yet found any solutions to this. The ones I have been suggested are things like keeping your code examples externally and bringing them in to the documentation so they can be tested independently or using some kind of regex to parse the examples, output those to a file, run them, et cetera, et cetera. Not ideal, but there's some ideas. Depends how important it is to you. And if anyone has a solution that I haven't found, I'd love to hear it later because it's something that would be really, sorry? Just write some perl. Just write some perl. Yeah. Okay. Now I think I have a couple of minutes so I do have a little bit of time for my bonus material, which could be very, very quick. Things like generating multiple formats for EPUBs, for PDFs, all sorts of things. Pandoc is my tool of choice. I love Pandoc. It basically lets you input a bunch of different formats, output a bunch of different formats. It's very flexible. The documentation, unsurprisingly, is good. The person who does most of the code is very helpful and it's a little hard to look at. But so basically this would go through all the markdown files. I'll start at the bottom. Generates HTML. Actually that shouldn't be there, that line. Generates HTML from the markdown, but also generates a PDF. Generating PDF from markdown requires, with Pandoc requires delving into the wonderful world of LaTeX. But if you don't want to do anything complicated, you can just go with the default templates for that. But LaTeX is kind of fun in itself. It's like CSS for print sort of, but much more complicated. But this is a really cool way of generating manuals out of HTML documentation, things like that. And there are even services that will make this a bit easier as well. But it's a very, very cool tool. Editor snippets. So this, I don't know if you can see this little video, but it's things like having language shortcuts or custom shortcuts. So I have something, a tool I use here called HerQL, which lets me create special markdown links and I have a snippet set up or I have an introduction that we put on all our GitHub repositories. Instead of me typing it each time, I have a snippet set up that I just have to type a couple of letters for and then I have the boilerplate text ready to go. And HerQL, if you're doing markdown, is what's called Transclusion. So you can actually have reusable bits of markdown that you can then bring in to other places and link them together and then render them together. So if you want to kind of have repeated texts that you don't have to literally write every time, there's kind of two little ways depending at what stage in the process you are to make that a bit quicker and easier. And again, most text editors, I'm sure I've forgotten some. I tried to include all the main ones and have snippet support either built-in or as a package. Finally, said, this is a placeholder thing. So this is something I've been using recently. So in the documentation, I have lots of placeholders for examples. So we have a product that has, you need access tokens, you need space IDs, you need a bunch of different things. And if we feel like we want to change the example at some point, I could do a big search and replace or we just have all the replacements defined in a bash script and then we just have to change them in one place. And when the documentation is built, then it replaces them all. I might come back. I just wanted to share a tip that what we do is, for example, when we show examples in bash, we set all those as variables. Yeah, yeah, yeah. It's another way to do it. I went down this path for some reason and it works for me. And that's a really nice way of just having examples that you can swap out within one place. Again, reducing the amount of extra work you need to do. So if you're interested in knowing more, this is actually, again, a memorable link to the sort of writing better documentation blog post. Koala is a really cool tool. I saw someone with one of their t-shirts on earlier. They're mostly around Hamburg, but they've just been doing the rounds. And it's basically, so a lot of these were what's called lintas. And Koala is a way, it's a tool that lets you combine multiple lintas into what they call Koala bears. I'm half Australian so it makes me laugh. But yeah, it's not quite there, but they have some really nice ideas. And it's Python, of course. But you can actually wrap the Python round other languages, which is also cool. Test the Docs is a little project that myself and again, some of the people who use some of the Plone documentation are kind of working on alongside Write the Docs, which is a sort of writer's community about testing docs. Not much there right now, but that will happen. And if you're interested in just chatting about these sorts of things, then the Write the Docs community has Slack channel. I think we still have IRC as well. And why even bother with all this in the first place? My golden words are that documentation isn't just for developers. So let's make it as usable and nice as possible for everyone to understand and appreciate.