 So I was just thinking of creating a title for the talk and I didn't want it to be a technical documentation and all that, something boring. So I went with Zen type, so something like Jutsu or Dou and all that. I hope you know what Jutsu means, technique, Dou means a way of the way, you know. So anyway, I thought this was a clicker. Anyway, so what's the function of a good documentation? So basically it means it helps the rapid community growth and helps in bug fixes. You know, it avoids trivial bug reports as a good function of documentation. And basically they agree with more and more contributors than projects like Docker or Go-to-core. And how documentation can be like this, you know, it's total mess. You know, it can repel users and community. It can lead to spurious bug reports that are growth of the project and do a lesson code as well. So, you know, even the developers, they say documentation here, it did not be what you see on the web page or PDF. It can also be a comment. Anyway, so these are some of the projects I just listed, which I thought have some really good documentation. Radies I found to be quite excellent and place a great deal of stress on. Can you put it onto something? But if you move it, it cuts out. Oh, okay. You need to clip it. Otherwise it's just going to carry on. But don't fiddle with it. Okay. Anyway, you know, this also needs a better documentation. Anyway, so where was I? Yeah, so this is some of projects which I thought have good documentation, which inspired me as well. Radies or Go has some really nice ones, you know, for beginners. You know, the function of a documentation shouldn't just cater to a beginner, but also even to an experienced power user as well. You know, you never know. I mean, it should cater to the whole spectrum. And Docker, of course, you know, this grew to everywhere in no time. One of the functions of the documentation, what is it? Keep it fresh. Don't make your documentation go stale, you know, important. How can you achieve this? Some of the ways are, as I've listed here, are keep the documentation version control, you know, either in the same code tree as the code or as a JIT submodule or anything like that. And make sure that your documentation is in unison. What is there in the code? You know, don't make either one of them go ahead. Perlok is one of the ways in which, you know, the documentation is in the same body as the code itself so that it does not go stale. And one more thing is the timeline. So what happens is there are several versions of a project. And when you are reviewing the documentation, you don't know whether it's for the latest head of the project or the latest release or the latest beta or the latest alpha. So having a versioned timeline for the documentation of a project is also very helpful. And it can avoid a lot of ambiguity. Okay, and this is about the management. How do you manage? There are many projects which keep their documentation in continuous integration as the code itself. And the documentation testing, you know, that is something that not many do, but that also helps here. And getting the feedback from the user, continuous feedback. I've seen some projects doing that, like CoreOS and all that, you know, where they have a box in the end asking, you know, what can we do to improve and stuff like that. And user feedback. Actually bug reporting for documentation is another thing which is very helpful. And the reporting with context, you know, there are many projects which allow that. I think doki wiki and twiki and all that. Those allow that. But also, yeah. And this is about the formats. What format should you use? And the question is, which is better? Because some of the, which is better is not a good question because in many cases you need more than one of these. For instance, first two are the formats I've listed. But what about using a wiki for your documentation? You know, something which allows you to put the documentation out there, but also allows, you know, people to edit continuously. Because the problem with documentation is you don't have the perspective of the end user who uses it as a developer often. So having it in a wiki format can allow for better edits and less steep learning curve. And also having it in man tech and info formats are better when a person is using it for troubleshooting or on a server and stuff like that. Anyway, these are some of the tools I've listed that I found very helpful. And the one I use is Spinks. We use Spinks. But again, some like Haddock for Haskell and PerlDock with Cpan and Pandock, which is very helpful for converting between the formats and of course Spinks for the documentation, which is used again by projects like Python and all of them. And Oxygen for generating code, documentation from the comments. Anyway, so this is another thing that I thought I would stress in the documentation. It's that attribution. There's a lot of attribution for code, but there is not much for documentation, which discourages people from commenting more and more documentation. So that's something, unlike code, it's not much formal. But it's very important to... So it's very important to the project. It also provides an added incentive for people to contribute to the documentation. And since it is of high importance to the... If project leader attributes a high importance to the documentation contribution, it means more people will contribute. One of the issues that many projects face is that there are people willing to contribute, but most of them may not be willing to contribute in terms of code, but in other ways, such as documentation. So that helps attributing to whoever contributed it. And yeah, so this is another thing. For many of the comments and things like that, people find that the documentation is quite mechanical, something like Manpage, Visavi, something like a blog post detailing something. That is another thing that needs to be checked. The blog posts, they speak directly to the reader, and they are less mechanical, and they are more how-to-based, how-to-do stuff like that. So that is something that can be integrated into the formal documentation itself. This is something what I call as a normalization, but this is a normalization in the database parlance. So what is this normalization? I've seen documentation where you have two, three paragraphs, but with links branching out to several different parts so that when a user approaches a particular topic, something, say, ready a cluster, but then he has to jump to several links to understand that some of them points to different links, and then he has to collate them all of them and read it as one. So that's what I call it as a denormalized documentation. That is, it points to several places, as in normalized tables, database normalization, and all that. Whereas a denormalized is one wherein instead of pointing, you duplicate it. But there are problems with that in that it creates, again, stillness if you forget to update in multiple places, and maintenance can be hard. But again, there are some documentation engines which allow for embedding of the documentation so that you maintain one copy, but it's embedded in multiple places. Like RST, for instance, allows that. So that way, the user need not jump to multiple places, but at the same time, he can read it as a whole. But again, having completely denormalized is also not that good in that big chunk of monolithic documentation can be a turnoff for people who are interested in specific parts of it. So this brings me to the dialectics of it. So what we call as a FAQ. There are many projects for which when I started, I actually jumped to the FAQ, because the human way of thinking is through questions. How, why, what, where, and stuff like that. And this is something that also helps us in troubleshooting and for beginners. That's how we humans think. That's how our flow of thinking is. It's through asking questions. So this is also what you call as learning the hard way. There are, okay, what happened now? Okay, so this is what I call as learning the hard way. I'm sure you have seen those books, learn Python the hard way or those books wherein, you know, you're made to do some tasks and then, you know, through by asking questions and stuff like that, rather than giving you the answers. So that's the dialectical approach. And that approach, while this can exist in parallel to the existing formalized documentation. In that, you know, you have common questions that someone who is beginning, who is a beginner to the project can ask and, you know, you can have the answers which in turn point to the formal documentation. You know, that reduces the load, the mental load for a beginner and, you know, uses the learning curve. And this is, again, learning from patterns. This is something what I usually say that humans are better at learning from examples like machines are better at learning from algorithm. You know, reverse is what we refer to as pattern recognition and machine learning because where, you know, it learns from patterns. That's how we humans are. But what we often see is that some documentations, something like man pages, though now that is changing, lack examples, you know. And I recently saw Q&A on some Reddit posts where there were links for every command with examples. So having examples helps, always helps. And it always helps for anyone who wants to try out different, who wants to try out different ways in which they can use a particular command or a particular project or stuff like that. But you should make sure that how much it covers the project and so things. It also helps in quick testing, as I said. So the examples are very important. It also encourages the user of the documentation to actually try it at the same time he's reading it, you know, because that helps in better retention. Okay, so who are all the consumers of the documentation? This is something that a documentation writer or a project lead needs to take into consideration. So you have the end user for whom you need to stress on simplicity and for whom you need to check on the assumptions that he makes and his prior knowledge and stuff like that or whatever he needs to know before that. And then there is a developer. And for him, the document is like the code commands and design documents and stuff like that. Because as the project grows, you have more and more new developers joining and for them having good code commands is very, very vital. And then there are architects and DevOps and all of that. For DevOps, it helps with the reference code command references. And the troubleshooting part is what I refer to as a FAQ based documentation. That helps when you're troubleshooting. How do I do this? How do I do that? Why did it this way? Stuff like that. So I'm done. Further, I couldn't add more links, but these have a... I like the side, read the docs, since it collects documentation from several projects and has some nice maintenance and integration with GitHub and stuff like that. OK. That's about it. I'm the product lead for Percona XDB Cluster at Percona. But I also write documentation and keep care of the documentation for that project. And this is the image credits. Thank you.