Lucidworks Enterprise: hands-on documentation

With the global launch of Lucidworks Enterprise, we’ve also introduced a new online documentation system.  This is the complete product User Guide, documenting all the features and functionality of Lucidworks Enterprise.

What We’ve Done

In the earliest versions of Lucidworks Enterprise (which had very limited distribution), the documentation was in DocBook format and the User Guide was created during the product build process.  This was a powerful and integrated solution, but one that was difficult for a non-programmer to work with.  To make even minor documentation changes, we had to create a whole new build of the software.

Before we’d even decided to make Lucidworks Enterprise freely available for developer download, we knew we wanted to put our documentation online for customers to access.  Ideally, we’d be able to update the User Guide as needed outside of the software release cycle.   And we liked how MySQL allows customers to comment on pages of their documentation, creating a community of users who can help each other solve common problems.

Once we decided to make Lucidworks Enterprise freely available, we knew that the Guide also had to be open for anyone to view, although we decided to limit comments to registered users only.

We chose Confluence as the engine behind the User Guide, which we’ve been using for about 9 months as an internal development wiki.  When we looked closer at it as our publication tool, we discovered that it allowed us to accomplish all of our goals without adding administration layers that a full-blown CMS system would introduce (which we really don’t need at this point in time).

Benefits to You (and Us)

Things are never as easy as you hope they’ll be (that conversion from DocBook to Confluence is an experience I’d rather not repeat, although the Doxia Converter helped a lot), but we’ve been able to create a coherent User Guide and publish it with minimal programming resources.  We’re an Agile development team, and we need our docs to be ready to go with frequent releases.  By turning our User Guide into a wiki, we can update pages quickly and get new software out the door even faster.

Although we package the User Guide with Lucidworks Enterprise as a PDF file and HTML pages, we consider those to be snapshots of the Guide which may be out of date as soon as a day later.  We don’t anticipate major changes that quickly, of course, but being able to update our documentation and make it available to you in real-time is compelling.

Hands on doc

If you log in, you can post comments to any page and your comments and questions will be instructive to other users who’ve gone before you. This also helps us know what parts of the documentation or even our application are most challenging to you and allows us to plan improvements in those areas.  You can also “Watch” pages for updates via email or RSS (click the Tools menu to receive emails, click Browse -> Advanced to subscribe to an RSS feed).

What’s Next?

Although the User Guide covers most of what you need to use Lucidworks Enterprise, there’s room for more details and explanation.  It also doesn’t reference some of the inner workings of Solr or Lucene very often, so we plan to re-publish the Solr Reference Guide in this format in the coming months.  And of course there will be new software releases of Lucidworks Enterprise, throughout 2011, so we’ll be updating often.  In the meantime, let us know what you think and how we can make it suit your needs even better.