Docs as Code - Die neue Art, Dokumente zu erstellen

Inhaltsverzeichnis
Allgemeines
Docs as Code

In diesem Blogbeitrag erhalten Sie grundlegende Einblicke in die Philosophien des technischen Schreibens sowie Einblicke von Spezialisten und Experten auf diesem Gebiet. Was machen technische Schriftsteller? Unter Bezugnahme auf T. R. Girills Aufsatz über "Philosophy's Relevance to Technical Writing" können wir sagen, dass "technische Schriftsteller Forschungsberichte, Vorschläge, Anleitungen und Newsletter für medizinische Zentren, Fertigungsunternehmen, Finanzinstitute und staatliche Labors erstellen." Natürlich repräsentiert dies nur einen kleinen Teil der Anwendungsfälle für technische Schriftsteller, und es gibt noch viele weitere, die Sie sich vorstellen können. Konzentrieren wir uns zunächst auf das technische Schreiben von Handbüchern. Ryan Brong verdeutlicht dies in seinem Blog "Ryan Brong's ePortfolio,", indem er schreibt, dass Ingenieure und wissenschaftliche Forscher ihre Ideen mithilfe einer klaren technischen Kommunikation an die Öffentlichkeit bringen müssen.

Viele Unternehmen und Sektoren verlassen sich bei der Kommunikation auf das technische Schreiben. Es vereinfacht Komplexität und ermöglicht ein klares Verständnis und die Umsetzung von Ideen, Theorien, Praktiken oder Verfahren.

Es ist von immenser Bedeutung für Unternehmen und Branchen, die Benutzerdokumentationen, Anleitungen, technische Berichte, Machbarkeitsstudien, Unternehmensberichte, Forschungsergebnisse, Richtlinien und Verfahren, Geschäftspläne, Weißbücher, Fallstudien, Literaturübersichten, Vorschläge und mehr verwenden.

Technisches Schreiben, seit den Anfängen der Schriftsprache vorhanden, erfährt ein rasantes Wachstum, insbesondere in unserer fortschreitenden Ära der Telekommunikation. Seine Popularität lässt nicht nach und wird noch Jahrzehnte lang ein fester Bestandteil unserer Welt sein.

Was heißt das und wie fuktioniert es?

Das bedeutet, dass technisches Schreiben komplexe Ideen vereinfacht, um sie leicht verständlich und in verschiedenen Kontexten wie Benutzerdokumentationen, Berichten, Studien und Plänen umsetzbar zu machen.

Im Wesentlichen beinhaltet technisches Schreiben das klare und effektive Vermitteln technischer Informationen. Es stellt sicher, dass komplexe Konzepte auf eine Weise präsentiert werden, die für die beabsichtigte Zielgruppe zugänglich ist. Dies kann das Aufschlüsseln komplizierter Prozesse, die Erklärung spezialisierter Terminologie und die Bereitstellung klarer Anweisungen umfassen.

In praktischer Hinsicht analysieren technische Schriftsteller das Publikum, sammeln relevante Informationen, organisieren den Inhalt logisch und kommunizieren ihn unter Verwendung angemessener Sprache und Formate. Sie bemühen sich, technische Inhalte für Leser verständlich und nutzbar zu machen, die möglicherweise keine technische Vorbildung haben.

Insgesamt spielt das technische Schreiben eine entscheidende Rolle bei der Förderung der Kommunikation und des Wissenstransfers innerhalb von Unternehmen, Branchen und Sektoren und stellt sicher, dass Informationen genau und umfassend vermittelt werden.

Es gibt 5 Komponenten des technischen Schreibens

Die Komponenten des technischen Schreibens sind grundlegend für die Erstellung effektiver Kommunikationsmaterialien. Sie umfassen:

1. Zweck: Die klare Definition des Zwecks des Dokuments und dessen Ziele.

2. Zielgruppe: Die Identifizierung der beabsichtigten Leserschaft und das Verständnis ihres Kenntnisstands und ihrer Bedürfnisse.

3. Inhalt: Die Bereitstellung genauer und relevanter Informationen, um den Zweck des Dokuments zu erfüllen und die Anforderungen des Publikums zu erfüllen.

4. Organisation: Die logische und zusammenhängende Strukturierung des Inhalts, um das Verständnis und die Navigation zu erleichtern.

5. Stil: Die Verwendung angemessener Sprache, Tonlage und Formatkonventionen, um die Lesbarkeit zu verbessern und Informationen effektiv zu vermitteln.

Es gibt 7 Arten von technischem Schreiben

Was die Arten des technischen Schreibens betrifft, umfassen sie eine Reihe von Dokumenten, die auf verschiedene Zwecke und Zielgruppen zugeschnitten sind. Dazu gehören:

1. Benutzerhandbücher: Anleitungen und Anleitungen zur Verwendung von Produkten oder Systemen.

