Das Making of adoc Studio

Wir haben Mitte 2004 festgestellt, dass Dokumentation wichtig ist für unsere Projektmanagement-Software Merlin Project. Während die Entwickler fleißig am Code arbeiteten, kümmerte sich das Serviceteam um die Dokumentation. So begann eine Reise, die erst viele Jahre später erfolgreich endete. Ich meine dabei nicht die Inhalte der Dokumentation, denn ein Handbuch für eine sich kontinuierlich entwickelnde Software ist sowieso nie abgeschlossen. Unser größtes Problem war immer die Software oder Technik, mit der wir die Texte schrieben und die endgültigen Dateien erstellten.

Microsoft Word

Natürlich wurde nach guter Business-Manier automatisch zu MS Word gegriffen. Hier muss man wissen, dass die Version von 2004 unter Mac OS X (so hieß das macOS zu der Zeit) eine sehr wackelige Angelegenheit war. Unter großen Schmerzen haben wir für Merlin 1.0 eine Dokumentation am Start gehabt. Da die Word.doc-Binärdateien nicht in ein VCS (Version Control System) – damals setzten wir noch Subversion ein – passten, verteilten sich hunderte von unterschiedlichen Kopien des Handbuchs auf diversen Datei-Servern. Natürlich jedes Dokument mit einem anderen Stand, der aber teils nur minimal unterschiedlich war.

Wir verloren sehr schnell den Überblick und somit manche gute Version des Merlin-Handbuchs aufgrund unüberlegter Löschungen. Uns war klar, dass wir darauf kein Software-Business aufbauen können.

LaTeX

Für Merlin 2, welches 2006 erscheinen sollte, wurde uns durch unseren Geschäftspartner Tom Alby eine radikale Änderung vorgeschlagen:

Wenn du eine umfangreiche Dokumentation brauchst, nutze LaTeX. Du kümmerst dich nur noch um den Text, den Rest macht das System für dich. Fertig.

Natürlich hatten wir keine Ahnung von der Sprache, und wussten auch nicht wie wir an den nahezu unüberschaubaren Befehlsumfang jemals verstehen wollten. Aber wir hatten sofort den Vorteil, dass die Texte in dem neuen VCS, namens Git, eingepflegt wurden. Also haben wir Tom dankend gebeten, das Handbuch für Merlin 2 zu schreiben.

Das Ergebnis war hervorragend. Wir bekamen neben den Quelltexten auch ein exzellent aussehendes PDF.

Unser Plan war es, die Wartung und Aktualisierung des Handbuchs intern durchzuführen. Allerdings stellte sich heraus, dass wir uns hierbei überschätzt hatten. Wir konnten neue Texte hinzufügen, aber das Hinzufügen neuer Abschnitte gestaltete sich bereits schwieriger. Komplett neue Bereiche oder Umgestaltungen waren für die meisten im Team einfach nicht möglich.

Nach und nach weigerte sich das Team, die LaTeX-Dateien zu bearbeiten. Damit war auch der zweite Ansatz gescheitert.

HTML

Es muss so um 2008 oder 2009 gewesen sein, als wir schließlich zu einem etwas weniger technischem Ansatz kamen. Da die ProjectWizards-Webseite zu der Zeit von Hand in BBEdit als HTML-Seiten gebaut wurde, lag der Weg nahe, auch das Handbuch so zu erstellen. Von LaTeX hatten wir bereits gelernt, den Inhalt von der Gestaltung zu trennen. So funktionierte es in HTML auch. „Ein globales Stylesheet formatierte die HTML-Textdateien. Natürlich passte auch alles wieder in das Git – wir waren glücklich.

Das Problem lag bei PDF. Zunächst haben wir versucht, HTML als Standard zu etablieren, jedoch ohne Erfolg. Wir versuchten die Qualität unserer PDF-Dateien zu verbessern und suchten nach Alternativen wie den direkten Druck aus dem Browser, um diese Herausforderung anzugehen. Unsere Kunden ließen uns schnell wissen, dass sie ein vollwertiges PDF-Handbuch wünschten.

Wir kopierten den Text aus dem Browser und fügten ihn in MS Word ein, um daraus dann ein Dokument zu erstellen. Das Ergebnis war erneut unbefriedigend.

Dieses Problem begleitete uns während der gesamten Zeit mit Merlin 2. Das Handbuch und dessen Ausgabe waren weit entfernt von einer zufriedenstellenden Lösung.

Markdown

Mit der Entwicklung der dritten Version der mittlerweile umbenannten Software „Merlin Project“ sollten Verbesserungen eintreten! Wir hatten aus den Fehlern der ersten Jahre gelernt und setzten uns das Ziel, ein ansprechendes Handbuch sowohl im PDF- als auch im HTML-Format zu erstellen. Dafür stellten wir eine Liste auf, die die Anforderungen an die Dokumentationstechnologie festlegte:

• Die Texte müssen in ASCII mit einem beliebigen Text-Editor geschrieben werden müssen.

• Das Encoding muss UTF-8 sein.

• Die Ausgabe erfolgt im Standard als HTML, aber auch PDF und ePub muss möglich sein.

