 Okay, so this presentation is about how I left my word processor and embraced Eskidoq. This presentation was done in Eskidoq, rendered to HTML, and displayed on Firefox. So who am I? I was a developer for 12-ish years, doing a range of stuff from mobile to embedded to cloud to, I don't know, desktop, I guess. And now I'm a consultant at Red Hat Services. I work on cloud, OpenStack, cloud management, and deploying this for Red Hat's customers. But that's all about me. My next slide is about question. Who thinks documentation is really important to a project? I expect everyone to raise their hands. Whether it's configuring an HTTP server, whether it's looking up your function calls in Python, or even setting up your own cloud in OpenStack. Without documentation, you're pretty much stuck. Well, there's thoughts. You could make your API discoverable. You could make your code easy to read. But at the end of the day, when things go wrong, you look at documentation. Who likes writing documentation? Great, I expected that. But we must write. We must write. If we don't write, well, I really like this quote. Nick Coglian is a core member of the Python software foundation. He's also a Red Hatter. So this quote is, unless your UI discoverability is really good, saying the feature isn't documented is the same as saying the product can't do it. How many of you have seen the YouTube clips, kids with old computers? It's really funny. If you've grown up with computers in the 90s like me, you'll learn that, hey, to turn on a computer, I've got to reach around the back and flick the switch. And kids don't understand. It's not discoverable. And something that's so second nature to us growing up like this, we didn't even need documentation, but kids now, they need to be told what to do. Well, this kind of adds to the strength of the argument that documentation is really important. Writing is hard. And I'm going to go through a few bug bears that I find in common work processes. First of all, UI elements are distracting. As you can see in this picture, we're trying to write one document, but we've got 50 buttons surrounding a text pane. 50 buttons. I don't know about you, but when I start my work processor, the first thing I look at is, hmm, what font size do I want this to be? Should my headers be 24, 36, serif, sans serif? Are my bullets indented four spaces, two spaces, and so on? I end up looking at how the document looks like rather than what's actually in the content. So that sucks, right? In contrast, I love the clean UI we get with our new editors, right? You can go back to Vim, Emacs. We've got Sublime Text. We've got my new favorite Atom. Kudos to the GitHub people here. And the nice thing about these editors is they let you focus on the content. There's a common sort of UI language here where the main content is in the application. You can make it full screen and focus just on your text and nothing else. I like that. Bug battle, easy to make mistakes. Who can spot the errors in this diagram? Go ahead. Oh, this one and the title, this one and this, right? So technical analysis for Megacorp and report created for massive dynamic. So who's seen this before in their own company's documents, right? We've all done that. We've seen it. We've probably done it before, right? And even the title of the document is yet another company. It's very prevalent. So what I like in SEDoc is, well, we can define variables to substitute throughout the document, right? Minimize errors, automate mundane stuff so that these things don't get in your way. The next thing is outdated references, right? How often have you updated a document, added a new section, but forget to add references, right? Refer to section two for a certain feature. But then you forgot that you added a week later another section that pushes this section down. And then you've got an inconsistent document. In SEDoc, you can have cross-references and anchors to each part of your text, right? The beauty of this is you can have multiple sections and they always refer to the same place. You can have your documents split into multiple files and they still will refer to the same place when you compile them all together. But therefore, copy and paste hell. We've all done it. I'm guilty of it. I've got five documents. You want to compile it all together for a single consumer, right? Again, references, wrong all over the place, numberings, all messed up. So SEDoc has a nice feature of composition. We can have the combination of macros defined for a document to be spread throughout this document. We can compose several documents together, mix and match, right? In this case, I've got effects, which I'll show you later, basically talks about what this document is about, who is it for, who is it written by, and so on. We've got revisions, which you probably can guess from what it says. We've got prefaces, we've got domain content, and so on. And the nice thing about this is you can reorder it. And the numbering on the final document will be nicely done. Another thing I like about SEDoc is repeatability and customization. This command will work whether it's on my laptop, whether it's on a customer site, or whether it's even generated automatically through some other portal. I think I see at least one of you in the audience who's seen an example of a customer documentation written in SEDoc and created using a make file. Again, this is another example of changing branding depending on who your target audience is. You might want to have a different logo, right? And all you need to do is change the template, right? And of course, in my case, I made this presentation in SEDoc and I compiled it to a presentation. So this is the part where I demo. Let's go to here. To create this presentation, I used a tool called SEDoc, which created a presentation using DeckJS, right, from my current presentation.sqdoc. Oh, sorry. Better? Okay. So just a simple command line for the tool. As I mentioned earlier, I'm using the Atom Editor. It's got a very nice plugin for SEDoc preview. So all I need to do after I write my SEDoc is press Control-Shift-A and it renders my SEDoc in a window by the side. The nice thing about this is you can modify it, right? And it's dynamic. So I've got macros as well. This is a larger example. It's actually taken from one of my projects. I mentioned just now that there's a fax document for every document I generate, right? In this case here, I have subject, description, author, email, and so on. And the nice thing is I can define my source highlighter through this tag here and I can see the style, right, what color scheme and so on. When I do references. Now this importing that tag on line 50, that's an example of an anchor. And how I get to the anchor is through this. And even right now it's on the same page, but even if it's on different pages, it will refer to the same anchor when I compile it to the full document. This make files a little bit more complex, but I'll just walk through it line by line for you. The first one just creates a simple PDF document using SC-Doctor PDF. This is a plug-in for SC-Doctor, which generates, well, as you can guess, it's a PDF document. The target branded journal is a little bit special because it adds in a custom theme. In this case, it's the Red Hat Consulting logo which gets plastered on top and some footers and headers that get added to every page. So I'm making the plain document now and it generates a plain document, no backgrounds, no headers and footers. And we've got very nicely generated table of contents all clickable in a PDF and we can even go back to that link I was talking about. So if I click here, it goes to the right place. So if I mouse over, it says go to page 14, but in effect, whether it's page 14 or page 1400, it doesn't matter because the references have already been created and anchored in the right place. So I'm making the next target now, which is branded journal. This takes in templates from another directory that I've created somewhere else with JPEGs, sorry, PNGs and headers footers defined in the document. Now it comes out with a very nice professional looking header. You can see the fonts have changed a bit from serif to sans serif. It's a bit smaller, it just looks cleaner now. And all this was done without any change in the source text. It was just a different direction to style sheets. Any questions so far? No? Yes? Okay. So it's a YAML file. It's quite a big file, of course, because this has been customized for the company's styles. But if you were to start from scratch, I advised to go with a few, figure out how they work out or even find some from the web and copy and customize them. And I've used custom fonts as well. sq.com comes with some default fonts. I've added liberal sans, regular italic and bold. Now these are actually in my local file system, which I placed here. And that's what makes the fonts look a bit different from the first one to the second example. Okay. So I've got a few links. There's actually some books written in sq.im published on O'Reilly. O'Reilly does have a portal dedicated to using a couple of text-based formats to publish the books. sq.im being one, then Markdown being another. And the nice thing about the first link is it's actually, it's actually the source is all on GitHub. So you can actually see how this guy wrote his book in sq.dog. Okay. There we go. The internet is a bit slow, so I'm not going to go through this. Thank you. This was a very short presentation. I hope you enjoyed it. Do you have any questions from anyone? I haven't really used latex that much, but to me, sq.dog was simple, it was easy to use, and within Red Hat it was used across quite a number of our open source projects. There's also something else which I didn't mention here called sq.binder. Sq.binder is a project meant for managing documentation across a large open source projects with version documentation and so on. So I think the ecosystem around sq.dog is quite nice. I like it. Markdown is really, I mean Markdown, sq.dog, these are the class of markups that are kind of like email friendly. Email inspired. Yeah. Email inspired. And Markdown, one of the things that distanced me from Markdown in the beginning was Markdown doesn't do tables in the standard Markdown, there's GitHub flavored tables, there's other flavors. Things all the Markdowns we keep using and seeing, they all get extenders, like we have tables, we include dynamic stuff with expandable sections, and it's a very rich Markdown. Well, we don't make it, but we would be looking for things for documentation. And I was asked, I was told to look at sq.dog and one thing that made me not do anything was it's going to be hard to make it dynamic. We have a unique problem. We actually have to support multiple different languages as an API from the same API source. Do you mean I-18N? Mm-hmm. I-18N or Programming Languages? Programming Languages. Okay, okay. So there's a C API, C++ API, JavaScript API, but it all comes from the same class, the same APIs. So they share some documentation, but other bits are language specific, and I have yet to find any documentation thing that works this way. We have to have a little drop down menu, say, I want to be in C++ mode, I want to see C++ developer. I don't care about the JavaScript stuff, and it'll hide that and show the right things. I had not found it. That comes up, the question, but it comes up in a number of tools that are, there's only APIs in browsers where you're going through documentation. Yeah, but everyone's written something in a browser like a back end PHP or whatever, I don't know, to do that and generate it. There isn't like a standardized tool. So- So that feels like a gap that someone should fill. Yeah, we're going to have to fill it ourselves, like everyone else. And especially with network at the end, because we're absolutely certain that the other end of code will be technically language. So it's a method snack. But then, I'd argue that that's kind of a parallel discussion because that's code documentation, and then there's other types of documentation where it's further, I don't know. In this case, what I have is customer documentation where it talks about the overall use cases, and there's less code involved. Sure, but the things we're documentation is API for programmers. But it's available in N languages. And since it shares a lot, you don't want to rewrite all of it. So it's shared in the language specifics. So that feels like you're assuming there's something like a means of marking a block that's belonging to a particular case. So we're literally basically creating our own documentation system, just as solid, so we haven't found a solution. We're generating markdown, and then we're having a whole wiki actually do the rest of it from there. Cool. I'd like to see that. So the idea is you can then go to the wiki and actually edit the common sections they shared. You can edit the language-specific sections. So your second question was, who likes writing documents? Kate writing it. Yes, thank you. Hello. Who are you? The signal. Oh, I didn't know you were here. So, yes, as our signal points out, we have about five minutes, which means we can continue with the discussion, but is there a canon in the room? Yes. Is Michael canon in the room? The level's back here a little when you went. We won't have quite a bit more than five minutes. Continue, it's more than that. He's not ESO. You'd have to write your own tool. Yeah. The Doctogen is pretty much the tool for that. But it has big downsides. We've been using it for years, and we've hit the point at which we're kind of too big, and we didn't spend enough time really maintaining it. So now the mess is so big. Literally, we do make Doc, and it takes us about one to two minutes for a documentation to generate. I remember spending a day or two trying to fix that documentation. I gave up. It was a cycle of, does this actually make sure that this section is actually linked in? I've got a link and I can find it. It took me so long to figure it out, I gave up and threw my hands here and didn't bother anymore. But Doctogen is the only one for that. And you pretty much want to be writing it from the day you start writing your code. It's comments in code. And it's a CC plus plus mostly. I used Doctogen quite many years ago. It worked until, I guess, the skill. It's a skill problem. At a certain point when you either get big or complex and then you don't really look after it for a while, it becomes a big, hairy ball of mess to fix up again. Does anyone have any suggestions?