2. Standardbetriebsanweisungen (SOPs): Detaillierte Anweisungen zur Durchführung bestimmter Aufgaben oder Operationen.

3. Technische Berichte: Dokumente, die Ergebnisse, Analysen und Schlussfolgerungen aus Forschung oder Untersuchungen darstellen.

4. White Papers: Autoritative Berichte, die komplexe Probleme ansprechen, oft für geschäftliche oder technische Zwecke verwendet.

5. Vorschläge: Formale Dokumente, die Lösungen, Projekte oder Zusammenarbeiten vorschlagen.

6. Online-Hilfedokumentation: Digitale Anleitungen und Ressourcen, um Benutzern bei Softwareanwendungen oder Websites zu helfen.

7. Wissenschaftliche Artikel: Arbeiten, die Forschungsergebnisse und Analysen innerhalb der wissenschaftlichen Gemeinschaft präsentieren.

Ein Beispiel für technisches Schreiben könnte ein Benutzerhandbuch für ein Smartphone sein, das Schritt-für-Schritt-Anleitungen zur Einrichtung, Bedienung und Fehlerbehebung des Geräts bietet. Solche Dokumente zielen darauf ab, Benutzer mit dem Wissen auszustatten, das sie benötigen, um das Produkt effektiv und effizient zu nutzen.

Technische Redakteure sind mit mehreren Nachteilen konfrontiert. Erstens kann die Verfolgung von Änderungen in rein textbasierten Programmen schwierig sein, da ihnen integrierte Versionskontrollfunktionen fehlen. Zweitens gibt es keine automatisierten Tests, mit denen Dokumentationsfehler frühzeitig erkannt und behoben werden können. Drittens kann die Organisation und Wiederverwendung von Inhalten in rein textbasierten Umgebungen umständlich sein und zu Inkonsistenzen führen. Viertens ist die Bereitstellung von Updates ohne integrierte Prozesse zur automatischen Veröffentlichung von Änderungen langsamer. Und schließlich ist es nicht einfach, Automatisierung und Effizienz in den Veröffentlichungsprozessen zu erreichen.

Die Lösung für technisches Schreiben ist "Docs as Code".

"Docs as Code" repräsentiert die optimale Methode zur Erstellung technischer Dokumentationen. Die Dokumente werden innerhalb einer Anwendung kodiert, was es den Benutzern ermöglicht, den Inhalt zu nutzen, zu formatieren, zu pflegen und über verschiedene Geräte und Medien zu verteilen.

"Docs as Code" ist eine Methodik, die die Dokumentation als integralen Bestandteil des Softwareentwicklungsprozesses betrachtet, anstatt sie als nachträgliche Überlegung oder separate Aufgabe zu behandeln. Sie wendet Prinzipien und Praktiken aus der Softwareentwicklung auf die Erstellung, Überprüfung und Wartung von Dokumentationen an.

Hier sind einige wichtige Aspekte und Vorteile des Ansatzes "docs as code":

1. Versionskontrolle: Ähnlich wie Quellcode wird die Dokumentation in Versionskontrollsystemen wie Git gespeichert. Dies ermöglicht das Nachverfolgen von Änderungen, die Zusammenarbeit zwischen Teammitgliedern und das Zurücksetzen auf frühere Versionen bei Bedarf.

2. Textbasiertes Format: Dokumentation wird häufig in reinem Text oder leichtgewichtigen Markup-Sprachen wie AsciiDoc, Markdown oder reStructuredText verfasst. Diese Formate sind einfach zu lesen und zu schreiben und können mithilfe von Tools wie Sphinx, MkDocs oder GitBook in verschiedene Ausgabeformate wie HTML, PDF oder EPUB konvertiert werden.

3. Automatisierung: Es können kontinuierliche Integrations- (CI) und kontinuierliche Bereitstellungs- (CD) Pipelines eingerichtet werden, um die Dokumentation automatisch zu erstellen und bereitzustellen, wenn Änderungen am Dokumentations-Repository oder am Code vorgenommen werden. Dies stellt sicher, dass die Dokumentation immer aktuell ist und mit der Software synchronisiert bleibt.

4. Zusammenarbeit: Da die Dokumentation neben dem Code im selben Repository gespeichert ist, können Entwickler und technische Autoren enger zusammenarbeiten. Sie können die Arbeit des anderen überprüfen, Feedback geben und gemeinsam Änderungen vornehmen, was die Kommunikation und das gemeinsame Verständnis fördert.

5. Wiederverwendbarkeit: Dokumentationskomponenten wie Code-Schnipsel, Konfigurationsbeispiele und Fehlerbehebungshandbücher können in verschiedenen Projekten oder Modulen wiederverwendet werden. Dies reduziert die Duplizierung von Aufwand und gewährleistet Konsistenz im Dokumentationsstil und -inhalt.

6. Testen: Ähnlich wie bei Software kann auch die Dokumentation getestet werden, um Genauigkeit, Vollständigkeit und Lesbarkeit sicherzustellen. Automatisierte Tests können geschrieben werden, um Links, Codebeispiele und andere Aspekte der Dokumentation zu validieren.

7. Feedback-Schleife: Indem die Dokumentation als Code behandelt wird, sind Entwickler eher aktiv daran beteiligt. Sie können Verbesserungen vorschlagen, Fehler melden oder Klarstellungen direkt über die gleichen Kanäle einfordern, die sie für Codebeiträge wie Pull Requests und Issue Tracker nutzen.

8. Agilität: Die Einführung eines "Docs as Code"-Ansatzes ermöglicht es Teams, schnell auf Änderungen in der Software oder Rückmeldungen der Benutzer zu reagieren. Es fördert eine agile Denkweise, bei der die Dokumentation parallel zur Codebasis weiterentwickelt wird.

Zusammenfassend fördert "Docs as Code" eine Kultur, in der die Dokumentation als integraler Bestandteil des Softwareentwicklungsprozesses geschätzt wird. Durch Anwendung von Prinzipien der Versionskontrolle, Automatisierung, Zusammenarbeit und Testen auf die Dokumentation können Teams hochwertige Dokumentationen erstellen und pflegen, die die Benutzererfahrung und die Produktivität der Entwickler insgesamt verbessern.

Technisches Schreiben auf Mac, iPad & iPhone

Testphase starten

Kann ich "Docs as Code" für andere technische Schreibarbeiten verwenden?

Ja, die Grundsätze und Praktiken von "Docs as Code" können auf verschiedene Formen des technischen Schreibens jenseits der traditionellen Software-Dokumentation angewendet werden. Hier sind einige Beispiele:

1. API-Dokumentation: Wie bei der Software-Dokumentation profitiert auch die API-Dokumentation von Versionskontrolle, Zusammenarbeit und Automatisierung. Die Speicherung der API-Dokumentation neben dem Code gewährleistet, dass sie bei jeder Software-Veröffentlichung genau und aktuell bleibt.

2. Systemdokumentation: Dokumentation für Systeme, Architekturen und Infrastrukturen kann ebenfalls als Code behandelt werden. Dazu gehören Netzwerkdiagramme, Systemkonfigurationen, Bereitstellungsverfahren und operationale Handbücher. Die Speicherung dieser Dokumentation in Versionskontrolle ermöglicht es Teams, Änderungen nachzuverfolgen und Konsistenz über Umgebungen hinweg sicherzustellen.

3. Technische Anleitungen und Tutorials: Anleitungen und Tutorials, die erklären, wie man Software-Tools, Frameworks oder Bibliotheken verwendet, profitieren von der "Docs as Code"-Methode. Durch die Speicherung in einem textbasierten Format und die Nutzung von Automatisierungstools können Autoren schnell Anleitungen aktualisieren und veröffentlichen, um Änderungen im technologischen Umfeld widerzuspiegeln.

4. Schulungsmaterialien: Schulungsmaterialien zur Einarbeitung neuer Teammitglieder oder zur Schulung von Benutzern zur Verwendung eines Produkts können als Code verwaltet werden. Indem Schulungsmaterialien als Teil des Dokumentations-Ökosystems betrachtet werden, können Organisationen eine einzige Informationsquelle für alle Schulungsinhalte pflegen und sicherstellen, dass diese relevant und zugänglich bleiben.

5. Compliance- und Regulierungsdokumentation: Dokumentation zu Compliance-Anforderungen, wie Sicherheitsrichtlinien, Datenschutzbestimmungen und Branchenstandards, kann mit dem "Docs as Code"-Ansatz verwaltet werden. Die Speicherung der Compliance-Dokumentation in Versionskontrolle hilft Organisationen, Änderungen nachzuverfolgen und die Einhaltung regulatorischer Anforderungen zu demonstrieren.

6. Interne Wissensdatenbanken: Interne Wissensdatenbanken, Wikis und Dokumentations-Repositories profitieren davon, als Code verwaltet zu werden. Durch die Speicherung von Wissensdatenbankartikeln und internen Dokumentationen neben dem Code können Organisationen sicherstellen, dass das Teamwissen erfasst und für Teammitglieder zugänglich ist, unabhängig von Fluktuationen oder organisatorischen Veränderungen.

7. Konfigurationsmanagement: Dokumentation zu Systemkonfigurationen, Umgebungseinrichtungen und Infrastruktur-Bereitstellungen kann als Code mit Tools wie Terraform, Ansible oder Puppet verwaltet werden. Die Speicherung der Konfigurationsdokumentation neben dem Infrastrukturcode stellt sicher, dass Änderungen konsistent erfasst, überprüft und dokumentiert werden.

Zusammenfassend lässt sich sagen, dass der "Docs as Code"-Ansatz über die Software-Dokumentation hinaus verschiedene Formen des technischen Schreibens und Wissensmanagements umfasst. Durch die Anwendung von Versionskontrolle, Automatisierung, Zusammenarbeit und Testen auf technische Dokumentation können Organisationen die Qualität, Wartbarkeit und Zugänglichkeit der Dokumentation in verschiedenen Bereichen und Disziplinen verbessern.

Docs as Code im Vergleich zu Microsoft Word

Arbeiten mit Office-Dateiformaten wie Microsoft Word ermöglicht es Benutzern, Dokumente lokal zu bearbeiten, auszudrucken und über E-Mail oder Dateispeicher mit anderen Autoren zu teilen. Abhängig von der Infrastruktur können Dokumente über SharePoint oder OneDrive gemeinsam bearbeitet werden. Es wird jedoch herausfordernd, insbesondere wenn verschiedene bearbeitete Dokumentenversionen über organisatorische Grenzen hinweg fusioniert werden müssen. Eine Alternative zu diesem Ansatz ist die Verwendung von Wikis, in denen Autoren gemeinsam an Dokumenten arbeiten. Der Prozess, Inhalte in druckfertige Dokumente mit ansprechenden Layouts zu formatieren, ist oft umständlich. Beide Ansätze stoßen an ihre Grenzen, wenn Autoren gleichzeitig verschiedene Versionen von Dokumenten pflegen müssen, beispielsweise für unterschiedliche Veröffentlichungen oder Produkte.

Für Neueinsteiger in der technischen Dokumentation haben sich im Laufe der Zeit mehrere Plattformen entwickelt. Markdown, AsciiDoc und reStructuredText sind nur einige Beispiele. Sie bieten mehrere Vorteile, da sie in jedem Texteditor lesbar und bearbeitbar sind. Durch Konvertierung können Inhalte aus den Quelltexten in andere Formate wie hochwertige HTML- oder PDF-Dokumente umgewandelt werden. Sie enthalten verschiedene Komponenten wie Überschriften, Querverweise und Inhaltsverzeichnisse. Im Gegensatz zur herkömmlichen Textverarbeitung erfordert der Übergang zu einem solchen Format einen anderen Ansatz für das Dokumentenmanagement. Ein praktisches Beispiel finden Sie in unserem Blogbeitrag zur Erstellung eines Benutzerhandbuchs in AsciiDoc.

Sprechen wir über AsciiDoc

AsciiDoc als Sprache und Implementierung begann vor über 15 Jahren mit Stuart Rackham als Betreuer. Es eignet sich hervorragend für technisches Schreiben in "Docs as Code", da es eine klare, strukturierte und leicht verständliche Syntax bietet, die besonders gut für die Dokumentation von Softwareprojekten geeignet ist. Mit seiner einfachen Markdown-ähnlichen Formatierung können Entwickler und technische Autoren problemlos komplexe Konzepte, Codebeispiele, Diagramme und Anleitungen verfassen, während sie gleichzeitig eine klare Trennung von Inhalt und Formatierung beibehalten.

AsciiDoc unterstützt auch die Integration von Versionskontrollsystemen wie Git, was eine nahtlose Zusammenarbeit und Versionsverwaltung ermöglicht. Darüber hinaus bietet es eine Vielzahl von Erweiterungen und Integrationen für die automatisierte Erzeugung von Dokumenten in verschiedenen Formaten wie HTML, PDF und ePub. Insgesamt bietet AsciiDoc eine flexible und leistungsfähige Plattform für die Erstellung und Verwaltung von technischen Dokumentationen im Rahmen von Docs as Code.

AsciiDoc mit adoc Studio

Der Nachteil von AsciiDoc besteht darin, dass Sie, wenn Sie kein technikversierter Mensch sind und sich einfach auf das Schreiben konzentrieren möchten, dennoch viel Zeit in einer Code-Umgebung verbringen. Es gibt jedoch eine großartige Lösung, um dieses Problem zu beheben. Sie ermöglicht es Ihnen, Ihre technischen Dokumente mit AsciiDoc auf Ihren Apple-Geräten zu verfassen, egal ob es sich um einen Mac, ein iPad oder sogar ein iPhone handelt.

Sie können alle Attribute aus der AsciiDoc-Syntax anwenden und gleichzeitig das Ergebnis in Echtzeit sehen. Anschließend können Sie das Erscheinungsbild des Dokuments gestalten und den Inhalt in verschiedenen Formaten exportieren. Schauen Sie sich unbedingt adoc Studio an, wenn Sie ernsthaft an technischer Dokumentation mit der AsciiDoc-Sprache interessiert sind.