• Das Design der Ausgabe muss von uns beeinflußt werden können.

Auf den ersten Blick erfüllte das in 2011 schon recht populäre Markdown alle Anforderungen. Es gab sogar schon erste Apps, die explizit auf Markdown setzten, wie z. B. Ulysses, von unseren Freunden aus Leipzig.

Beim Schreiben stießen wir immer wieder auf die Einschränkungen der Sprache und erkannten, dass wir das angestrebte Ziel nicht erreichten. Markdown mangelte es an:

• Tabellen

• speziellen Inhaltsblöcken

• einer umfangreichen Formatierung von Bildern

• und vielen weiteren Optionen

Wir benötigten eine effektivere Methode, um das Handbuch für Merlin Project zu erstellen. Unser Vorteil war, dass die neue Version der Projektmanagement-Software noch nicht fertiggestellt war. Das ist eine andere Geschichte.

AsciiDoc

Auf einem Team-Meeting wurde die Idee für einen neuen Ansatz vorgeschlagen: AsciiDoc. Eine Sprache, die von Stuart Rackham bereits in 2002 erfunden und entwickelt wurde. Vom Grunddialekt sehr ähnlich zu Markdown, aber an vielen Stellen viel weiter entwickelt und deutlich flexibler.

Die ersten Tests machten bereits einen positiven Eindruck auf uns. Wir konnten unsere bestehenden Texte relativ schnell in die AsciiDoc-Notation überführen und waren von den Ergebnissen sehr angetan. Nur die Geschwindigkeit war – gerade bei längeren und komplex strukturierten Texten – nicht optimal. Aber was interessierte uns die Dauer um die Texte zu bauen. Wir waren glücklich über die Ergebnisse. So wurden sehr viele Dokumente erstellt. Von kleineren Anleitungen, die nur für den internen Gebrauch vorgesehen waren, bis hin zu öffentlichen Dokumentationen. Irgendwann hatten wir auch das Merlin 2-Handbuch in AsciiDoc übernommen und konnten den Kunden auch wieder ein echtes PDF präsentieren.

Dann wurden Gerüchte laut, dass Stuart Rackham AsciiDoc nicht mehr weiterentwickeln könne. Natürlich waren wir in großer Sorge, denn um 2013 herum basierten alle unsere öffentlichen Dokumente auf diesem Markup-Dialekt. Schließlich erfuhren wir, dass sich Dan Allen um AsciiDoc kümmern würde. Diese Nachricht erleichterte uns sehr.

Noch vor dem Erscheinen von Merlin Project im Jahr 2015 hatten wir die Möglichkeit, das neue Asciidoctor mit den alten AsciiDoc-Dateien zu testen. Die Ergebnisse waren identisch, jedoch hatte sich die Geschwindigkeit beim Erstellen der Dokumente vervielfacht. So konnte unser neuer Zauberer am gleichen Tag mit den neuen Handbüchern in HTML, PDF und als ePub erscheinen.

Das Resultat

Seit 2012 wird bei ProjectWizards AsciiDoc und später Asciidoctor verwendet, und es hat sich als festes Werkzeug etabliert. Wir haben ansprechende Stile und Vorlagen für alle Ausgabedateien implementiert. Die Pflege der bestehenden Dokumente funktioniert einwandfrei. Nur das Thema Editor war mit BBEdit noch nicht perfekt gelöst.

Ab 2012 stellte sich eine weitere Herausforderung mit dem iPad. Nachdem wir schon eine Merlin Project-Version für das Apple-Tablett hatten, wollten wir auch unterwegs an unseren Texten schreiben oder diese zumindest korrigieren. Das war möglich, allerdings gab es keine Vorschau für unsere Asciidoctor-Texte.

Sowohl für macOS als auch für iOS haben wir nach einem geeigneten Editor gesucht. Leider war BBEdit ausschließlich für den Mac verfügbar. Eine Option war Ulysses, das auch auf dem iPad läuft, jedoch verwendet es nur Markdown als Sprache.

Nicht nur für das iPad waren wir auf der Suche, sondern auch für den Mac gab es die eine oder andere Herausforderung. Im Team wählte jeder seinen Editor, was grundsätzlich in Ordnung war. Allerdings traten Probleme auf, als einige Editoren die Dateiencodierungen nicht richtig setzten. Die Folge waren kaputte Sonderzeichen oder fehlende Umlaute. Diese Probleme verhinderten teilweise einen reibungslosen Einsatz von Asciidoctor.

Ich verbesserte die farbige Hervorhebung der Asciidoctor-Syntax in BBEdit, aber sie war nicht zufriedenstellend. Daher entwickelte ich ein BBEdit CLM (Codeless Language Module), das suboptimal funktionierte. Die Vorschau entsprach grundsätzlich der gleichen Datei im Browser mit der Asciidoctor.js Live Preview. Diese Methode erwies sich jedoch nicht in jedem Fall als praktisch. Auf dem iPad funktionierte sie erst recht nicht.

Technisches Schreiben auf Mac, iPad & iPhone

Testphase starten

Die Suche

