Neukonzeption des Solr-Referenzhandbuchs

Das Apache Solr Referenzhandbuch gilt als die offizielle Dokumentation für das Apache Solr Projekt. Offiziell wird es als über 700-seitige PDF-Datei veröffentlicht, aber eine Online-Version ist schon seit langem in der Apache Confluence-Instanz, auch bekannt als „cwiki“, verfügbar.

In Kürze wird die Lucene/Solr-Gemeinschaft das Solr-Referenzhandbuch an einem neuen Ort und mit einem völlig neuen Modell wieder einführen.

Warum ändern

Es gibt viele Probleme, wenn man versucht, etwas von der Größe des Solr Reference Guide mit Confluence zu verwalten, und die betreffen vor allem die Kontrolle und den Zugriff.

Confluence ist als Werkzeug für die Zusammenarbeit gedacht, aber die Lucene/Solr-Gemeinschaft hat beschlossen, dass wir die Bearbeitung auf die Committer beschränken sollten, damit wir eine zuverlässige Dokumentation erstellen können. Nicht-Committer, die das primäre Publikum und die Nutzer der Dokumentation sind, sind von diesem Prozess ausgeschlossen, außer um Kommentare zu Seiten abzugeben. Es gibt jedoch einige sehr sachkundige und talentierte Benutzer von Solr, die keine Committer sind. Wäre es nicht schön, wenn es für sie einfacher wäre, sich mehr zu beteiligen?

Ein zweites Problem mit dem derzeitigen Ansatz ist, dass wir jeweils nur eine Version online halten können. Das heißt, die Online-Version ist immer für die nächste Version von Solr. Gleichzeitig glauben wir, dass der Leitfaden hauptsächlich online konsumiert wird. Wäre es nicht schön, wenn wir für jede Version eine Online-Version zur Verfügung stellen könnten?

Außerdem gibt es eine Trennung zwischen dem Code an einer Stelle und der Dokumentation an einer anderen. Das bedeutet, dass die Dokumentation neuer Funktionen von der Entwicklung der Funktionen abgekoppelt ist. Das belastet den Entwickler zusätzlich und bedeutet häufig, dass jemand anderes versucht, Dokumentationen für Code zu schreiben, den er nicht geschrieben hat. Wäre es nicht schön, wenn Änderungen an der Dokumentation zur gleichen Zeit vorgenommen werden könnten, in der auch der Code geändert wird?

Abschließend zu der kurzen Liste der Probleme (es gibt definitiv eine längere Liste!), sind wir im Grunde auf das Aussehen und die Bedienung von Confluence festgelegt, es sei denn, wir wollen einige drastische und invasive Änderungen vornehmen, die bei jedem System-Upgrade kaputt gehen würden. Hier sehen Sie, wie der alte Guide heute aussieht:

Wäre es nicht schön, wenn wir das einfach umgestalten könnten, wenn sich die Bedürfnisse ändern?

Was passiert ist

Ende August 2015 habe ich ein Nebenprojekt gestartet, um zu sehen, ob ich das bestehende Solr-Referenzhandbuch auf ein neues Modell migrieren kann. Das Projekt lag lange Zeit auf Eis, aber im letzten Jahr habe ich es ernsthaft in Angriff genommen und für einige der schwierigeren technischen Fragen die Hilfe meiner Kollegen in Anspruch genommen. Die vorgeschlagene Änderung wurde von der Lucene/Solr-Gemeinschaft akzeptiert, und wir sind auf dem besten Weg, sie zu verwirklichen. Tatsächlich wird das Solr-Referenzhandbuch für Solr 6.6 in diesem neuen Modell veröffentlicht werden.

Was ändern wir also? Zunächst werden wir das Solr-Referenzhandbuch an einem neuen Ort online stellen(https://lucene.apache.org/solr/guide). Das Handbuch wird für jede Version von Solr versioniert, so dass Sie das Handbuch für Solr 6.6 oder 7.0 oder 7.1 usw. immer unter einer stabilen URL aufrufen können (wie heute die Javadocs).

Die PDF-Version wird die „offizielle“ Version des Leitfadens bleiben und wie bisher über die Online-Version zum Download zur Verfügung stehen. Wenn jedoch eine neue Version von Lucene/Solr erscheint, werden wir den Leitfaden für diese Version online veröffentlichen.

Der neue Guide ist in das Apache-Kommentarsystem integriert. Bestehende Kommentare in Confluence werden zwar nicht übernommen, aber Sie können weiterhin Seiten kommentieren, um anderen Solr-Benutzern Feedback oder Tipps zu geben.

Wenn Ihnen ein Problem auffällt und Sie über den Lucene/Solr-Quellcode verfügen, können Sie einen Patch einreichen, der geprüft und in die Dokumentationen für zukünftige Versionen aufgenommen wird. Wenn Sie der Meinung sind, dass es neue Dokumentationen zu einem Thema geben sollte, können Sie sie schreiben!

Wir werden auch die volle Kontrolle über alle Aspekte des Erscheinungsbildes haben. Der neue Guide wird ganz anders aussehen, mit einem dynamischeren Design, das auf kleineren Bildschirmen besser funktioniert. Hier sehen Sie, wie der neue Guide aussehen wird:

Hinter den Kulissen

Now some technical details of how we’ve made this happen. The current pages you see in Confluence will be converted to AsciiDoc format. This is a text markup format, very similar to Markdown but with additional extensions for flexibility. Specifically, we’re using tools from Asciidoctor in our build processes, so we’re focused on that project’s particular flavor of AsciiDoc to ensure compatibility.

For the online version, we’re using Jekyll to make the HTML pages. Jekyll is a static site generator, which takes our raw AsciiDoc-format files and applies templates to them to make a full site. This separation of content from presentation provides a lot of power, flexibility, and control over the documentation experience.

The raw AsciiDoc-format files will live in the Lucene/Solr source code, in a new directory „solr-ref-guide“. For now it has it’s own build.xml file to build the PDF and HTML versions (at the same time, or separately).

I’ll write some more posts in the future to introduce writing in AsciiDoc and submitting patches for documentation.

Timing

We have all of the big things we wanted to have in place before cutting over to this process: build scripts, Jenkins jobs, decisions about process, etc. The work currently exists in a branch from the main Lucene/Solr branch, and we’re tracking all the work in sub-tasks to SOLR-10290. You can take a look at the branch in the Git repo if you are more curious.

This weekend (starting 5 May), Confluence will be locked to all edits while we export the content and migrate it. About 90% of the migration is scripted, but there are a few things that just need a human being to resolve. My hope is this effort only takes a few days, and then we will start updating the content for Solr 6.6, which is planned for release in the next few weeks.

Stay tuned, there will be more announcements coming soon!

Some brief acknowledgements: While I kicked off the effort, we wouldn’t be this far along without the help of several people in the Lucene/Solr community as well as my colleagues and managers at Lucidworks. I’d like to especially thank the Lucidworks Fusion documentation team for blazing the trail and sharing their experience and some scripts to get us started.