 I'm going to be talking about a very boring topic. I know that documentation is not really our preferred activity, but I'm going to try my best and keep you guys awake. My name is Eric. I work for a scientific research organization. And most of the managers in there are actually scientists. One of the things that we're working with these kind of people is that they're very big in something they like to call reproducible research. This is the concept of when, if you say that you have A, or you do A, you always get B. And it has to be true pretty much every single time. It's one of the most common known scientific principles. They like to apply this kind of thought process to pretty much everything, and that includes the documentation that I produce for my environment. Now, here's the problem. Documentation is hard. We all talk about in general about how documentation is critical for the environment, how you need to have it in a production system, and it has to be fully up-to-date and everything. But these are obviously some of the problems that we usually find. Documentation is not generally complete. It's generally out of date, and it's inconsistent. By this I mean that if you have, say, two servers that are meant to be identical, chances are that if they were deployed at different times, the documentation will be different for both of them. There is not much that technology can help us do about the first problem. It's essentially a human problem. I think that we are generally lazy by nature, and there is not much we can do about it, but we can try and be a little smarter about the other two. There are many tools that we can use for writing documentation. The most obvious ones are on one hand side, Microsoft Word, LibreOffice Writer. These are enabling you to create super content-rich documents, text images, videos, whatever you want. You can just put them in there. I find using these type of tools very cumbersome. The documents are heavyweight, it's not really easy to manage or to play around with. To be honest, chances are that if you're using these kind of tools to write your documentation, your managers are also asking you to put this stuff up on SharePoint or Lotus Notes. This is a process that I like to think is the same as, let's put this stuff over here so that no one looks at it ever again. On the other hand side, we have TXT files, Markdown, HTML, these kinds of documents are very easy to create, very easy to manipulate and play with, but the problem that we have with them, aside from having to learn the language unless you're using pure text files, is that there is no inherent revision history. Documentation is obviously an evolving organism, just like your environment. You need to be able to change it over time and track those changes as well, so you know who did what and when. This is not something that you can automatically do. You can put lines at the top or at the bottom explaining what happened, but there is no universal standard for that. The only option that you have is really to put these files into some sort of version control system. That's yet another layer that you need to worry. In the middle, you have tools like MediaWiki or any other Wiki software for that matter. I actually really like this one because I think it strikes a good balance between the two. You get the best of both worlds, and editing pages in MediaWiki is actually quite simple. Even if you don't speak wiki text, it's fine. You can just go there, open the editor and you get most of the times where you get edited and you can just contribute to it. One of the problems that I find in pretty much every single place that I worked on that uses MediaWiki or Wiki software for their documentation is the uncontrolled proliferation of pages. This essentially means that people seem to find it easier to just create a new page with a little bit of information or instructions that they want to document instead of going through the trouble of finding an existing set of instructions and updating those or contributing to that. So you end up with something like this. Two different articles explaining how to do, in this case, something very trivial, but just because they didn't feel like going to the existing one and updating it. They often also forget to categorize a page whenever they create it or to at least add it in some sort of index so that it's easy to find. The result is that you have to end up sending emails back and forth to actually find the information that you want if you don't know what the key word is. Now, a while ago I was looking at configuration managers. Please raise your hand if you haven't heard of Puppet, Chef, Salt or Ansible. No one, yes, also. It's pretty much unthinkable that you haven't heard of these tools. I think they're amazing. All of them, they're very, very good at what they do. It's quite impressive that you can just create modules, stack them up on top of each other and end up with the configuration that you want for your servers. So then the thought came to mind immediately, why can modification do the same? If I have a patch installed on pretty much all of my web servers and then I discovered that I need to have PHP installed as well, I shouldn't have to go around and chase files all over the place and update every single one of them by hand, which is obviously impossible to do if you have a whole bunch of files stuck up on your shape on database. So this is where MediaWiki came into play. I thought about a concept of documentation snippets. This will be very similar to what you will call code snippets. These are essentially tiny set of instructions that are reusable, so not server-specific. They're always the same everywhere. And you should be able to update these snippets only once and then just apply them to your servers. MediaWiki has a very cool feature that you probably have heard of, which is called Transclusion. If you didn't, basically what it allows you to do is to embed the content of one document or one page into another one. So if you update the first one, the second one gets updated automatically. And this sounded exactly like I wanted. So I started using it in my MediaWiki instance at work. This is a very silly example of how you will use Transclusion in a real world scenario, but if your documentation is server-centric, something like this will come in very useful. You just update the installation instructions or the configuration instructions that you want, and that gets applied automatically to all the servers that embed this page into it. Now, I just said that these set of instructions had to be the same everywhere. And this is true except when it's not. Sometimes you have applications that you need to configure slightly differently, depending on where you deploy. I'm guessing, say, if you have a development environment and a production environment or servers that are on different buildings, they will need slightly different set of instructions for how to deploy them. And you want to have those documented, but you don't really want page proliferation and have two different articles explaining how to install the same thing. Modern versions of MediaWiki, pretty much every single one that is supported out there, now combined by default with an extension called parser functions that you can enable. And if you combine it with parameters that are arguments that you can pass to a page when you embed it into somewhere else, suddenly you have a lot of power in your hands. You can do fancy stuff like this. Essentially, parser functions allow you to create logical workflows in your document so that you can display different content depending on a condition. This is a very, very silly example where I choose to install one extra package if the requirement is to have the server held up enabled. Now, this is everything very easy to visualize if you actually use a live example, so I have prepared a weak instance for you. This is a cut down version of the actual MediaWiki instance that I have at work. I edited it heavily to protect the innocence, so no confidential information here, sorry guys. But at the bottom here, you can see how I have documentation snippets for two on how to configure the network, depending on the value of the server, one very simple one on how to discover a new disk that I add to a virtual machine, and if I look at a code of this, you can see how I'm using parameters to change dynamically the disk size of this documentation snippet whenever I embed it into a server page. I'm also using no include tags to create a category for just a documentation snippet, but if I wanted to automatically categorize the pages where this snippet is actually embedded on, I can do something like this. And if I save this, every single page that actually uses this snippet will have the category automatically created, which comes in very handy. Let me show you a real-world example of how this will come in useful. This is an example server where I describe how you need to configure the network, how you install Apache. This is an example of how I use the snippet that I just shown you. And then we install MySQL server, maybe a backup script for the MySQL database. This is a lot of text, and this documentation is actually very, very verbose. I think it's very foolproof. Most of us will know how to do this stuff by heart anyway, but anyway, it's just there for the sake of it. If I show you the code for this wall of text, that's what you get. Just five lines of code, and that's all you need to have a fully verbose documentation of your servers and how you deploy them. Now, most of the documentation that I have is essentially server-centric, but I discovered that I spend most of my time documenting how to install different applications, because some of my servers actually have just one of them, and some of the ones will have all of them. To show you how parser functions work, I have how to deploy a media week instance, which is, I think, a nice example. And in the usage of this document snippet, I can see the different parameters that I can pass to this snippet whenever I embed it somewhere else. So let's have a look at how it works. Say that I want to, on top of all this, deploy a media week instance in here. I will just call the media week template, and I will say, I want my LDAP extension configured as well. Preview, and then you have all the documentation that you have on your snippet included into this page automatically. A final thing, which is something that I mentioned in my abstract, is the ability to export all your documentation to a PDF or some of the formats. I did it already because, you know, time constraints, but this is all documented here on the week itself, which is available for you to play with. It's actually public. You can just go here and see how I am doing this and the scripts that you need. And this is the final result. Single PDF, with index included, and you can see your entire weekly content is just a single file, which will come in very handy if you say have a disaster recovery scenario and you need to grab all the documentation from somewhere and you don't have access to your documenting server. So that's it for me. Any questions? Pits that you've written, that you have obviously put aside that you then link back in, how do you curate that content and how do you keep it straight in your head? Which snippets you have so that you don't forget? I try to include pretty much every single snippet that I create in its own page. In this case, it's not in here. But essentially I try to add every single page that I create into another one so that it's always linked. One of the things about the Exporting to PDF feature is that it will only export the pages that have a link to it. So you need to actually force yourself to put the link to the page somewhere. And I have actually seen many places where the pages are actually created in the Wiki, but they're not referenced for many where. If you use the special pages feature of MediaWiki and find orphan pages, you will see that the only one in my case is the main page. And if you see any other pages in here, then chances are that you're missing something and that you will have a hard time finding it. And you should create a link somewhere else to keep track of it. Still answer the question? So how do you avoid the needle in a haystack problem where you go, I know I wrote a snippet about that, installing PHP or whatever. How do you go and find that? Sorry, I don't understand the question. I'm just wondering when you've got a very large amount of snippets and you're dealing with a large data set, how do you avoid the needle in a haystack problem? When you know you've got a snippet about something or you suspect you have a snippet about something, how do you go off and find it? I don't actually really have a problem, to be honest, so I don't know if I can answer the question. Most of the snippets that I have are very, very simple. I just list them in a page somewhere. So if I know that I documented once how to install something or how to install an application, I'll just go and look for it. Thank you. Sorry. Any more questions? Do you have any recommendation for how to actually keep the snippet content to match the changing other reference information? Like many people would be using a configuration management tool alongside a lot of their deployments and configurations. So the documentation would often be what is the manual equivalent or the why behind a lot of those configs and settings? Is there any way to tie these together to avoid the problem of actually having the two drift apart? Forgetting to update the snippet when you change what you do with your config management, is there anything you can recommend in that way, like a synchronization script or something? It's actually a very good question, and I thought about it while I was preparing the presentation because obviously what's missing here is a link between the documentation, why you're actually typing here, and why you put in your PAPN manifest or your configuration management module. I don't have an answer at the moment. I don't. Basically, I just make sure that whenever I make a change in my servers that applies globally, I update the documentation on my wiki, and because where I work, I'm basically a team of one, I can do that. But if you have a team with multiple people, you need to rely on them actually remembering. There has been one extension for actually deploying an open stack environment based on media wiki. So I imagine that it wouldn't be very hard to create an extension to actually link the media wiki content with, say, PAPIT or any other configuration management out there. But to be honest, I'm not a programmer, so I don't know how to. Anyone more questions? Yeah, I noticed that you're talking about your documentation representing what's in PAPIT. The way I view this is that your PAPIT document manifest should be clear enough that they are the documentation. If you thought about actually, in terms of whether you need a wiki page to say the server is built like this when it's clearly defined in your PAPIT manifest. So let me see if I understand the question. You're asking if I can, instead of putting stuff in media wiki, I actually document the stuff in the, say, PAPIT manifest, and use that as my documentation back. And yes, it's a possibility. You can obviously include comments in your PAPIT manifest or whatever module you use for configuration management. I actually find media wiki easier to use, and it will help you in some borderline cases where not everything is managed by PAPIT, stuff like the standard configuration that you use for UBM Gold Image, for instance, won't be in your PAPIT manifest necessarily, and other things that you say need to get from Windows because our Linux servers actually are living in a Windows-surrounded environment. You cannot really put into a PAPIT file. This covers pretty much absolutely everything that I need, so the only link that you have missing is how to synchronize or keep in sync the content of your documentation versus the one on your configuration manager. But yes, you can definitely do it your way, and you probably won't be missing anything. Any more? OK, thank you very much. Thank you all.