Dokumentation ist ein wesentlicher Bestandteil des Softwareentwicklungszyklus. Es erläutert die Verwendung der Software und kann Benutzerhandbücher, API-Referenzen, Installationsanweisungen und Versionshinweise enthalten.
Die Automatisierung Ihrer Dokumentation ist der neueste Trend, da sie helfen kann, Zeit zu sparen, Fehler zu reduzieren und Konsistenz zu gewährleisten. Halten Sie Ihre Dokumentation auf dem neuesten Stand und für alle Beteiligten zugänglich, was die Zusammenarbeit und kontinuierliche Verbesserung erleichtert.
Docs as Code ist ein Ansatz zur Dokumentationsautomatisierung, der technische Dokumentation als Code behandelt.
Was ist Docs als Code?
Docs as Code ist eine Softwareentwicklungsphilosophie, die technische Dokumentation als eine Form von Code betrachtet. Es schlägt vor, dass Sie die Dokumentation mit der gleichen Strenge und dem gleichen Prozess wie Softwarecode behandeln sollten.
Die Idee hinter docs as code besteht darin, die Dokumentation als erstklassiges Artefakt des Entwicklungsprozesses zu behandeln und sie in den Softwarelebenszyklus zu integrieren. Dies bedeutet, dass die Dokumentation als integraler Bestandteil der Codebasis behandelt wird. Es bedeutet, die gleiche Versionskontrolle, kontinuierliche Integration und die gleichen Testprozesse darauf anzuwenden, die Sie auf den Code selbst anwenden.
In einer typischen Einrichtung von Dokumenten als Code schreiben Sie die Dokumentation in Nur-Text-Dateien, normalerweise in eine leichtgewichtige Auszeichnungssprache wie Markdown, HTML oder reStructuredText. Anschließend speichern Sie ihn im selben Repository wie den Quellcode. Dies macht es einfach, Änderungen an Software und Dokumentation zu verwalten und nachzuverfolgen. Es hilft auch sicherzustellen, dass die Dokumentation mit der neuesten Version des Codes auf dem neuesten Stand ist.
Warum Sie Dokumente als Code verwenden sollten
Vor Dokumenten als Code wurde die Dokumentation oft getrennt vom Code behandelt, der mit unterschiedlichen Tools und Prozessen erstellt wurde. Dieser lockerere Ansatz führte oft zu veralteter Dokumentation und Inkonsistenzen mit dem Code. Sie können mehrere Vorteile nutzen, indem Sie den Docs-as-Code-Ansatz übernehmen.
Verbesserte Zusammenarbeit
Docs as Code ermöglicht die Zusammenarbeit zwischen Entwicklern, technischen Redakteuren und anderen Beteiligten im Entwicklungsprozess. Da das Code-Repository die Dokumentation enthält, ist es für verschiedene Parteien einfach, Beiträge zu leisten und Änderungen vorzunehmen. Dadurch wird sichergestellt, dass die Dokumentation korrekt, aktuell und umfassend ist.
Ein kooperativer Dokumentationsansatz trägt dazu bei sicherzustellen, dass alle relevanten Informationen enthalten sind und das Softwaresystem, wie es von allen Parteien interpretiert wird, genau widerspiegelt.
Prozessautomatisierung und Zugänglichkeit
Ein weiterer Vorteil von Docs as Code besteht darin, dass es automatisierten Tools ermöglicht, Dokumentationen zu generieren und zu veröffentlichen. Ein Build-System kann automatisch HTML- oder PDF-Versionen der Dokumentation aus Nur-Text-Dateien zur Veröffentlichung auf einer Website oder einem internen Dokumentationsportal generieren. Dadurch wird die Dokumentation für mehr Stakeholder zugänglich.
Durch die Automatisierung des Prozesses zum Generieren und Veröffentlichen von Dokumentation trägt Docs as Code dazu bei, den Zeit- und Arbeitsaufwand für die Pflege und Veröffentlichung der Dokumentation zu reduzieren. Es ermöglicht Entwicklungsteams, sich auf die Verbesserung der Software zu konzentrieren.
Versionskontrolle
Das Speichern der Dokumentation im selben Code-Repository wie die Software erleichtert die Verwaltung und Nachverfolgung von Änderungen an beiden.
Sie können verwenden Versionskontrollsysteme wie Git, um Änderungen an der Dokumentation nachzuverfolgen und bei Bedarf zu früheren Versionen zurückzukehren. Dadurch wird sichergestellt, dass die Dokumentation korrekt und aktuell ist, und Sie können Änderungen nachverfolgen und prüfen.
Der typische Docs-as-Code-Workflow
Der typische Docs-as-Code-Workflow umfasst Schreiben, Versionskontrolle, Erstellung und Hosting:
Der Schreibprozess
Der Schreibprozess ist die erste Phase eines typischen Docs-as-Code-Workflows. Am meisten Technische Redakteure und Dokumentationsingenieure verwenden einfaches MarkDown, AsciiDoc oder HTML. Sie schreiben die Dokumentation mit Tools wie GitBook und Redocly, die einen reibungslosen Ablauf gewährleisten.
Versionskontrolle für Dokumentation
Die Dokumentation entwickelt sich mit der Entwicklung des Codes weiter. Sie benötigen ein ausgeklügeltes Versionskontrollsystem wie Git, Plastic SCM oder Subversion, um Änderungen an der Dokumentation für eine einfachere Zusammenarbeit und Versionsverfolgung nachzuverfolgen.
Der Dokumentationserstellungsprozess
Der Erstellungsprozess umfasst die Verarbeitung und Kompilierung der Dokumentation in ihre Lieferformate. Dies können HTML, PDF, EPUB oder andere sein. Der Dokumentationsprozess wird normalerweise durch die Verwendung von Static-Site-Generatoren wie Hugo und Jekyll erleichtert.
Hosten und Verteilen von Dokumentation
Der Hosting- oder Verteilungsprozess ist normalerweise der letzte Schritt der Dokumentation als Codierungsprozess. Dieser Prozess stellt sicher, dass die Dokumentation an den Endbenutzer geliefert wird und allen Beteiligten zur Verfügung steht. Sie können GitHub- oder GitLab-Seiten oder ein benutzerdefiniertes Portal verwenden, um Ihre Dokumentation im Web zu verteilen.
Sie können die Go- und Java-Dokumentation mit GoDoc und JavaDoc automatisieren
Die Docs-as-Code-Philosophie revolutioniert das Schreiben und Verwalten technischer Dokumentation.
Viele Programmiersprachen, einschließlich Go und Java, bieten Tools zum Automatisieren der Dokumentation mithilfe von Codekommentaren. Go stellt das Godoc-Tool bereit, und Java stellt JavaDoc bereit.
