04 October 2013

Docs! Docs! Docs

By Clinton Gormley

There's not much point in having an amazing piece of software, if users can't figure out how to use it. Over the years, we've had several complaints about our documentation: it's difficult to navigate, it's difficult to know where to start, etc. This is not unusual -- documentation is the bugbear of most software projects.

But that doesn't mean we can't make it better! So let's tell you what we've done so far and what we've got planned.

Docs and code, code and docs

Documentation should be an accurate reflection of the code it describes. Up until now, we've had the code and the documentation in separate repositories. Now, the code lives with the docs in the main Elasticsearch repository. This is good news both for users and developers.

Developers can include code and documentation in the same pull request and users can now access the relevant documentation for the version of Elasticsearch that they are using. We build a separate set of documentation for each major version, ie 0.90.*, 1.00.*, master. Changes between point versions are marked up as in this example in the function_score query.

So far, we have focussed on migrating the docs to the new build system. There are still a few niggles in the new docs. Please bear with us as we work on fixing them. Next we plan on improving them: making them more consistent, more complete, better explanations and more examples. This is a long-term project but you should notice a steady improvement in the documentation over time. We welcome feedback, suggestions and pull-requests!

One build system to rule them all

All of our projects will be using the same framework to provide their documentation. We have chosen to use AsciiDoc as our markup language, because it is easy to read, very expressive and, via DocBook, gives us the assurance that we don't have any bad links. Also, because we build all docs from each project together, we can ensure that cross-document links work and continue to work when edits are made later on.

Another good reason to use AsciiDoc and DocBook is that DocBook can produce output as HTML, PDF, EPUB and Mobi... and it is the preferred format for books published by O'Reilly Media!

The Definitive Guide

Yes! We are in the process of writing The Definitive Guide to Elasticsearch, to be published by O'Reilly Media. It was important for us to find the right partner for this book: we are an open-source company and we wanted the book to be open-source too. O'Reilly has a long track record of supporting the open-source world and we are thrilled to be working with them on this important project.

While our reference documentation is intended to explain how to use a particular API and what parameters it accepts, the book will focus on how to approach and solve problems: how to improve search relevance, how to handle multiple languages, how to tune Elasticsearch for your workload. It will be suitable for beginners who know nothing about search, but will have enough meat in it to satisfy the more experienced as well.

The book will be freely available online in HTML format both on our website and on O'Reilly's site and, when finished, will be available to purchase in hard copy from O'Reilly. The first part of the book is due to be published online in December this year. New chapters will be added as they are finished, and hardcopies will available for purchase in mid-2014.