Guten Tag.
Als einer der Entwickler des Open-Source-
Embox- Projekts habe ich oft (zu oft in letzter Zeit) gehört, dass das Projekt interessant ist, aber da es keine Dokumentation gibt, kann es nicht verwendet werden. Wir antworteten, dass es eine Art Dokumentation gibt, dass wir immer Fragen beantworten können, dass Sie in extremen Fällen versuchen können, es selbst herauszufinden, weil das Projekt offen ist, aber all dies passte nicht. Ich musste mich mit diesem für Entwickler sehr unangenehmen Thema befassen. Aber natürlich geht es in dem Artikel nicht darum, dass Dokumentation „unangenehm“ ist! Und darüber, wie wir den Dokumentationsentwicklungsprozess komfortabler gestaltet haben. In der Tat treten bei mehr oder weniger großen Projekten notwendigerweise Probleme im Zusammenhang mit der Dokumentation auf.
Für diejenigen, die zu faul zum Lesen sind, sage ich sofort, dass wir am Ende zur Entwicklung der Dokumentation im Markdown-Format gekommen sind. Nun, für diejenigen, die sich für die Details interessieren, die Gründe für den Abschlag und die Vor- und Nachteile dieses Ansatzes, bitte ich um Katze.
Ich werde zunächst die Relevanz des Themas begründen. Nicht nur Embox hat Dokumentationsprobleme. Zum Beispiel hat Google ein Analogon zum GSOC-Programm (Google Summer Of Code) für technische Redakteure
Season of Docs angekündigt. Das Unternehmen Kaspersky Lab veranstaltet
Konferenzen für technische Redakteure . Und das Unternehmen Parallels veröffentlicht
auf dem Hub Artikel zum Schreiben von Dokumentationen . All dies deutet darauf hin, dass das Thema wichtig ist und möglicherweise zu Unrecht der Aufmerksamkeit beraubt wird.
Die oben erwähnte Artikelserie versteht den korrekten Inhalt der Dokumentation, aber ich möchte mich auf den Prozess der Entwicklung von Dokumentation und Technologie konzentrieren, wenn Sie möchten. In der Tat ist für ein Open-Source-Projekt die Offenheit als Eigenschaft des Entwicklungsprozesses das Markenzeichen. Und wir wollten einen Prozess schaffen, der die Anforderungen unseres Projekts erfüllt.
Ein kurzer Exkurs in die Geschichte unserer Dokumentationsentwicklungsprozesse.
Sobald das Projekt auf
Google Code gefunden wurde . Wir hatten ein ziemlich anständiges Wiki, viele erinnern sich sogar daran, fragen, wo es zu finden ist und bitten, es an Github zu übertragen, wo sich das Projekt jetzt befindet (oder an einem anderen zugänglichen Ort). Das Google Code Wiki war sehr praktisch. Es war mehrsprachig und hatte meiner Meinung nach mehr Funktionen als das Wiki auf Github. Aber es ist so passiert, dass es zusammen mit Google Code selbst in Vergessenheit geraten ist. Das aktuelle Wiki auf Github erfüllt die ihm zugewiesene Funktion, Betriebsinformationen über das Projekt bereitzustellen, recht gut, aber es ist ziemlich schwierig, eine vollständige Dokumentation auf dieser Plattform zu erstellen.
Natürlich benötigen Sie für jedes Open-Source-Projekt sowohl eine Online-Dokumentation (schnell zugänglich) online, deren Rolle das Wiki spielt, als auch eine vollständige Dokumentation, die offline verfügbar ist, da es viel einfacher ist, das Wesentliche und die Ideologie des Projekts zu verstehen. Darüber hinaus ist die Offline-Suche in einem einzelnen Dokument anstelle unterschiedlicher Wiki-Seiten viel einfacher.
Die wahrscheinlich beste Option, die ich kenne, ist die
ARM-Dokumentation . Das heißt, Online-Dokumentation, bei der in allen Abschnitten gesucht wird, aber ein bestimmtes Dokument im PDF-Format zum Download zur Verfügung steht. Leider hat Embox das ARM-Niveau in Bezug auf die Funktionen noch nicht erreicht. Daher mussten wir die Offline-Version separat machen. Dafür haben wir den
Google Text & Tabellen- Dienst verwendet. Dies ist praktisch, weil: Sie Daten in verschiedenen Formaten herunterladen, zusammenarbeiten und über ein integriertes Versionskontrollsystem verfügen können. Wir haben einige Informationen aus dem Wiki übertragen, die Struktur festgelegt, da das Ziel der Entwicklung der Offline-Version darin bestand, eine ganzheitliche Dokumentation zu erstellen, und mehrere Dokumente entwickelt. Aber schnell genug stießen wir auf Probleme. Die Informationen waren veraltet, die Daten aus dem Wiki stimmten nicht mit den Daten aus der Offline-Dokumentation überein, und vor allem konnten wir keine vollständige Dokumentation erstellen. Es gab eine Struktur, aber da es nicht möglich war, anständiges Feedback von Benutzern zu erhalten, stellte sich heraus, dass nur die Entwickler die Dokumentation verstehen können. Dies ist sicherlich kein Serviceproblem, aber die Tatsache, wie sie sagen, ist offensichtlich. Wir mussten nach einem anderen Ansatz für dieses Problem suchen.
Dann haben wir versucht, nur die Daten aus dem alten Wiki in den Wiki-Github zu übertragen, aber selbst dann sind wir schnell auf Probleme gestoßen. Wir haben festgestellt, dass ein Teil der Informationen veraltet ist, ein Teil nicht hinzugefügt wurde und ein Teil nicht klar war, wie sie in einer benutzerfreundlichen Form dargestellt werden sollen. Als wir die Suche nach einer Lösung für das Problem fortsetzten, haben wir irgendwann sogar über die Entwicklung der Dokumentation in TeX unter Verwendung des Git-Repositorys nachgedacht, aber schnell erkannt, dass dies bereits zu viel war. Obwohl diese Idee einen Einfluss hatte.
Wir haben uns entschlossen, aus der Dokumentation zu formulieren, was wir wollen, dh aus dem Prozess der Dokumentationsentwicklung lassen wir den Inhalt außerhalb der Klammern:
- Die Dokumentation sollte im Textformat aufbewahrt werden, da Git als Versionskontrollsystem verwendet werden sollte
- Die Dokumentation sollte Online- (Wiki) und Offline-Versionen (separate Dokumente, z. B. im PDF-Format) enthalten
- Online- und Offline-Dokumentation sollten problemlos synchronisiert werden können.
- Die Dokumentation sollte aus Abschnitten (Kapiteln) bestehen, die separat entwickelt oder studiert werden können, aus denen Sie jedoch eine vollständige Dokumentation erstellen können
Keiner der Punkte widerspricht der Verwendung von Markdown, und es war interessant, da es bereits im Wiki verwendet wird. Sie können natürlich ein anderes Format verwenden und es in Markdown konvertieren. Nachdem wir jedoch eine weitere Liste von Anforderungen zusammengestellt hatten, um verschiedene Arten von Inhalten (Bilder, Text, Formatierung) hinzuzufügen, kamen wir zu dem Schluss, dass der Abschlag alle unsere aktuellen Anforderungen ausreichend erfüllt. Und das allererste Google zum Thema „Markdown to pdf“ hat gezeigt, dass die Optionen zum Konvertieren von Markdown in andere Formate existieren und sehr beliebt sind.
Es gibt verschiedene Möglichkeiten, Markdown in PDF umzuwandeln , aber
Pandoc ist bei
weitem am beliebtesten. Dieses Dienstprogramm kann jedes Textformat in ein beliebiges Textformat umwandeln. Darüber hinaus ist es freitragend. Daher ist es uns nicht nur vertraut, sondern kann auch in Skripte integriert werden, um Dokumentationen in verschiedenen Formaten zu erstellen.
Wir entschieden uns für das Dienstprogramm und begannen, über die nächste kleine Frage nachzudenken, die wir lösen mussten, nämlich wie man ein einzelnes Dokument erstellt und nicht viele PDF-Dateien mit verschiedenen Kapiteln, die aus separaten Markdown-Dateien stammen. Der erste Wunsch war einfach, die Dateien in der gewünschten Reihenfolge zu „speichern“ (um Text aus verschiedenen Dateien zusammenzuführen), aber es stellte sich als viel einfacher heraus, Pandoc selbst ist perfekt in der Lage, mit der Liste der Dateien zu arbeiten. Dadurch konnten wir auch das Problem teilweise lösen, dass wir verschiedene Dokumente benötigen, in denen sich der Inhalt überschneiden kann. Zum Beispiel generieren wir drei Dokumente und alle drei enthalten einen kurzen Beschreibungsabschnitt. Wir listen diese Datei einfach in der Liste für Pandoc für alle Dokumente auf.
Wir wenden ein ähnliches Prinzip auf Deckblätter an, auf denen der Titel des Dokuments enthalten ist, und so weiter. Wir haben gerade Dateien mit Kopfzeilen für jedes Dokument erstellt und sie als erste Dateien in die Quellliste für Pandoc aufgenommen.
Wie Sie wahrscheinlich vermutet haben, löst dies (eine Liste verschiedener Dateien) das Problem der Mehrsprachigkeit. Wir geben lediglich die Dateien mit der gewünschten Sprache an.
Lassen Sie uns etwas mehr über Russisch sprechen. Bei der Erstellung von PDF-Dateien verwendet pandoc Latex als Backend für das Rendern, die Rechtschreibprüfung usw. Standardmäßig wird Kyrillisch nicht angezeigt und ein Fehler bezüglich eines unbekannten Zeichens wird angezeigt. Dies wird sehr einfach gelöst, geben Sie einfach "babel russian" an.
--- ... header-includes: - \usepackage[russian]{babel} ---
Es ist zu beachten, dass die Angabe korrekter ist
--- ... header-includes: - \usepackage[russian, english]{babel} ---
Und verwenden Sie Latexbefehle im Text
\selectlanguage{russian} \foreignlanguage{english}{ English text }
Oder
\begin{otherlanguage}{english} Text in english \end{otherlanguage}
Da wir jedoch einen „sauberen“ Preisnachlass für eine mögliche Übertragung in das Wiki beibehalten wollten und sich herausstellte, dass die Babel-Direktive für unsere Zwecke ausreichte, haben wir beschlossen, sie nicht zu komplizieren und sie unverändert zu lassen.
Natürlich wollten wir keine Dokumente formatieren, sondern zumindest einheitlich aussehen. Und hier hat uns Latex wieder geholfen. Tatsache ist, dass Pandoc Latex verwendet und Sie Latexvorlagen dafür angeben können. Dies geschieht einfach mit der Option --template
pandoc --template=embox_pandoc.latex ...
Nachdem Sie eine Vorlage kompiliert und beim Generieren aller Dokumente angegeben haben, erhalten Sie Dokumente in einem mehr oder weniger einheitlichen Stil. "Mehr oder weniger" - weil es einige Probleme gibt, die wir nicht lösen konnten. Zum Beispiel die Bildung eines einzelnen Codeblocks. Beim Markdown kann ein einzelner Codeblock angegeben werden, damit er nicht formatiert wird und die Syntaxhervorhebung möglicherweise aktiviert ist. Aber wir haben es geschafft, nur einzeilige Blöcke zu machen. Dies stellte sich nach Betrachtung des generierten Latexcodes heraus.
Das heißt, es gab Fälle, in denen derselbe Block etwas unterschiedlich auf verschiedenen Dokumenten platziert wurde.
Ein weiterer Punkt im Zusammenhang mit dem kyrillischen Alphabet, nämlich die Verwendung der russischen Sprache. Wie oben erwähnt, hat es sich als ausreichend erwiesen, das russische Babel in der Kopfzeile anzugeben, um die russische Sprache zu verwenden. Wir sind jedoch auf einige Kuriositäten gestoßen, zum Beispiel gab es keine kühnen Hervorhebungen und andere Formatierungs-Kuriositäten. Anfangs haben wir darüber gesündigt, dass Russisch in Großbuchstaben und nicht in einer Vorlage angegeben ist. Sie begannen, das Problem zu untersuchen. Es stellte sich heraus, dass man auf gute Weise nicht nur verwenden muss
\usepackage[russian, english]{babel}
sondern auch
Schriftarten einstellen \usepackage[T1,T2A]{fontenc} \usepackage[utf8]{inputenc}
Aber selbst nachdem dies geschehen war, war es nicht möglich, die Situation zu korrigieren. Es stellte sich heraus, dass nicht alle Schriftsätze alle Rendering-Optionen enthalten, insbesondere unsere nicht fett, kursiv usw. in anderen Formaten. Da es keine einfache Lösung für das Problem gab, haben wir das Problem überlegt und auf bessere Zeiten verschoben. Nun, da wir einen sauberen Markdown verwenden wollten (dh ohne Angabe von Latexbefehlen), haben wir eine gemeinsame Vorlage für beide Sprachen erstellt, und die Angabe zur russischen Sprache wurde in die Kopfzeile eingefügt.
Nur ein paar Worte werde ich über die Oberfläche der Anwendung selbst sagen. Da, wie gesagt, Konsolenanwendungen uns persönlich sehr vertraut sind und leicht in Skripte gepackt werden können. Eigentlich ist die Oberfläche einfach, natürlich können Sie viele Optionen festlegen, aber für unsere Zwecke reicht es aus, eine Vorlage, eine Liste von Eingabedateien und eine Ausgabedatei anzugeben.
pandoc --template=embox_pandoc.latex <title file> <list of input markdown files> -o <output file>
Im Internet finden Sie, dass Sie zum Generieren von PDF (oder einem anderen Ausgabeformat) einen Prozessortyp mit der Option --pdf-engine = xelatex benötigen. Standardmäßig wird dieser jedoch verwendet, wenn die Ausgabedatei die Erweiterung pdf hat. Deshalb haben wir das auch nicht gebraucht.
Wir haben die Skripte zum Zusammenstellen der Dokumentation in ein Makefile gepackt, damit es ziemlich vertraut wird. Und jetzt, um die Dokumentation zu erhalten, können Sie die erforderliche Umgebung einstellen, rufen Sie einfach an
make [en][ru]
Abschließend noch ein paar Worte zum Versionskontrollsystem. Das Prinzip ist nicht zu komplizieren (einfach zu halten), wir haben versucht, uns an alles zu halten. Und da die einfachste Lösung darin bestand, ein separates Repository für Github zu verwenden, haben
wir dies getan . Wir hoffen, dass die Verwendung von Github das Feedback der Benutzer verbessert. Wie Sie auf Github wissen, gibt es schließlich Probleme, bei denen Sie Mängel diskutieren und Ihre Ideen und Anweisungen anbieten können.
Dieser Prozess wurde kürzlich auf Wunsch vieler Arbeiter gestartet! Wir haben es geschafft, die
englische und
russische Version des „Schnellstarts“ sowie die
erste Version des russischen Benutzerhandbuchs zu erstellen . Der Prozess selbst erschien uns bequemer, weshalb wir ihn mit der Öffentlichkeit teilen.