Die Suche nach einem gemeinsamen Editor intensivierte sich. Wir befragten Freunde und andere Entwickler nach einem Editor, und die Antworten waren meist die gleichen. In den letzten Jahren sind auf dem Mac einige sogenannte IDEs (Integrierte Entwicklungsumgebungen) populär geworden. Diese bekamen durch die OpenSource- und insbesondere die Asciidoctor-Community spezielle Erweiterungen zur Unterstützung unserer Wunschsprache. Damit konnten wir alle arbeiten, hatten nur das Problem, dass diese nicht auf dem iPad liefen. Außerdem wurde deutlich, dass Entwickler-IDEs primär für die Bearbeitung von Code in verschiedenen Programmiersprachen entwickelt wurden und nicht für das Verfassen langer Texte ausgelegt waren.

Bis wir uns an den Start von Merlin erinnerten. Die Initial-Zündung war in 2003 eine fehlende Projektmanagement-Software auf dem Mac. Heute fehlte uns eine AsciiDoc-Umgebung für Mac und iPad.

Die Lösung gestaltete sich jedoch nicht ganz einfach, da auf dem iPad keine interpretierten Sprachen ausgeführt werden dürfen. Damit schied Asciidoctor bereits zu Beginn aus den möglichen Optionen aus. Andererseits erwies sich das auch als Vorteil, da für uns bei ProjectWizards nur Software-Projekte von Interesse sind, die nicht sofort nachprogrammiert werden können.

Eine gewisse Innovationshöhe muss gegeben sein, damit nicht sofort viele Wettbewerber auf dem Markt erscheinen. Daher war uns klar, dass unser Produkt einen eigenen Parser benötigte. Doch damit nicht genug. Auf einmal sprudelten die Wünsche an ein nicht existierendes Projekt.

Das Vorprojekt

Im Oktober 2020 stand ein Textsystem für Mac und iPad, basierend auf AsciiDoc erstmals auf der Themenliste bei einem Team-Meeting. Und von da an ging es Schlag auf Schlag. Im Januar 2021 war ein erstes Ziel definiert und erste Mockups bereits gezeichnet. Uns war klar, dass Merlin Doc – so hieß das Produkt in den ersten Monaten – eine sehr einfach zu bedienende IDE für AsciiDoc-Texte auf macOS und iPadOS sein soll.

Das bedeutete, dass die Kompatibilität zu bestehenden AsciiDoc-Projekten eine hohe Priorität hatte. Als Vorbilder dienten uns Apps wie Pages oder TextEdit. Wir strebten keine WYSIWYG-Oberfläche an, aber auch keine überkomplizierte Konfiguration. Unser Ziel war es, etwas dazwischen zu schaffen, das angenehm und benutzerfreundlich ist.

Im Jahr 2022 fiel der Startschuss für das neue Projekt, das unter dem zweiten Projektnamen FinalSpec begann.

Die ersten sechs Monate waren geprägt durch Experimente. In sogenannten Prototypen wurden Techniken getestet, verworfen und auch für gut befunden.

Ab Mitte des Jahre 2021 wurde es dann ernst: Mit dem Kick-Off für einen MVP (Minimal Viable Product – einem minimal lebensfähigen Produkt) war die Spiel- und Testphase vorbei.

Das Ziel, ab Ende 2022 mit einem MVP durch das Land zu reisen, wurde knapp gerissen. Ab Juni 2023 durfte ich bei großen Kunden, Verbänden und Kollegen unser neues Werkzeug zeigen und erste Rückmeldungen einholen.

Das Feedback war überwältigend! adoc Studio, der mittlerweile offizielle Name des Produkts, wurde begeistert aufgenommen. Jeder wollte eigentlich sofort damit durchstarten.

Seit Juli 2023 setzen wir adoc Studio zusammen mit einigen anderen mutigen Testern ein. Die Veröffentlichung der ersten Version 1.0 steht noch aus. Wir führen derzeit einen umfangreichen Beta-Test durch, um das Produkt zu optimieren. Ihre Teilnahme hilft uns, adoc Studio zu einer perfekten integrierten Schreibumgebung für technische Autoren zu entwickeln.

Abschließend

Wir sind stolz auf adoc Studio und glauben fest daran, dass es den Prozess der Erstellung und Bearbeitung von Dokumentation revolutionieren kann. Wir hoffen, dass Sie es genauso lieben werden wie wir.

Wir sind begeistert von den aktuellen Möglichkeiten von adoc Studio und freuen uns auf die Zukunft. Es gibt zahlreiche Ideen für weitere Entwicklungen. Unsere Reise hat gerade erst begonnen, und wir laden Sie herzlich ein, uns auf diesem Weg zu begleiten. Wir sehen mit Vorfreude darauf, viele weitere Jahre des gemeinsamen Lernens und Wachsens mit adoc Studio und der AsciiDoc-Community zu erleben. Bitte zögern Sie nicht, uns bei Fragen, Anregungen oder Wünsche zu kontaktieren.

Herzlich willkommen in der Welt von adoc Studio, wir freuen uns auf Sie!

— Frank Blome