Online-Dokumentation für Nutzer mit AsciiDoc und Antora
This is a modal window.
Das Video konnte nicht geladen werden, da entweder ein Server- oder Netzwerkfehler auftrat oder das Format nicht unterstützt wird.
Formale Metadaten
| Titel |
| |
| Serientitel | ||
| Anzahl der Teile | 47 | |
| Autor | ||
| Mitwirkende | ||
| Lizenz | CC-Namensnennung 4.0 International: Sie dürfen das Werk bzw. den Inhalt zu jedem legalen Zweck nutzen, verändern und in unveränderter oder veränderter Form vervielfältigen, verbreiten und öffentlich zugänglich machen, sofern Sie den Namen des Autors/Rechteinhabers in der von ihm festgelegten Weise nennen. | |
| Identifikatoren | 10.5446/59593 (DOI) | |
| Herausgeber | ||
| Erscheinungsjahr | ||
| Sprache |
Inhaltliche Metadaten
| Fachgebiet | ||
| Genre | ||
| Abstract |
| |
| Schlagwörter |
FrOSCon 2021 Cloud-Edition10 / 47
5
8
9
11
13
14
19
20
22
23
25
28
29
33
36
38
42
43
00:00
HauptidealCONSULTANT <Datenbank>Content <Internet>CodeTOUR <Programm>Web SiteLaufwerk <Datentechnik>ASCIIMischung <Mathematik>VideokonferenzSoftwareGit <Software>VersionsverwaltungBrowserChatten <Kommunikation>EntscheidungstheorieFunktion <Mathematik>CodeFunktionalitätMomentenproblemInhalt <Mathematik>Struktur <Mathematik>ComputeranimationXML
03:28
VersionsverwaltungContent <Internet>Komponente <Software>TOUR <Programm>Web SiteProzessautomationHTMLEllipseSkript <Programm>Open SourceDownloadingSystemplattformCMSModulRollbewegungSoftwarekonfigurationsverwaltungRepository <Informatik>KonfigurationsraumCross-site scriptingVersionsverwaltungKomponente <Software>Git <Software>DateiformatSage <Programm>LaufzeitsystemInhalt <Mathematik>HTMLListe <Informatik>MengensystemRepository <Informatik>RollbewegungBimodulProzessautomationBrowserPlug inWahrscheinlichkeitsverteilungProgrammcodeFunktion <Mathematik>ErweiterungStruktur <Mathematik>Kontinuierliche IntegrationWeb-SeiteXMLUML
13:44
IndexKomponente <Software>VersionsverwaltungGUIDO <Datenformat>CLIWeb SiteInternetMassenspeicherDemoszene <Programmierung>CMSSystemplattformContent <Internet>FAQASCIIHTMLPDF <Dateiformat>CodeDatenendgerätWorld Wide WebAutomat <Automatentheorie>GRADEPlug inEditorQUICK <Programm>MenütechnikKontextbezogenes SystemBLENDGoogleData Envelopment AnalysisServerHumanoider RoboterKomponente <Software>MetadatenEbeneModulIndexProzessautomationBimodulGroße VereinheitlichungVersionsverwaltungParametersystemQuellcodeÜbersetzungsspeicherSoftwareWeb-SeiteInternationalisierung <Programmierung>Git <Software>GleichheitszeichenXMLComputeranimation
21:27
CodeServerEditorHTMLSummePoint of saleFAQGUIDO <Datenformat>VersionsverwaltungWINDOWS <Programm>LINUXWorld Wide Webp-BlockIndexRechenzentrumMIDI <Musikelektronik>ProviderMAID <Datenbanksystem>Content <Internet>HTTPSchreib-Lese-KopfFaserbündelMultiplikationVersionsverwaltungInhalt <Mathematik>Schreib-Lese-KopfHTMLWINDOWS <Programm>VerschlingungChatten <Kommunikation>WEBCodierungJavaScriptLINUXMusterspracheComputeranimation
28:47
CachingVersionsverwaltungCodeDiagrammLINUXEditorLoginAdvanced Encryption StandardWeb SiteDisplayUNIXWINDOWS <Programm>World Wide WebHTTPStellenringHumanoider RoboterUpdateGebäude <Mathematik>Highlight <Programm>Schreib-Lese-KopfMono-FrameworkNDSPlug inKomponente <Software>PDF <Dateiformat>ProviderKonfigurationsraumASCIIInhalt <Mathematik>VersionsverwaltungGit <Software>ModulBrowserSoftwareArbeit <Physik>E-MailKontextbezogenes SystemChatten <Kommunikation>Web-SeiteQuellcodeFunktionalitätProgramm/QuellcodeComputeranimation
36:08
HTTPWorld Wide WebCONSULTANT <Datenbank>CodeInhalt <Mathematik>Chatten <Kommunikation>World Wide WebProzessautomationDateiBimodulMagnetbandlaufwerkVideokonferenzComputeranimation
40:45
EditorSchreib-Lese-KopfCodeNabel <Mathematik>DOSMADOQUICK <Programm>StellenringPlug inSchätzungGUIDO <Datenformat>DiagrammHTMLPDF <Dateiformat>Proxy ServerURLGoogleBlaseUpdateFramework <Informatik>FokalpunktIndexKomponente <Software>Internationalisierung <Programmierung>ÜbersetzungsspeicherModulListe <Informatik>MetadatenErweiterungGruppierungGit <Software>HomepageComputeranimation
45:08
Komponente <Software>QUICK <Programm>CodeBewegungGooglePDF <Dateiformat>ARCHIVE <Programm>VerschlingungHypermediaCross-site scriptingHTMLSoftwareGmailHomepageURLServerWINDOWS <Programm>VersionsverwaltungData Envelopment AnalysisPACEPDF <Dateiformat>MomentenproblemPlug inErweiterungURLGit <Software>CodeChatten <Kommunikation>MagnetbandlaufwerkOpen SourceWeb logFunktionalitätPRIMA <Programm>Topologische EinbettungComputeranimation
51:18
JSONXMLUML
Transkript: Deutsch(automatisch erzeugt)
00:06
Herzlich willkommen hier bei FrostCon im Development Track mit unserem nächsten Vortragenden Alexander Schwarz zum Thema Online-Dokumentation für Nutzer mit ASCII-Doc und Anthora. Wie man Dokumentation in ASCII in Git mit dem Code zusammenverwalten kann.
00:25
Viel Spaß dabei. Wenn ihr Fragen habt, bitte in die Videokonferenz kommen und in die in das Chat schreiben. Dann, wenn ihr zwischendurch am Ende gestärkt, ich sammle die dann im Zweifelsfall. Jetzt viel Spaß. Danke für die Einleitung und auch von mir ein herzliches Willkommen zu diesem Vortrag
00:45
von der Dokumentation für Nutzer mit ASCII-Doc und Anthora. Mein Name ist Alexander Schwarz. Ich bin IT-Consultant. Das heißt irgendwie Mischung aus Software-Entwickler, IT-Architekt. Und als Software-Entwickler bin ich immer so im Java-Umfeld, Community-Umfeld unterwegs,
01:06
ein bisschen JavaScript-Contents. Und als IT-Architekt unterstütze ich Leute dabei, hoffentlich gute Entscheidungen zu treffen in ihren Projekten und nochmal Experimente zu wagen, Sachen ausprobieren, um neue Sachen zu entdecken.
01:21
Heute geht es aber um Online-Dokumentation. Und wie immer erst mal so ein kleiner Einstieg in Dokumentation. Warum brauchen wir überhaupt so etwas? Die Motivation für Dokumentation. Wir möchten die Nutzer bei ihrer Arbeit unterstützen. Denn Software ist hoffentlich selbst erklärend, zumindest in beiden Teilen, aber so eine Dokumentation,
01:43
die vielleicht die häufigsten Fragen beantwortet, so eine Übersicht über die Funktionen liefert, die braucht es dann eben doch nochmal, um bei der täglichen Arbeit zu unterstützen. Und idealerweise ist so eine Dokumentation halt immer aktuell. Sie passt zu der Software-Version, die der Nutzer gerade im Einsatz hat.
02:02
Und wenn es vielleicht mehrere Versionen draußen gibt, kann ich auch in der Dokumentation zwischen diesen Versionen umschalten und mir anschauen, was genau in dieser Version eben gerade Funktionalität da war und wie es dort funktioniert hat. Die Inhalte sind idealerweise auch konsistent. Das heißt, wenn ähnliche Sachen an verschiedenen Stellen beschrieben werden,
02:24
sind sie dann auch ähnlich beschrieben und weichen nicht voneinander ab. Ich kann vielleicht auseinander verweisen. Das hilft mir auch bei meiner Konsistenz. Oder ich kann Textblöcke wiederverwenden an manchen Stellen. Und naja, Dokumentation, wenn ich sie schreibe, dann schreibe ich sie idealerweise in dem Moment, in dem ich auch neue Funktionalitäten schreibe.
02:43
Und spiele sie dann im gleichen Moment in Produktion ein, wie ich meine Software in Produktion einspiele. Sie gehen also gleichzeitig live. Und an diesen drei Stellen möchte eben Anthora unterstützen und da auch ein gutes Toolset und gute Strukturen zur Verfügung stellen, die dafür gut funktionieren.
03:03
So eine Dokumentation mit Anthora und Asketox sieht dann ungefähr aus wie dieses Beispiel. Das heißt, irgendwo läuft sie im Browser. Sie ist automatisiert und aktuell. Sie ist durchsuchbar. Das heißt, ich habe hier oben sowas wie einen entsprechenden Suchbereich,
03:22
wo ich meine Begriffe eingeben kann. Ich habe eine Navigation und Querverweise. Das heißt, wenn ich hier, ich habe ein bisschen ausgeblendet, hier eine Navigation auf der linken Seite. Oder ich habe dann hier drin auch noch Querverweise in meinem Text, wo ich dann auf andere Seiten springen kann.
03:40
Und meine ganze Dokumentation, die ist nicht nur ein großer Buch, sondern die ist dann auch strukturiert. Ich sehe es zum einen nach Version strukturiert. Hier oben kann ich eine Version auswählen, die ich dann eben gerne zeigen, die der Nutzer eben bei sich installiert hat, die er gerade benutzt. Und hier unten kann ich dann zwischen verschiedenen Komponenten hin und her springen und sagen, das ist vielleicht meine Dokumentation für Endnutzer.
04:01
Das ist meine Dokumentation für diejenigen, die es installieren. Alle diese Möglichkeiten bietet eben Anthora und die Toolbox, die es mitbringt. Und wie gesagt, dafür brauche ich eine Strukturierung der Dokumentation in Komponenten und Module. Komponenten haben wir schon ein bisschen gesehen hier. Module gibt es gleich noch ein bisschen in Detail.
04:23
Anthora geht dann her und sammelt alle meine Inhalte, die ich eben im ASCII-Doc-Format beschrieben habe, aus verschiedenen Git-Repositories, wenn ich verschiedene habe, ein- und aus verschiedenen Branches, und baut daraus eine Dokumentationsseite, die ich in einem Rutsch deployen kann, die auch dann alle Querverweise enthält.
04:41
Und die ganzen ASCII-Doc-Inhalte, die ich eingesammelt habe, verwandelt es dann erstmal in HTML, damit es dann eben im Browser angezeigt werden kann. Und dieses HTML wird dann mit einem UI-Theme gemischt, also den passenden Styles, die ich habe, der passenden Kopf- und Fußzeile mit der Navigation, die ich dafür vielleicht festgelegt habe, um noch andere Inhalte einzubringen.
05:03
Und daraus kommt eben eine statische Webseite raus, die ich dann auf einem ganz normalen Web-Server deployen kann. Und die Konvertierung ist relativ schnell. Das heißt, auch große Dokumentationsseiten kann ich damit konvertieren in kurzer Zeit. Und ich habe auch sehr wenige Abhängigkeiten zu anderen Projekten,
05:23
zumindest im Vergleich zum Node.js-Universum. Es sind relativ wenige des Dependencies. Es ist modular und erweiterbar. Aktuell gibt es gerade die Version 2 von Anthora, die hat schon einige Module. Version 3 wird noch viel erweiterbarer werden, dass man da auch noch eigene Sachen besser schreiben kann.
05:44
Gut, da ich jetzt ASCII-Doc über ASCII-Doc gesprochen habe und ASCII-Doc da auch immer wieder auftaucht, vielleicht eine kurze Abgrenzung zwischen den beiden. ASCII-Doc ist die Sprache und ASCII-Doc da ist das Werkzeug oder die Toolchain, mit der man dann mit ASCII-Doc arbeiten kann.
06:02
ASCII-Doc ist erstmal ganz normaler Text. Schreiben ohne Ablenkung in der IDE. Ich kann es in Git einchecken. Hat einen großen Funktionsumfang für technische Dokumentation. Ist ein bisschen angelehnt an DocBook, aber halt eben nicht so kompliziert zu schreiben. Und ich kann damit Callouts machen, ich kann damit Listen machen,
06:22
ich kann damit Tolletabellen machen. Das ist alles Teil des Sprachumfangs, den ich hier habe. Wird seit 15 Jahren kontinuierlich weiterentwickelt und seit 2020 startete die Standardisierung bei der Actives Foundation von ASCII-Doc. ASCII-Doc ist dann das Werkzeug, mit dem ich aus ASCII-Doc Textdateien
06:43
oder ein Werkzeug, mit dem ich aus ASCII-Doc Textdateien HTML erstellen kann. Und noch ganz viele andere Formate. PDF, EPUB, ganz viele verschiedene. Es ist Open Source, läuft unter Java, Ruby und JavaScript, Laufzeitumgebung und Anthora setzt eben auf ASCII-Doc da auf,
07:02
um diese Konvertierung machen zu können. Schreiben in der IDE. Ich habe hier auch so einen Screenshot im Hintergrund mitgebracht. Von dem IntelliJ ASCII-Doc Plugin. Da bin ich der aktuelle Maintainer von diesem Plugin. Und dort kann ich eben fokussiert als Entwickler
07:23
mein Programmcode schreiben und gleichzeitig eben auch ohne in ein anderes Tool zu wechseln, wenn ich möchte, auch im gleichen Grid-Hepository die Dokumentation vorschreiben, die dort existiert. Zusammenarbeit erfolgt dann eben über eine Versionsverwaltung. In diesem Fall ist die Versionsverwaltung auch vorgegeben.
07:41
Es ist immer Git, wenn man Anthora verwendet. ASCII-Doc würde auch mit ganz verschiedenen anderen Versionsverwaltungen funktionieren, aber Anthora baut eben auch Git auf. Und das IntelliJ ASCII-Doc Plugin unterstützt eben sowohl Anthora mit all seinen Komponenten, Strukturen und Autovervollständigung als auch ASCII-Doc.
08:05
Schauen wir uns Anthora genauer an. Was bringt Anthora mit? Das bringt zum einen Struktur mit. Und zum einen diese Überlegung von Komponenten, die erst mal unabhängig voneinander existieren, die aufeinander verweisen können, aber selber eigene Namen haben, eigene Versionsnummern haben können.
08:23
Ich könnte die Versionsnummern von einzelnen Komponenten auch unterschiedlich hochzählen, wenn ich das möchte. Und davon kann ich erst mal beliebig viele haben, um dann mit jeder Komponente genau einen Adressaten so anzusprechen, wie ich ihn gerne ansprechen möchte. Einen Endnutzer, einen Administrator, Administratorin, ganz verschiedene.
08:46
Und jede Komponente kann dann mehrere Module haben. Die kann ich mir auch wieder frei wählen, können beliebig viele sein. Und jedes von diesen Modulen hat dann aber eine feste Struktur. In Anthora heißen die Families von diesen Gruppen,
09:02
von diesen Unterverzeichnungen, die dann immer wieder da sind. Das sind dann ein Verzeichnis für Seiten, dann ein Verzeichnis für Bilder, für Beispiele, für Anhänge. Oder auch Partials, das sind also kleine Text-Snippets, die ich an mehreren Stellen einbinden möchte. Und ja, diese Struktur gibt Anthora vor.
09:24
Die ist auch in allen Anthora-Projekten erst mal grundsätzlich gleich und hilft, dass Leute sich auch zu orientieren. Sag mal, Ask a Doc als eine Inhaltsbeschreibungssprache gibt sowas nicht vor. Da haben sich vielleicht auch Best Practices entwickelt, wie man sowas strukturieren kann in einem Projekt.
09:40
Aber Anthora gibt hier noch viel, viel mehr Struktur vor, das eben basierend auf Best Practices, basierend auf den Erfahrungen, die Dan Allen nicht zuletzt in die Community gesammelt haben, wie man so etwas strukturieren kann. Und diese ganzen Inhalte kann ich dann entweder in einen Branch und ein Git Repository reinpacken,
10:01
oder ich kann es eben in verschiedenen Branches haben oder auch über mehrere Git Repositories verteilen. Das ist halt eine fortgeschrittene Funktion. Am Anfang nutzt man das vielleicht noch nicht. Wenn man dann wächst als Projekt und mehr Dokumentationen hat, kann man eben darauf zurückgreifen und davon auch profitieren von diesen erweiterten Funktionen.
10:22
Wenn ein Anthora dann startet und dann wird einfach nur Anthora als Kommandozeilenwerkzeug aufgerufen, zusammen mit Node.
10:41
Und was Anthora dann macht, ist, es braucht ein Playbook. Ein Playbook beschreibt dann, okay, welche Git Repositories muss ich jetzt alle ziehen? In welchen Branchen findet sich Dokumentation? Und genau, also der erste Schritt, das liest Anthora ein. Und dann holte sich die verschiedenen Git Repositories,
11:01
wie sie im Playbook drin standen. Und genau, dann holte sich die ganzen ASCII-Dok-Dateien raus, wandert sie in HTML um. Das UI-Theme wird dann eben auch gezogen von Anthora und damit gemischt. Dann wird vielleicht noch ein Suchendex erstellt und ich habe dann eine statische Ausgabe-Seite.
11:21
Das ist der Ablauf von Anthora. Um so einen Dokumentations-Setup zum Laufen und zum Fliegen umzubringen, habe ich dann verschiedene Rollen in einem Projekt, die sich ergänzen. Eine Rolle ist sicherlich der Autor, die Autorin.
11:43
Und diese Person muss halt, sagen wir mal, strukturieren und schreiben können. Das ist dann so eine Erwartung, die man so einem Autor einfach mitbringt. Und in dem Anthora-Projekt muss diese Person dann aber auch mit Git umgehen können, um eben mit anderen Autoren entsprechend zusammenarbeiten zu können.
12:02
Und ASCII-Dok können, um diese Inhalte zu erstellen, die es eben in diesem Projekt braucht. Es wird immer noch jemanden geben, der dann Doktuops macht, Automatisierung und Infrastruktur. Das heißt, wir brauchen jemanden, der einen Git einrichtet, der eine Jaml-Konfiguration schreibt,
12:21
das Playbook, wo dann die ganzen Sachen herkommen. Wer eine Package-JSON pflegt. Wir sind hier im Node-Universum unterwegs. Das heißt, alle unsere Versionen von Erweiterungen für Anthora oder für Anthora selbst stehen in so einer Package-JSON-Datei drin. Wir wollen so etwas wie eine Continuous Integration haben für unsere Dokumentation. Das sind alles die Sachen,
12:41
die man in einem Projekt braucht, jemanden, der es entsprechend einrichtet. Und die dritte Person ist dann der Web-Entwicklerin, die sich dann um die Webseitenerstellung kümmert, zumindest um das Theme, was vielleicht anpasst, mit entsprechenden Logos ergänzt, aber dann halt so ein bisschen Wissen
13:01
rund um HTML und CSS mitbringt. Jeder hat seinen Aufgabenbereich. Der Autor kann sich auf die Inhalte konzentrieren, der Web-Developer kümmert sich um das Theme und Doktuops kümmert sich um die Automatisierung. Diese drei Sachen müssen eben abgedeckt sein, damit man dann auch eine gute Dokumentation hat und mit Anthora auch ein gutes Ergebnis abliefern kann.
13:25
Die ersten Schritte, die man dann hat in so einem Projekt, da gibt es auch einen Quickstart, den habe ich unten eingeblendet in den Folien. Der Autor, der Autor wird dann schauen, na ja, ich erstelle erst mal eine Ordnerstruktur. Ich füge mal eine allererste Komponente,
13:41
die ich haben möchte. Die habe ich auf der rechten Seite mal dargestellt. Auf der obersten Ebene ist dann die Komponente. Darunter gibt es dann immer eine Anthora.yml-Datei, die ein paar Metadaten aufnimmt. Und dann habe ich verschiedene Module drunter. Ich habe jetzt hier genau ein Modul, das heißt Root in Großbuchstaben. Das ist dann der Default dort drin.
14:00
Ich kann aber auch das Root weglassen und andere Komponenten nur mit Namen hier vergeben. Da kann man sich überlegen, wie das in das eigene Projekt am besten reinpasst. Und unterhalb jedes Modules sieht man schon die Struktur, von der ich sprach. Anthora.yml vergibt Name und Version. Index.adoc ist sozusagen die Startseite
14:21
in meinem Pages-Ordner. Die Startseite von diesem ersten Modul in dieser ersten Komponente. Die Navigation, in diesem Fall, ist nicht automatisiert erstellt, sondern gepflegt. Das heißt, ich kann mir sehr überlegen,
14:41
wie meine Navigationsstruktur, welche Seiten wie eingerückt sein soll, dargestellt werden soll. Und dann fängt eben an, die DocuOps-Personen zu sagen, hier ist das Instalima Anthora. Ich erstelle so ein Playbook für den Autor, für die Autorin, für die lokale Vorschau.
15:02
Und das man eben lokal testen kann. Und dann gibt es vielleicht noch ein zweites Playbook, um es dann wirklich im Internetbereich zu stellen, zu publizieren, wo dann vielleicht noch andere Parameter drin sind, wo vielleicht nicht ein Subset publiziert wird. Das sind so verschiedene Möglichkeiten, die ich hier habe. Und der Web-Entwickler, der dann halt
15:20
sich um das UI-Theme kümmert. Genau, schauen wir uns dann gleich mal ein Beispiel an. Ich glaube auch, jetzt ist es Zeit für ein Live-Demo. Der ganzen Theorie, die ich eben hier erzählt habe, auch ein paar Beispiele dazu zu geben.
15:44
Marius fragt gerade Playbooks in diesem Fall hier an Anthora-Konzept und kein Ansible-Konzept. Das ist richtig, genau. Das heißt, das ist auch eine Jammel-Datei, die wir gleich sehen werden, hat aber nichts mit Ansible zu tun. Gute Frage, danke schön dafür.
16:02
Und als Beispiel habe ich hier heute mitgebracht die Dokumentation des IntelliJ ASCII Dog Plugins. Ganz im Sinne von Eat Your Own Dog Food. Die Dokumentationsseite des IntelliJ ASCII Dog Plugins ist mit Anthora geschrieben. Auch hier sieht man wieder eine Suchzeile,
16:20
eine Navigation hier oben. Man sieht hier eine Navigation auf der linken Seite, die dann diese eine Komponente, in der ich mich gerade befinde, den User's Guide entsprechend punkturiert. Ich kann jetzt zwischen dem User's Guide und dem Contributor Guide hin und her schalten. Das sind beide Komponenten, die ich hier habe. Und jetzt schauen wir uns
16:42
mal an, wie so etwas im Quellcode aussieht und auch wie die entsprechende Automatisierung davon aussieht. Gehen wir mal in die IntelliJ. Und das ist hier das Git Repository, in dem
17:01
die Software selber entwickelt wird. Da gibt es erstmal hier einen Ordner Dog, in dem ich die Komponenten abgelegt habe. Wie dieser Ordner heißt, aber Dog heißt oder anders ist erstmal egal. Wichtig ist dann erst die Struktur innerhalb einer Komponente.
17:21
Wie ich gesagt habe, es gibt hier zwei Komponenten, ein Contributor's Guide und ein User's Guide. Und schauen wir mal in den User's Guide rein, was da so drin steht. Die Komponente wird hier beschrieben, sie hat einen Namen. Das ist eigentlich der echte Name hier sozusagen, der wirklich technische Name, mit dem ich dann auch
17:41
Querverweise machen kann. Aber hier oben gibt es dann noch den Titel, der dann wirklich als Überschrift angezeigt wird, wenn ich die irgendwo verwende. Ich habe jetzt hier erstmal auf eine Version verzichtet an der Stelle. Man kann hier aber eine Version reinschreiben, die dann auch später publiziert wird. Und die Module, die ich hier habe,
18:00
ich habe jetzt hier dieses eine Route-Modul, das hat jetzt keine besonderen Rechte in dem Sinne, ist aber halt einfach das Standard. Der Standardname für das erste Modul. Und ich habe hier meine Navigation hier drin, die ich dann hier strukturiert habe. Und wenn wir jetzt hier mal auf die Page-Struktur schauen,
18:21
dann habe ich hier auch meine Index-Adoc. Das ist dann hier meine normale ASCII-Doc-Datei, mit meiner Überschrift. Vielleicht noch ein paar zusätzliche Antora-Attribute, die man vielleicht so noch nicht gesehen hat. Der Kurztitel für die Navigation habe ich hier drin. Ich habe hier eine Beschreibung
18:41
noch mit drin. Ich habe ein bisschen Kommentare hier drin, um zu beschreiben, nach dem Motto, wer denn hier der Leser ist für denjenigen, der das nächste Mal Dokumentation dazuschreibt. Ich habe dann hier meine Struktur, mit Überschriften, die hier mit zwei Gleichheitszeichen eingeleitet sind, als nächste Ebene. Und ich habe hier Aufzählungspunkte
19:01
drin. Man sieht hier auch, diese Struktur wird dann noch abgebildet. Dass ich hier auch navigieren kann innerhalb meines einen Dokuments. Zwischenruf noch die Frage, wie sieht es mit Lokalisierung aus? Kann ich Antora-Dokumentation in verschiedenen Sprachen erstellen? Und dann lieber
19:21
pro Version einen eigenen Ort erstellen? Na ja, man würde, wie könnte man so etwas machen? Man könnte, es gibt so einen Umweg über PO, Q4A, für Text, Q4A,
19:40
dass man wirklich Translation Memory hat und Sachen dann übersetzt. Und dann würde man vielleicht einen eigenen Branch haben, mit einer eigenen Versionsnummer, um zu sagen, das ist meine Version 1.0 meiner Software, in der Dokumentationsversion DE für Deutsch oder EN für Englisch. So könnte man sowas machen, aber OnTheFly wird das aktuell
20:01
von Antora nicht unterstützt. Vielleicht schreibt jemand noch mal ein Modul dafür, dass es auf OnTheFly übersetzt wird, aber aktuell braucht man dafür eben auch mal einen eigenen Branch für jede Sprache, die man dann umsetzen möchte. Genau, hier sieht man so einen Querverweis, xref als Querverweis, und
20:21
hat dann hier die Möglichkeit zum Kriegsstart rüberzuspringen. In meiner Idee wird sowas eben entsprechend ergrenzt hier. Was ich jetzt sage, ich habe einzelne Dateien, ich habe hier Unterverzeichnissen, die ich dann eben rein springen kann. Und mit string-v kann ich hier rein springen und sagen, ja, jetzt habe ich dann
20:40
hier sowas wie Callouts drin und wenn ich dann zum Beispiel mal einen Quickstart, das muss ja auf dieser Seite auch mit drauf sein, kann ich dann hier eben auch reinspringen und sehe hier auch das Pre-Rendering. Auch hier habe ich, was ich hier bei meiner Idee so eingestellt habe,
21:00
ist, dass ich wirklich den gleichen Style habe in der Vorschau hier rechts, wie ich dann später auf der Webseite auch habe. Dann sieht man hier zum Beispiel, das ist hier so eine Admonition Warning, die eben entsprechend eingeblendet wird. Ich habe hier sowas, wie der Aufzählungspunkt. Ich habe hier verweise den Bildern, die hier im Vorschau auch aufgelöst werden.
21:22
Das heißt, das Ziel war es hier wirklich einen guten Support zu haben für das Schreiben von AsciiDoc-Dokumentation und Antora-Dokumentation in IntelliJ. Hier gibt es so einen Schritt, der öfter mal wiederholt wird.
21:41
Nach dem Motto, wenn ihr fertig ist, aber installieren, geht doch bitte dann nochmal zu den Recommended Settings. Das ist jetzt ein Partial, den ich hier einblende. Und wenn ich zu dem Partials gehe, dann ist es halt ein Text- snippet, der an verschiedenen Stellen verwendet wird. Der befindet sich jetzt im Ordner Partials. Und wenn ich jetzt mal meine IDE frage, wie oft wird das denn irgendwo
22:01
verwendet? Das habe ich jetzt genau ersucht jetzt. Mal gucken, ob dann die Demogürter mit mir sind. Und dann wird er mir hoffentlich gleich zeigen, wo er das überall gefunden hat. Das wird eben an drei Stellen verwendet. Bei der Installation wird es an zwei Stellen verwendet. Und in meinem Quickstart wird es verwendet. Und diese Partials helfen mir
22:21
dann eben auch eine konsistente Dokumentation zu liefern. So. Dann schauen wir mal wieder.
22:41
Zwischendurch kam die Frage aus dem Chat ein bisschen auf Topic, ob sowas für Markter aufgibt. Da gibt es vielleicht sowas wie Dokusaurus oder andere Sachen. Ich bin selber ein ASCII-Doc-Fan, weil ich in ASCII-Doc sozusagen selten bis eigentlich gar nie in die Verlegenheit komme, irgendwie HTML in meinen Content-Sachen zu schreiben.
23:03
ASCII-Doc ist da so feature-complete, dass ich wirklich Inhalte schreibe und nicht irgendwie nach HTML ausbricht. Deshalb bin ich einfach ein ASCII-Doc-Fan. Und vielleicht fehlt mir dann ein bisschen die Erfahrung im Markdown-Universum. Aber da gibt es bestimmt auch was. Im Code-Doc sieht man da vielleicht
23:21
ab und zu. Gut. Aber da muss man halt Markdown schreiben. Gut. Mal gucken, dass ich meine Fahne wieder finde. Wo war ich denn jetzt hier? Genau, wir waren jetzt hier in der Installation. Genau, dann vielleicht sowas wie, wir sind hier alle gerne Leute, die so
23:41
Keyboard-Makros mögen. Eine gute Dokumentation hat vielleicht auch sowas dabei, wenn es denn passt, so eine Dokumentation der verschiedenen Keyboard-Shortcuts mitzuliefern. Und hier gibt es erstmal ein bisschen Dokumentation oder Kommentar für diejenigen, die Dokumentation und schreiben hier. Das ist das Motto, wo man hier ein bisschen nachschauen kann. Und dann gibt es hier
24:01
halt für Windows und für Linux die entsprechende Dokumentation. Und ich habe es hier, ich brauche hier immer noch keine HTML zu schreiben, sowohl für so eine schöne Tabelle, als auch für die entsprechenden Keyboard-Shortcuts. Und wenn ich das eben dann in meiner Dokumentation suche, nach
24:20
Keyboard-Shortcuts E-Mails, so habe ich es gemeint. Vielleicht sollte ich noch etwas anderes machen. Dann wird das eben auch genauso schön gerendert auf meiner Dokumentations- Webseite, wie ich es eben bei mir in der IDE gesehen habe. Ist ein bisschen stark rangezoomt, aber so sei es.
24:42
Genau, das heißt, ich kann hier, sag mal, als Coder bin ich hier denke ich sehr gut zu Hause, dass ich mit Klassaturkürzeln auch meine Dokumentation schreiben kann. Gut, das war so der erste Schritt hier. Genau, schauen wir nochmal, das muss ich mal gucken, wo ich das,
25:01
hier ist mein Dokumentations-Repository. Ich habe mich dafür entschieden, und das ist, denke ich, bei Anthora auch ein oft gesehenes Pattern für den UI teilt und da, wo das Playbook drin ist, noch ein zweites Kit-Repository aufzumachen. was ich hier gemacht habe, was Anthora
25:21
gut kann, ist so eine strukturierte Dokumentation. Und was es vielleicht nicht so gut kann, wo man vielleicht ein bisschen hin und her schieben muss, ist sowas wie eine gute Startseite machen. Was ich hier gemacht habe, wenn man auch auf die Startseite geht, von IntelliJ ASCII-Doc,
25:40
das hier ist eine Jekyll-Seite, auch ein Statische Webgenerator. Ich sag mal, jeder andere Statische Webgenerator hätte es wahrscheinlich genauso getan. Aber Jekyll hat auch eine ganz gute ASCII-Doc-Unterstützung, wie auch viele andere, aber jedem das seine. Und dann kann ich eben hier entsprechend einsteigen wie die Startseite. Das heißt, man findet hier einmal so ein bisschen was
26:02
zu Jekyll. Das befindet sich dann in welchem Ordner noch gleich. Genau, so im Root, hauptsächlich hier Jekyll, Jamfile. Und dann gibt's einen Unterordner für Anthora, wo jetzt hier noch ein bisschen mehr drin steht, wie
26:20
zum Beispiel mein UIs-Team funktionieren soll. Ich hab mich dafür entschieden, das UI-Bundle 17 nehmen, so wie es von Anthora erst mal kommt. Das ist das Standard-Team, muss man kaum was verändern. Habt man erst mal eine Seite. Was man dann auf alle Fälle verändern möchte, ist wahrscheinlich die Kopf- und die Fußzeile. Und das ist eine Sache, die kennt man vielleicht schon
26:41
von anderen statischen Webgeneratoren, wo man dann sagt, hier den Futter möchte ich jetzt überschreiben, den Futter-Inhalt möchte ich überschreiben, hier steht halt irgendwas drin, dass ich halt sage, wer jetzt damit mitgearbeitet hat, wer die Contributors sind, den Link zu GitHub und im Header möchte ich was anderes, im Header-Content möchte ich was anderes reinschreiben. Das sind so die
27:02
zwei Parteien, die man auf alle Fälle verändern möchte, wo man vielleicht eine andere Integration im Header haben möchte. ja, nach und nach überschreibt man vielleicht mehr Sachen, sodass es sich bei mir hier so ein bisschen gesammelt hat. Ich hab hier so eine Lightbox reingebaut und halt wenn man auf Images draufklickt, dass da was passiert.
27:20
Aber das ist halt eine Sache, die der Web Designer macht. Ich kann so ein bisschen HTML, ein bisschen JavaScript. Und so hat sich hier das nach und nach ein paar Sachen angesammelt, auch diese JavaScript-basierte Suche, die ich hier drin habe. So kann man nach und nach Sachen hinzu. Und am Ende gibt es hier zwei Playbooks drin, einmal das für den
27:42
Autor, für die Autorin. Und dann sagt hier, das ist mein ich hab die Startseite für die Dokumentation, da soll erstmal beim User Guide einsteigen. Und dann lokal habe ich es alles schon ausgecheckt. Dann sage ich, relativ zu diesem Verzeichnis gibt es als ausgecheckte
28:01
die ausgecheckte Dokumentation, die Innenbearbeitung ist, mit ihren beiden Start Paths. Und dann will ich auch nur den Head, also das, was ich dort habe, weil ich gerade eine Bearbeitung habe, entsprechend anzeigen und generieren lassen als startische Seite. Und wer soll sich eben dieses UI- System hier holen? Und wenn ich dann später das ganze MCI-CD
28:22
publiziere, sieht es halt ein kleines bisschen anders aus. Ich sage hier, ich möchte halt wirklich das Git-Repository von irgendwo remote herklonen. Ich habe verschiedene Start-Pfade in meinem Git-Repository. Ich habe meine Branches, ich habe nur den Main-Branch hier drin. Man hätte vielleicht für jede Version, wenn jede Version in einem eigenen Branch lebt, dort verschiedene
28:44
Branches hinterlegt. Genau. Damit ist man hier unterwegs. Genau, ein paar Einstellungen. Das ist auch alles open source. Könnt ihr euch anschauen und Fragen stellen. Wie gesagt, am Ende wird hier ein Autoprodukt generiert in irgendeiner
29:03
Unterstrichzeit-Docs. Am Ende wird das gleiche Bezeichnis in das Jekyll vorher schon seine Sachen hineingeschrieben hat. Dann habe ich meine fertige stratische Webseite und kann sie entsprechend publizieren.
29:24
geht es weiter. Vielleicht nochmal das Thema Regimentation. Marius fragt, ist von Anthora generierten Wandel alles drin, inklusive der Texte oder nur das Anthora-Theme?
29:43
In dem UI-Theme ist wieder nur das Theme drin, aber in diesem Site, was ich da gerade gezeigt habe, da ist dann auch die Inhalte drin. Das heißt, ich klappe das hier aus. Man sieht hier den Anthora-Docs. Da hat Anthora seine Sachen reingepackt. Dann habe ich hier den Contributors Guide.
30:01
Also wir waren im User Guide. Dann habe ich hier meinen Index-HTML und das ist jetzt wirklich UI-Theme am Anfang sozusagen. Und wenn man hier ein bisschen runterscrollt, kommen dann wirklich irgendwann die Inhalte. Das ist noch Navigation. dann kommt der echte Text hier quasi in der Mitte. Und dann am Ende kommt dann irgendwann der Footer. Das sind wirklich statisch
30:21
generierte HTML-Seiten. Wie gesagt, man hat hier eine Ordnerstruktur drin. Alle FAQ-Einträge sind in einem eigenen Ordner, so wie ich sie auch in meinen Seiten habe. Die Advanced Themen sind in einem eigenen Ordner hier drin. Ich switche mal zurück,
30:41
dass man sich nochmal anschauen kann, wie das hier aussah. Ich mache mir hier ein paar Sachen zu. Auch hier, das entspricht quasi genau meiner Struktur, wie ich sie eben auch in meinem Modul habe. Das war heute die Frage, die wir gerade im Chat hatten. Wie gesagt, stellt keine Fragen im Chat. Ich versuche darauf eben
31:00
entsprechend einzugehen. Dann kann ich hier auch gucken, Dokumentation. Das ist ja alles im Git drin. Und dann können wir ja mal gucken, wann und wie. Dann kann man auch mal gucken, was wurde denn hier
31:20
entsprechend geändert. Dann sehe ich halt hier, hier gab es einen Commit, der sich um die neueste Version von Android Studio gekümmert hat. Dass es da ein paar Änderungen gab und ich kann mir hier dann eben meine ASCII-Doc-Änderungen angucken, dass ich hier eben was für Version 20.20.3 dazu geschrieben habe. Dann kann man auch sehen, wer
31:40
das jeweils gemacht hat. Hier hat sich jemand mal zum Beispiel um die Source Highlighting gekümmert, das hier eben falsch war. Hat jemand contributed? Hier war was nicht sichtbar, hat er was korrigiert. Vielen Dank nochmal an ihn. Und wie gesagt, auch hier sind die Tickets eben miteinander verlinkt. Und wenn ich jetzt mal gucken würde,
32:02
mal gucken, ob ich hier ein gutes Beispiel finde. Jetzt kann ich natürlich auch nach der Ticketnummer hier suchen, 734, was zu einem Ticket dokumentiert wurde. Ja, idealerweise würde man dann auch sehen, das war die Code-Änderung, das waren die
32:21
entsprechenden Dokumentationsänderungen, alles zusammengefasst und gelinkt an das GitHub-Issue, weil sie alle das referenzieren oder in das Commit-Set. Jetzt muss ich mal gucken, ob ich ein gutes Beispiel finde. Anscheinend habe ich jetzt kein gutes Beispiel parat, bin ich schlecht vorbereitet.
32:41
Gut. Ja, von daher, wir profitieren hier von der Versionsverwaltung, die und geht, was uns das entsprechend mitbringt. Dann sind wir glaube ich am Ende des Demo-Teils. Wie gesagt, gerne Fragen stellen dazu.
33:11
Wie gesagt, Dokumentation. Das sind schon die Fazitfolien. Unterstützt die Dokumentation bei ihrer Arbeit.
33:21
Software ist hoffentlich weitestgehend selbst erklärend, aber so die erweiterten Konzepte liest man dann doch vielleicht gerne mal nach, um auch mal zu schauen, was gibt es in einer erweiterten Funktionalität. Und wie gesagt, die Inhalte sollten aktuell sein. Was wir heute gesehen haben, die Chance ist eben, die Inhalte aktuell
33:40
zu halten, indem man eben als Team zusammenarbeitet über eine Versionskontrolle in Git. Machen wir eine Änderung im Main-Branch oder in einem Feature-Branch in einer Versionskontrolle in Git. Und im gleichen Branch arbeiten dann auch die Autoren mit, die die entsprechenden Inhalte
34:00
pflegen dort oder die Entwickler machen das teilweise gleich mit, je nachdem, wie man sowas eben in einem Projekt haupteilt. Die Inhalte sind konsistent. Durch Komponenten-Versionen und die Deduplizierung von Inhalten. Das heißt, eben dadurch, dass ich meine Version entsprechend auswählen kann in meiner Dokumentation,
34:22
das kann ich gleich nochmal in Tora zeigen, finde ich dann auch genau diese Dokumentation, die zu der Software-Version passt, mit der ich gerade lokal arbeite oder in meiner Umgebung arbeite. Und wenn ich eine Deduplizierung mache über Parsches, wie wir sie gesehen haben, so einfache Textblöcke, die immer wieder die gleichen Links enthalten sollen, immer wieder die gleichen kurzen
34:42
Zusammenfassungen enthalten, was ich die eben auslagere und modulübergreifend, aber auch komponentübergreifend verwenden. Und ja, CICD, da können wir gleich nochmal reinschauen, diese ganze
35:01
Publizierung von neuen Dokumentationen, das soll dann auch wirklich gleichzeitig live geben in der Software, das heißt, ich drücke auf den Knopf, ich committe was und dann bringt meine Maschinerie an und bringt das dann wirklich live live in den Browser des Kunden sozusagen.
35:21
Gut, von daher sage ich erstmal hier vielen Dank. Das sind hier die Links. Zu ASCII-Doktor, zu Anthora, zu dem Plugin, was ich euch heute gezeigt habe, zu ein paar Videos, die ich schon in einem anderen Kontext schon mal aufgezeichnet
35:40
habe, auch auf anderen Konferenzen. Schaut gerne mal vorbei, wenn ihr Fragen habt, stellt sie mir auf Twitter, stellt sie mir per E-Mail. Wenn es um das IntelliJ ASCII-Dok plugin geht, Fragen auch gerne als GitHub-Issue, da gibt es eine eigene Rubrik für Fragen, die dann auch gerne beantwortet werden, entweder
36:00
von einem anderen Contributor oder von mir. Genau. Da wird euch dann geholfen. Und an der Stelle erstmal vielen Dank. Ja, wir haben zu danken für den Vortrag, für die Anführung, den Überblick und die Beispiele. Vielen Dank dafür. Wenn ihr noch Fragen habt,
36:21
ich sehe, es wird hier im Chat schon fleißig getippt. Wenn ihr im Stream zuschaut, bitte in die Videokonferenz reingehen. Da gibt es einen Chat in www. Da könnt ihr die Fragen reinschreiben. Wir versuchen, die jetzt hier noch zu beantworten. Wir haben noch ordentlich Zeit dafür. Und warten, was da so kommt. Ich glaube,
36:40
das ist eine sehr gute... Ich gerne. Ich erzähle weiter. Es ist natürlich eine wirklich schöne Möglichkeit, dass die Dokumentation auch nah beim Code ist, so sie zusammenverwalten kannst und wirklich auch die Änderungen von neuen Features im Code auch parallel mit der Dokumentation online sind.
37:01
Vielleicht dazu, dass du es getrennt führen würdest. Man kann sie dann auch gemeinsam reviewen an der Stelle. Genau. Man macht einen Peer-Review. Und das geht ganz normal im Software-Entwicklungsprozess. Auch die Dokumentation, was ganz angenehm sein kann. Ja, schauen wir mal in die Frage rein. Da kommt die erste rein.
37:22
Wir haben ein bisschen lag, wir beide, glaube ich. Genau, du liest die Fragen vor, ich antworte. So machen wir das. Okay. Die Frage sind, ist denn der reine Aurora Output so minimal oder hässlich, dass sich der Überbau mit anderen Zeitbildern so sehr empfiehlt?
37:46
Also, es kommt doch an, was für andere Zeitbilder ihr so habt. Wenn die Zeitbilder euch so etwas mitbringen, wie mehrere Versionen voneinander zu verwalten, dann braucht es vielleicht Aurora nicht. Wenn ihr sagt,
38:03
ihr seid mit eurer Markup-Sprache zufrieden, dass ihr auch die ganzen Querverweisungen zwischen Versionen machen könnt, zwischen den Komponenten, zwischen den Modulen machen könnt, beim Markdown ist es meistens, ich sag mal, irgendwas dazu gepackt ist, was dann irgendwie so ein gewisser
38:21
Markdown-Flavor wieder ist, dann seid ihr damit vielleicht auch gut bedient. Aber wie gesagt, diese Querverweise, diese Automatisierung, Sachen aus mehreren Git-Repositories auschecken können, on the fly, das ist eine Sache, ich glaube, die ist bei Aurora sehr, sehr gut gelöst. Spielt sehr gut ineinander.
38:41
Ja, und ist auch sehr gut integriert, dass man auch diese Trennung gut hinkriegt zwischen Leuten, die Inhalte schreiben und die dann sich um die Automatisierung kümmern. Die Leute, die Inhalte schreiben, zumindest jetzt mit dem IntelliJay-Plugin für ASCII-Doc und Aurora hat man auch diese Autovervollständigung. Ich denke, dann
39:01
ist das Ganze sehr rund und bietet da einen ganz guten Mehrwert. Dann gibt es eine Frage, die, wie es hier heißt, wirklich, weil es ins Detail geht so sehr, aber die Frage ist, ob, also bei plain ASCII-Doc würde ein multi-page HTML-Output fehlen,
39:22
das heißt, wenn er ein Verzeichnis mit 20 Dateien hat, ob dann auch 20 HTML-Dateien rauskommen, die man einzeln verlinken kann, Beispiel, da wäre als use case architecture decision records. Ja, also derjenige hat recht, gut, das ist ein Guest-Account, genau, Martin,
39:40
ich glaube, der Name stimmt. Genau, also dieses plain ASCII-Doc multi-page output, was da eben, das geht ganz gut eigentlich, dass man sozusagen aus jeder Datei eine HTML-Datei erstellt, was da aber dann auch fehlt, ist die Verlinkung. Die Verlinkung zwischen diesen verschiedenen ASCII-Doc-Dateien,
40:00
zumindest die passenden Unterstützungen dafür ganz gut hinzukriegen, ist manchmal schwierig. Das geht auch, ist aber halt dann doch ein bisschen, ich sag mal eher
40:20
Zeit einfacher und gut für einen Start, aber ich denke, wenn man gute Querverweise haben möchte, dann hilft einem auch diese Navigation, die man gestalten kann mit Anthora, die hat man bei diesem multi-page output in der Regel nicht so schön, weil man muss sie anders hinkriegen. Ja, gerade mit der Navigation hat Anthora noch einen deutlichen Vorteil, wenn man die
40:41
eben individuell gestaltet, also man hatte die ja gesehen. Die ist ja wirklich, ich sag mal, eine Crafted Navigation zumindest hier auf der linken Seite, wo ich dann wirklich sage, das möchte ich jetzt in der Gruppierung haben, das möchte ich so und so eingerückt haben. Das Beispiel, was hier sagt, was er hatte, war glaube ich dann
41:02
Architecture Decision Records. Das heißt, ich schreibe auf, während meiner Entwicklung, warum ich hier links und warum ich da rechts abgewogen bin und mich für die eine Variante oder die andere Variante entschieden habe. Was man da halt manchmal gerne haben möchte, sind automatische Inhaltsverzeichnisse. Zu sagen, es kommt eine neue Decision dazu und die soll automatisch mit in der Liste
41:22
auftauchen. Da müsste man glaube ich eine Erweiterung zu Anthora dazu nehmen oder selber schreiben an der Stelle oder vielleicht sich kurz in der Teil generieren lassen. Aber ich glaube automatische Listen mit Inhalten, da tut sich Anthora ein bisschen schwer.
41:42
Da bin ich mit, da kenne ich zum Beispiel Templating mit Hugo, dass man da sagt, gibt immer alle Dokumente, die in den Metadaten das und das stehen haben und macht mir daraus mal eine Liste und dann möchte ich die Liste als Liste anzeigen lassen und da reinspringen. Sowas gibt es bei Anthora Out of Box noch nicht.
42:04
Vielleicht schreibt jemand bald eine Erweiterung dafür. Nach einem Feature Request. Dann nochmal eine Rückfrage zu Dokumentation mehreren Sprachen. Ob man da pro Sprache ein eigenes Modul machen würde?
42:24
Entweder eine eigene Komponente oder ein eigenes Modul. Eins von beiden würde man sicherlich machen. Jetzt lasse ich mir überlegen, wo die Vorteile wären für ein Modul und wo die Vorteile wären für eine eigene Komponente.
42:43
Man muss halt gucken mit dem Querverweisen. Wenn man irgendwann von einer Komponente in eine andere Komponente verweist, muss man ausprobieren. Manchmal kann man sich bei den Xrefs Sachen weglassen. Normalerweise könnte ich hier auch die
43:00
Komponente schreiben und dann das Modul, so wie man es jetzt hier bei dieser Autoverforschung sieht. Vielleicht macht man entweder eine eigene Komponente oder ein eigenes Modul dafür. Dann hätte man halt irgendwo entweder hier einen DE dran, bei der User's Guide oder bei dem Routier einen DE dran.
43:21
Irgendwo würde man es wahrscheinlich dranhängen. Und mit PO4A. Das wäre, glaube ich, mein Favorit, um solche Lokalisierungen später zu machen. PO4A.
43:51
Hier steckt man auf der einen Seite ASCII-Doc rein, dann kommt ein PO5 raus für Lokalisierung und dann kann man quasi eine Übersetzung machen, quasi wie ein
44:01
Translation Memory in beidem Sinne. Dann lässt man es nochmal drüber laufen und dann kommt, wo man vorne ein Englisches reinsteckt und dann übersetzt es nach Deutsch, kommt dann ein deutsches ASCII-Doc wieder raus und das müsste man wieder einchecken. Dann würde man Anthora drüber laufen lassen. Anthora arbeitet nur mit Sachen, die wirklich im
44:21
Git irgendwo eingecheckt sind. Es sei denn, man arbeitet so in diesen Autorenmodus lokal, dann kann man auch mal einen Branch, den hätten, nehmen, der gerade lokal ausgecheckt ist, aber es muss halt immer eingecheckt sein. Das ist Versuch an der Antwort.
44:41
Und dann zur Ausgabe, ob es auch die Möglichkeit gibt, das gesammelt PDF, also ein PDF-Dokument raus zu rendern, statt HTML- Seiten? Von Haus aus erstmal nicht. Es gibt dann eine Zulip-Community
45:01
für Anthora und zu ASCII-Doc, wenn man auf die Homepage geht, wenn man hier Anthora Org eingibt. Ganz wichtig, wenn ihr etwas nach unten scrollen. Below the Fold ist sozusagen die Management Summary. Hier wird nämlich nochmal alles zusammengefasst. Sehr schön designt, aber es hat für mich, glaube ich, ein paar Monate gebraucht, bis ich immer angefangen habe zu scrollen
45:21
und nicht einfach nur noch auf Docs geklippt habe. Und es gibt hier die Community in Zulip, da kann man solche Fragen auch stellen, z.B. PDF. Es gibt eine Erweiterung dafür, die zumindest mal ein PDF, die ist noch ein bisschen früh im Stadion, die zumindest mal versuchen, ein PDF zu erstellen pro Seite,
45:40
dass man sich das auch unterlernen kann. Wenn man wirklich ein großes PDF erstellen möchte, gibt es von Haus aus für Anthora erstmal nichts, was einen aber vielleicht helfen kann, das zu sagen, man baut dann ein Masterdokument, ein Main-Dokument, wo man dann sagt, ich inklude die entsprechende Kapitel
46:00
in der Reihenfolge, in der ich sie haben möchte und generiere dann nochmal einen PDF aus den gleichen Inhalten, aber das ist etwas, da kann man halt wunderbar seinen ASCII-Doc-Content wiederverwenden. Aber Anthora hilft einem da erstmal nicht weiter.
46:21
Dann haben wir mehr eine Anmerkung als eine Frage. Marius schreibt, dass er verschiedene Markabsprachen als Dokumentation sich angeguckt hat und verweist hier auf seinen Blog. Jetzt weiß ich nicht, wie wir das in den Stream bekommen als URL. Also vielleicht einfach auch MattedMind. Gibt es eine Dokumentation in VCS.
46:43
Genau, dann kann man ... Genau. Müssen wir jetzt abschreiben hier oben? Ist vielleicht spannend, wenn man sich da mal so umgucken möchte nochmal. Na, cool. Prima. Und er sagt, das ASCII-Doc-Doc-Plugin
47:01
möchte er auf jeden Fall noch ergänzen. Oder muss er noch ergänzen? Prima, da freu ich mich. Gut. Okay, und dann eine Frage, wie das denn ist mit dem Einbetten von Videos, weil ASCII-Doc kann Videos einbetten, wie das denn mit Git und Anthora, nicht Anthora, ich will damit Anthora sagen, wie das mit Git und Anthora funktioniert, ob das wieder
47:20
deine Erfahrungen sind. Genau, wie ist meine Erfahrung damit, ich hab bis jetzt keine Bilder eingebettet, ich hab meistens eher mal Diagramme eingebettet, das klappt ganz gut, da gibt's sowas, gibt's Kroki, ich weiß nicht, wer das kennt, das war hinten aber allerdings dabei. Aber letztens hat das mal ein Nutzer ausprobiert, und das klappt offensichtlich, das heißt, man
47:40
hat im Moment den Ordner, der heißt Images, und hat einfach mal ausprobiert, ob man da auch ein Video reinschmeißen kann, und dann hat er gemerkt, das geht ja, und hat dann die Frage im Chat gestellt, ja, ist das denn okay, dass das so funktioniert, meinte Dan Allen, der Maintainer von Anthora, nach dem Motto, ja, schön, dass das funktioniert, aber eigentlich wollte man doch noch mal einen eigenen Ordner dafür machen, aber so,
48:00
dass das so funktioniert, funktioniert das wohl, und jetzt hab ich glaube ich im GitHub ein Issue offen, nach dem Motto, ja, da, also, Dan war dann nicht so ganz begeistert, sag ich mal so. Wir haben ja ein bisschen Zeit, wir können ja ein bisschen Anekdoten machen.
48:20
So, dann gibt's jetzt irgendwo die Issues hier. Genau, dass Anthora das unterstützt, das IntelliJ Plugin auch noch nicht unterstützt, wie gesagt, er hat's jetzt hier reingepackt und commited, und dann ist halt der Wunsch, dass das IntelliJ Plugin doch bitte auch die Autoververschwindigung macht, ja,
48:40
und im Chat, also vor allem im Chat, im Zulip Chat, aber jetzt nicht hier drin, wo Dan meinte, na, ob man jetzt, das ist doch eigentlich eher, ist doch kein Feature in dem Sinne, sondern eher so ein Zufall, dass das passiert, ob man das jetzt im Plugin unterstützen sollte. Ja, mal gucken, wahrscheinlich bauen wir das doch erstmal ein, und dann gibt's halt irgendwann
49:01
den Hinweis, hier, es gibt jetzt einen neuen Ordner für Videos oder so, und möchtest du das nicht mal verschieben. Also, es gibt so ein paar Inspections, die wir auch schon gebaut haben, im ASCII-Doc und Anthora Plugin für IntelliJ, dass man halt sagt, hier, früher konnte man in Anthora ASCII-Doc die
49:20
Endung ADOC weglassen bei den Xrefs, in den neueren Versionen wird sie glaube ich, sogar entzwungen inzwischen, früher empfohlen und dann entzwungen, dass es halt so Inspections gibt, die sagen, hier, nach dem Motto, ja, das funktioniert jetzt noch, aber bitte fang doch schonmal an die,
49:40
ja, fang doch schonmal an die Endung hier zu ergänzen. Und eine Frage, ob es ein Anthora Plugin für VS Codeum Visual Studio gibt, ob da was bekannt ist, ob es sowas gibt. Visual Studio Code, da gibt es eine ASCII-Doc-Unterstützung,
50:02
aber diese ASCII-Doc-Unterstützung hat Stand heute noch keine Unterstützung für Anthora. Das führt dann dazu, dass man zwar ASCII-Doc-Inhalte schreiben kann, aber vielleicht die Bilder in der Vorschau noch nicht so ergänzt werden, wie es denn ergänzt werden könnte, oder
50:22
die Querverweise noch nicht auch so aufgelöst werden, wie sie aufgelöst werden könnten. Sagen wir so, die Funktionalitäten, also ich bin jetzt kein Visual Studio Code Nutzer im täglichen Umfeld, von daher ist mein persönlicher Bedarf da gering. Ich weiß aber, viele andere nutzen Visual Studio Code.
50:42
Ich sag mal so, die das IntelliJ Plugin hat seine Funktionalität dokumentiert. Da kann man durchaus mal abschreiben, es ist Open Source. wer dazu Fragen hat, und der gerne was bauen möchte, der ist auch herzlich eingeladen,
51:00
auch mal, dass man sich zusammensetzt, überlegt, wie kann man sowas auf der anderen Seite bauen, oder dann chatet man, man trifft sich auf GitHub, dann macht man Videocall, also im Sinne des Anthora-ASCII-Doc-ASCII-Docter- Ökosystems bin ich da durchaus offen, aber ich werde nicht derjenige sein, der es auf der anderen Seite programmiert.
Empfehlungen
Serie mit 4 Medien