Implementierung der DITA Single Source-Technologie in einem Softwareentwicklungsunternehmen

    Hallo! Ich heiße Elena Tolmacheva. Bei DoxVision entwickle ich Benutzerdokumentation.

    In letzter Zeit ist es immer beliebter geworden, zur Erstellung von Handbüchern aller Art für den Betrieb komplexer Softwaresysteme eine Single-Source-Technologie zu verwenden, bei der beliebige Texte oder Bilder in den entwickelten Dokumenten wiederverwendet werden. Vor nicht allzu langer Zeit haben wir begonnen, diese Technologie für die Entwicklung von Referenzen und gedruckten Dokumenten von DoksVision anzuwenden, und in diesem Artikel möchte ich meine Erfahrungen teilen.



    Warum haben wir uns für Single Source Technologie entschieden?


    Diejenigen, die mit dem Unternehmen DoksVision vertraut sind, wissen, dass das Hauptprodukt, das wir entwickeln, die Docsvision-Plattform ist. Darüber hinaus werden viele zusätzliche Anwendungen und Module veröffentlicht. Da Hilfsprodukte zur Verwendung als Teil der Plattform vorgesehen sind, mussten wir bei der Beschreibung von Benutzeraktionen in der Dokumentation einen Teil des Textes duplizieren: entweder vollständig oder mit geringfügigen Änderungen. Dieser Ansatz (unter Berücksichtigung der regelmäßigen Veröffentlichung neuer Versionen für alle Produkte) war für technische Redakteure sehr mühsam Die Vielzahl der verfügbaren Beschreibungen ermöglichte es uns nicht, Änderungen in allen sich wiederholenden Abschnitten nachzuverfolgen und schnell Änderungen an vielen Dokumenten gleichzeitig vorzunehmen.

    Es gab andere Schwierigkeiten:

    • Der Editor, in dem die Entwicklung durchgeführt wurde, beinhaltete nicht die gleichzeitige Arbeit mit einem Dokument mehrerer technischer Redakteure, was die Organisation der Teamarbeit am Projekt erschwerte.
    • Kunden kontaktierten das Unternehmen mit Anfragen nach Dokumenten in verschiedenen Formaten: Einige bevorzugten Informationen, andere benötigten die Möglichkeit, Text zu bearbeiten oder zu drucken. Wir hatten keine solche Gelegenheit.
    • Wir wollten auch, dass alle ausgestellten Dokumente den gleichen Stil haben. Aufgrund des menschlichen Faktors konnten wir dies jedoch in keiner Weise erreichen: Die bereitgestellte Dokumentvorlage ermöglichte es uns, Änderungen vorzunehmen, und jemand änderte sie regelmäßig nach eigenem Ermessen, was den allgemeinen Eindruck der Unternehmensdokumente beeinträchtigte.

    In dem Moment, in dem die Anzahl der Minuspunkte unsere Geduld überforderte, wurde beschlossen, die Art und Weise, wie Dokumente entwickelt werden, radikal zu ändern. Aus diesem Grund haben wir uns für die Single-Source-Technologie entschieden und uns speziell für die Verwendung der DITA-Architektur in unserer Arbeit entschieden .

    Warum DITA?


    Wir mochten die DITA-Technologie aus mehreren Gründen. Diese Architektur wurde speziell für technische Redakteure entwickelt, und viele der Bedürfnisse der Dokumentationsersteller wurden bereits berücksichtigt. Folgende Faktoren waren für uns ausschlaggebend:

    • die Fähigkeit, Dokumente in verschiedenen Formaten (PDF, HTML5 und XHTML, Eclipse-Hilfe, TocJS, HTML-Hilfe, Java-Hilfe, ODE, RTF, troff) auszustellen,
    • die harte Gliederung von Abschnitten aufgrund typisierter "Themen" ( Konzept, Aufgabe, Referenz usw.)
    • die Fähigkeit, für mehrere Mitarbeiter gleichzeitig an einem Projekt zu arbeiten.

    Wir wählten die Technologie aus und begannen, einen Plan für deren Implementierung zu erstellen.

    Planung


    Zu Beginn der Reise haben wir einen Plan erstellt, der natürlich angepasst werden musste. Hier gebe ich eine Reihe von Stufen in einer strengen Reihenfolge der Ausführung an, die (unserer Meinung nach) für die Lösung der Aufgabe optimal ist. Ich mache Sie darauf aufmerksam, dass der Plan für den Übergang zu einer Single-Source-Technologie geeignet ist (nicht nur die von uns gewählte DITA).

    Die Phasen unseres Plans sind:
    1. Werkzeuge
    2. Standardisierung
    3. Design
    4. Anpassung
    5. Lagerung
    6. Schulung Im

    Folgenden werde ich alle diese Phasen detailliert beschreiben. Und erinnern wir uns an die Spezialisten, die bei der Implementierung behilflich sein können. Bei der Umstellung auf das neue System benötigten wir:
    • Designer - half bei der Erstellung von Design-Layouts für Dokumente
    • Programmierer - Richten Sie ein Tool zum Zusammenstellen eines Dokuments in verschiedenen Formaten ein.
    Ein technischer Redakteur koordinierte alle diese Arbeiten.

    Die Werkzeuge


    Neue Technologien erfordern die Verwendung neuer Software. In der ersten Phase der Implementierung muss daher eine bestimmte Software ausgewählt und gekauft werden. Sie benötigen mindestens:
    • einen Editor für technische Redakteure (wir haben den Oxygen XML Author ausgewählt)
    • ein Tool zum Zusammenstellen von Dokumenten vom Quellformat zum endgültigen (wir haben das DITA Open Toolkit zum Konvertieren von XML-Dateien in die mitgelieferten Formate pdf und xhtml ausgewählt)
    • ein Speichersystem für Quelldateien und resultierende Dokumente (wir haben TFS gewählt)

    Wenn Sie sich für einen Editor entscheiden, verlassen Sie sich auf die Benutzerfreundlichkeit, die Verfügbarkeit von Funktionen für die Ausführung der von Ihnen benötigten Aufgaben und natürlich auf die Kosten einer professionellen Version. Ich stelle fest, dass die Unterstützung für die Arbeit mit DITA in fast allen gängigen Editoren für technische Redakteure (Oxygen XML Editor, XML Mind, DocBook, AuthorIt) implementiert ist.

    Die Auswahl eines Tools zum Zusammenstellen eines Dokuments ist möglicherweise nicht erforderlich, wenn der erworbene Editor das Zusammenstellen eines Dokuments in dem für die Freigabe erforderlichen Format und Format ermöglicht. Mit Design meine ich in diesem Fall den Standard, den Ihr Unternehmen übernommen hat: Schriftarten, Logos, Farbgestaltung, Format der endgültigen Dokumente usw.

    Das Speichersystem kann genauso verwendet werden, wie es die Entwickler in Ihrem Unternehmen zum Speichern des Programmcodes verwenden. In diesem Fall können Sie beim Kauf sparen. Sie brauchen nur einen guten Weg zu finden, um das Repository zu organisieren, auf den ich weiter unten eingehen werde.

    Standardisierung


    In der zweiten Phase der Implementierung ist eine Standardisierung der Dokumente erforderlich. Erstens, um eine einheitliche Struktur der Dokumentation zu erreichen und dem Designer die Formulierung eines Stildesigns zu ermöglichen.

    Was muss standardisiert werden:
    • Arten von Dokumenten, die für jedes Produkt des Unternehmens ausgestellt werden (Benutzerhandbuch, Administratorhandbuch usw.)
    • Dokumentenstruktur für jede der zulässigen Arten (Titelseite, Einführung, Kapitel, Abschnitte, Dokumentenliste, Anwendungen)
    • Zusammensetzung Elemente für jedes Element der Struktur (z. B. für das Deckblatt: Logo, Produktname, Systemname, Version, Dokumenttyp)
    • Liste der endgültigen Formate (pdf, odt, xhtml usw.)
    • Liste der Lokalisierungen (Russisch, Englisch usw.)
    • Methode zur Nummerierung von Produktversionen und Versionen der ausgegebenen Dokumente für das Produkt Ich werde

    erklären, warum ein so strenger Standard erforderlich ist. Betrachten Sie als Beispiel die Titelseite der Docsvision-Dokumentation, die in der Hilfe und im gedruckten Format in der Zusammensetzung der Elemente und in der Art und Weise, wie sie gestaltet sind, unterschiedlich aussieht. Die Hilfe enthält beispielsweise eine Beschreibung des Zwecks des Dokuments (das nicht auf der Titelseite, sondern im Abschnitt Einführung gedruckt ist), ein Suchfeld und ein Inhaltsverzeichnis. Bitte beachten Sie, dass der restliche Text dieser Blätter vollständig identisch ist, durch die Norm definiert ist und nicht vom Stil abhängt.


    Abb. 1. Ein Beispiel für die Zusammensetzung der Elemente der Titelseite

    Das Erstellen eines Standards ist vielleicht die wichtigste Phase der Implementierung, da Standardisierungsfehler dann reibungslos in die Entwurfslayouts und von dort in das Programm zum Zusammenstellen der endgültigen Dokumente einfließen. Wenn es viele Fehler gibt, müssen alle Arbeiten neu begonnen werden.

    Design


    Während der Entwurfsphase müssen grafische Layouts der Dokumentation erstellt werden, damit der Programmierer beim Einrichten des Tools zum Zusammenstellen des Dokuments ein klares Verständnis darüber hatte, wie die Hilfewebseite oder ein Blatt im gedruckten Format aussehen sollte.

    Es ist ratsam, den Designer im Voraus mit dem im Unternehmen verwendeten Style Guide vertraut zu machen, und wenn dies plötzlich nicht mehr der Fall ist (was häufig vorkommt), dann zumindest mit der Website des Unternehmens.

    Layouts müssen vorbereitet werden:
    • für jedes der zuvor standardisierten Formate der endgültigen Dokumente, z. B. einen separaten Satz von Bildern für PDF und einen separaten Satz von Bildern für XHTML-Hilfe
    • für jeden ihrer standardisierten Stile (z. B. wenn verschiedene Produkte gemäß dem Stil des Unternehmens verwendet werden) Farbskala)
    • Für jede der standardisierten Sprachen (in Fremdsprachen werden möglicherweise unterschiedliche Begriffe verwendet, der Programmierer kennt beispielsweise die Übersetzung des Wortes "Suche" ins Französische nicht).

    Vorbereitete Layouts sollten mit der Unternehmensleitung abgestimmt werden. Anschließend können Sie mit der Einrichtung fortfahren.

    Anpassung


    Wie ich bereits gewarnt habe, müssen Sie wahrscheinlich Programmierer verschiedener Spezialisierungen anschließen, um das Setup abzuschließen. Für die Erstellung von Zertifikaten sind CSS-Kenntnisse erforderlich. Am besten wenden Sie sich an einen Layoutspezialisten. Und um die Ausgabe in Druckformaten einzurichten, ist möglicherweise nur der Satz nicht ausreichend. Um beispielsweise das Dita Open Toolkit zu konfigurieren, mit dem wir das PDF-Format erstellt haben, brauchten wir einen Spezialisten, der mit XSLT-Transformationen vertraut ist.

    Ich weiß nicht, welche Programmierer Sie benötigen. In jedem Fall sollten jedoch die folgenden wichtigen Faktoren berücksichtigt werden:
    • Wie viele Formate werden vom fertigen Programm aus den vom technischen Redakteur bereitgestellten Quelldateien erfasst?
    • Wie viele Stiloptionen von einem Programm oder mehreren Programmen für verschiedene Stile zusammengestellt werden können, wird benötigt.
    • Wie viele Sprachen unterstützt das Programm, und ob es möglich ist, die Ausgabesprache mit einer einfachen Einstellung zu ändern.

    In der Abbildung ist ein Beispiel für die Bestimmung der Anzahl der Werkzeuge zum Zusammenstellen von Dokumentationen dargestellt.


    Abb. 2. Optionen zum Einrichten eines Programms für die Dokumentationserstellung

    Beachten Sie bei der Berechnung der für die Programmierung vorgesehenen Zeit, dass dieser Vorgang häufig mehrere Monate dauert. Während der Arbeit benötigt der Dokumentierer möglicherweise neue Tabellen, Überschriften usw., und dann muss das Programm finalisiert werden.

    Lagerung


    Single-Source-Technologie bedeutet, dass die Quelldateien eines Dokuments (von technischen Redakteuren erstellt) und fertige Dokumente (von einem Programm zum Zusammenstellen eines Dokuments erstellt) unterschiedliche Dateien sind. Und diese Dateien sollten auch separat gespeichert werden. Es ist optimal, dasselbe Versionsspeichersystem wie die Codeentwickler Ihres Unternehmens zu verwenden.


    Abb. 3. Das Prinzip der Speicherung von Dateien in einer Single-Source-Technologie

    Die Struktur der Speicherung von Quelldateien sollte auf dem folgenden Prinzip beruhen:
    • Die Methode zur Speicherung von Dateien für alle technischen Redakteure sollte vereinheitlicht werden.
    • Die Namen von Dokumenten sollten standardisiert sein.
    • Versionen von ausgestellten Dokumenten sollten sich nicht überschneiden.
    • Zertifikate, die automatisch mit dem Programmcode gesammelt werden, sollten am selben Ort wie der Code gespeichert werden.

    Die Struktur der Speicherung der endgültigen Dokumente sollte
    Folgendes umfassen: • getrennte Speicherung verschiedener Versionen;
    • im Rahmen der Version:
    - getrennte Speicherung für verschiedene Formate;
    - Separate Lagerung für verschiedene Standorte.

    Schulung


    In der letzten Phase der Implementierung müssen Sie Kollegen für die Arbeit mit neuer Technologie schulen.

    Zuallererst müssen technische Redakteure einen neuen Editor für das Schreiben von Text beherrschen.
    Sie müssen wahrscheinlich auch die Liste der Tags untersuchen, die vom Programm verarbeitet werden, um die Dokumentation zu erstellen. Beispielsweise verwenden wir bei DoxVision DITA-Spezifikations-Tags .
    Wenn ein Teil des Textes vor der Verwendung der Single Source-Technologie kopiert wurde, muss und kann er nun für die Wiederverwendung erlernt werden. Darüber hinaus müssen die Kollegen mit neuen Datenspeicherungsstrukturen vertraut gemacht und sorgfältig überwacht werden, dass dieser Standard von allen eingehalten wird.

    Was ist das Ergebnis


    Wenn die Implementierung erfolgreich ist, wird die Qualität der zu entwickelnden Dokumentation erheblich zunehmen und die Produktionskosten werden sinken. Technische Redakteure werden mehr Freude an ihrer Arbeit haben und ihre Führungskräfte werden von den Partnern positives Feedback erhalten.

    Abschließend möchte ich sagen, dass die Einführung einer Single-Source-Technologie im Durchschnitt etwa sechs Monate dauert und die Übertragung zuvor entwickelter Dokumente in ein neues Format ebenso viel Zeit in Anspruch nimmt.

    Zur Information: Viele Materialien zu DITA sind auf der DITA Writer-Website gesammelt, und es gibt dort eine Liste mit Referenzen .

    Ich hoffe, dieses Material wird Ihnen nützlich sein und Ihnen helfen, schnell und schmerzlos auf eine neue Technologie umzusteigen!

    Jetzt auch beliebt: