18 Software-Dokumentations-Tools, die die harte Arbeit für Sie erledigen

🟢 Bonusmaterial: Git Workflow Checkliste zur Vereinfachung & Rationalisierung der Versionsverwaltung

Ohne Dokumentation ist Software nur eine Black Box. Und Blackboxen sind nicht annähernd so nützlich, wie sie sein könnten, weil ihr Innenleben vor denjenigen verborgen ist, die sie in der Öffentlichkeit benötigen.

Software-Dokumentation macht Ihre Software zu einem Glaskasten, indem sie den Benutzern und Entwicklern erklärt, wie sie funktioniert oder verwendet wird.

Sie haben wahrscheinlich schon einmal eine Dokumentation gesehen, aber wenn Sie eine Auffrischung brauchen, hier ist ein Beispiel für die API von Slack:

Wie Sie sehen können, erklärt Slack alles über seine API in quälender Ausführlichkeit. Alle verwandten Seiten sind verlinkt, es gibt eine Seitenleiste mit leicht zugänglichen Themen und Screenshots von dem, was den Benutzer erwartet.

Um dies genauer zu erklären, werden wir die folgenden Themen in diesem Process Street Beitrag behandeln:

• Was ist Software-Dokumentation?
• Hosting-Optionen für Software-Dokumentation
• Schreibwerkzeuge für Software-Dokumentation
• Abschließende Worte zur Software-Dokumentation

Lassen Sie uns beginnen.

Was ist Software-Dokumentation?

„Dokumentation in der Software-Entwicklung ist der Überbegriff, der alle schriftlichen Dokumente und Materialien umfasst, die sich mit der Entwicklung und Nutzung eines Software-Produkts befassen“ – Prototype.io, Software Documentation Types and Best Practices

Jede Software sollte eine Form von Dokumentation haben, die im Detail erklärt, was das Produkt ist, wie es funktioniert und warum es so funktioniert.

„Wenn es nicht dokumentiert ist, existiert es nicht“ – Sitepoint, A Guide to Writing Your First Software Documentation

Als Entwickler ist es Ihr Hauptziel, den besten Code zu schreiben, den Sie können. Sie wollen, dass Ihr Code der beste seiner Art ist, leicht zu lesen und zu benutzen, und Sie wollen, dass das Ergebnis großartige Dinge sind. Richtig?

Aber ohne zu dokumentieren, was Sie getan haben und warum Sie es getan haben:

• Niemand außer Ihnen kann Ihren Code benutzen

Ohne Dokumentation wird niemand verstehen, was Sie getan haben und warum Sie es getan haben. Es wird unglaublich schwierig, ja fast unmöglich sein, dass jemand anderes Ihren Code aufgreift und daran arbeitet. Sie könnten ihn sogar verwerfen und von vorne beginnen, denn das wäre in manchen Fällen schneller, als zu versuchen, herauszufinden, was Sie getan haben und warum.

• Sie können ihn nicht aktualisieren oder verbessern

Können Sie sich daran erinnern, was Sie am Samstag vor drei Monaten zum Abendessen gegessen haben? Wenn Sie nicht gerade ein absolutes Gewohnheitstier sind, können Sie es wahrscheinlich nicht. Man kann also sagen, dass Sie sich wahrscheinlich auch nicht mehr an den Code erinnern, den Sie zwei, drei, vier Monate später geschrieben haben. Wenn Sie sich nicht an die Gründe für Ihre Code-Entscheidungen erinnern können, wird es Ihnen schwer fallen, ihn zu aktualisieren oder zu verbessern.

Dessen ungeachtet ist die Software-Dokumentation oft eine Aufgabe, die übereilt, schlecht erledigt, zurückgestellt oder ganz vergessen wird.

Bevor wir uns darüber unterhalten, welche Werkzeuge Sie zum Schreiben von Software-Dokumentation verwenden können, müssen wir uns überlegen, wie wir sicherstellen können, dass die Aufgabe überhaupt erledigt wird.

Hier kann Process Street helfen.

Process Street ist eine Software für das Geschäftsprozessmanagement (BPM), mit der sich Prozesse erstellen, verwalten und verfolgen lassen.

Mehr darüber, was Process Street ist, später, für jetzt, lassen Sie mich Ihnen zeigen, wie Sie es als ein Werkzeug verwenden können, das Ihnen hilft, Software-Dokumentation in jedes Software-Entwicklungsprojekt, an dem Sie arbeiten, einzubauen.

Unten sehen Sie ein Beispiel für eine vorgefertigte Vorlage für den Softwarebereitstellungsprozess. Diese Vorlage wurde erstellt, um Softwareingenieuren und Programmierern zu helfen, ihre Software bestmöglich einzusetzen.

Klicken Sie hier, um auf den Software Deployment Process zuzugreifen!

Um diese Vorlage zu erhalten, melden Sie sich entweder an und fügen Sie sie zu Ihrem Dashboard hinzu oder melden Sie sich für eine kostenlose Testversion an.

Diese Vorlage ist ein perfektes Beispiel für einen Prozess, dem Sie jedes Mal folgen können, wenn Sie einen neuen oder aktualisierten Code bereitstellen möchten.

Sie enthält klare Schritte, die Sie durch den gesamten Bereitstellungsprozess führen, von der Einrichtung einer Staging-Umgebung bis zur Live-Schaltung Ihrer Änderungen. Diese Schritte stellen sicher, dass nichts übersehen wird und dass der gesamte Prozess jedes Mal reibungslos abläuft.

Wir haben diese Vorlage als Leitfaden entwickelt, der Ihnen helfen soll, einen für Sie geeigneten Bereitstellungsprozess zu entwickeln. Jedes Unternehmen ist anders, jedes Softwareprojekt ist anders, und jeder Bereitstellungsprozess ist anders.

Sie können diesen Prozess bearbeiten und die Aufgaben hinzufügen, die für Sie, Ihr Unternehmen und Ihr Projekt relevant sind.

Womit ich wieder bei der Software-Dokumentation wäre: Sie könnten die „Software-Dokumentation“ als Aufgabe hinzufügen. Auf diese Weise wird jeder, der den Prozess der Softwareeinführung durchläuft, daran erinnert und ermutigt, dies als Teil des Prozesses zu erledigen.

Ich habe noch ein paar weitere vorgefertigte Prozessvorlagen, die Ihnen von Nutzen sein könnten, und die ich am Ende dieses Beitrags einfüge.

Bevor wir dazu kommen, lassen Sie uns einen Blick darauf werfen, wo Sie Ihre Software-Dokumentation speichern können.

Optionen für das Hosting von Software-Dokumentation

Es ist nicht gut, nur einen Haufen Textdateien auf Ihrem Computer zu haben. Sie müssen für Entwickler und Benutzer zugänglich sein, was Sie höchstwahrscheinlich tun werden, indem Sie die Dokumente im Internet hosten, da es sich nicht um die 1980er Jahre handelt.

Process Street (für den internen Gebrauch)

Für die Ausbildung neuer Entwickler und um Ihre Dokumentation an einem Ort zu halten, ist Process Street eine solide Wahl für Software-Dokumentation.

Zunächst könnten Sie einen Prozess für das Schreiben Ihrer Dokumentation erstellen, um sicherzustellen, dass Sie alle richtigen Details erfassen und sie so nützlich wie möglich machen.

Mit den folgenden benutzerfreundlichen Funktionen können Sie dann Ihre Dokumentation an einem einzigen Ort verfassen und speichern:

• Bild-Widgets
• Text-Widgets
• Video-Widgets
• Datei-Widgets
• Teilaufgaben
• E-Mail-Widgets
• Embed-Widgets

Wenn Sie Ihre Dokumentation in Process Street speichern, kann jeder im Unternehmen darauf zugreifen. Sie können sie mit anderen teilen, zur Genehmigung senden, Erinnerungen zur Überprüfung festlegen und sie einfach aktualisieren.

Testen Sie es:

Was dokumentiert werden kann, kann auch in Process Street dokumentiert werden.

Melde dich hier für eine kostenlose Testversion an und probiere es aus.

Read The Docs

Es ist bemerkenswert, dass Read The Docs kostenlos ist, wenn man sieht, was es alles kann. Ähnlich wie bei GitHub können Sie so viel Open-Source-Material erstellen, wie Sie wollen, das auf der Website offen indiziert wird, aber es wird Sie etwas kosten, wenn Sie die Dokumente privat und intern für Ihr Unternehmen machen wollen. Für unsere Zwecke werden Sie wahrscheinlich damit zufrieden sein, dass die Dokumente für die Benutzer im Web verfügbar sind.

Der Grund, warum Read The Docs so gut ist, ist, dass Sie die Dokumentation mühelos aus jedem Versionskontrollsystem importieren können, einschließlich Git, Mercurial, Subversion und Bazaar. Es unterstützt auch Webhooks, so dass die Dokumente automatisch erstellt werden, wenn Sie Code übertragen.

Schauen Sie sich die Anleitung „Erste Schritte“ an, um ein Gefühl dafür zu bekommen, wie es funktioniert und wie sich Ihre Dokumente verhalten, wenn sie dort gehostet werden.

GitHub (& GitHub Pages)

Wenn Sie GitHub für die Versionskontrolle Ihrer Software verwenden, haben Sie zumindest eine README.MD-Datei im Repository. Wenn Sie GitHub für die Dokumentation Ihrer Software verwenden möchten, wie es Millionen andere in der Vergangenheit getan haben, füllen Sie diese README-Datei einfach mit Markdown aus.

Ein großartiges Beispiel ist das t-Repository von sferik, das hier als Screenshot zu sehen ist:

Wenn du mehr als nur ein Blatt formatierten Textes haben willst, kannst du das Pages-Tool von GitHub nutzen (du bekommst eine kostenlose Webseite + Hosting mit jedem GitHub-Account, und du kannst sogar eine benutzerdefinierte Domain dazu leiten). Pages hat sogar großartig aussehende Standardthemen, die deine Dokumentation professionell aussehen lassen.

Oben ist die atom.io-Dokumentation für Electron, die auf GitHub gehostet wird. Das ist eine kluge Wahl, weil sie automatisch mit der Versionskontrolle von GitHub zusammenarbeitet, genau wie der Rest Ihrer Software. Das Repository der Website finden Sie hier.

Dropbox Paper (für den internen Gebrauch)

Für den internen Gebrauch von Software-Dokumentation ist Dropbox Paper eine ausgezeichnete Wahl. Wie sein Vorgänger Hackpad können Sie damit ein privates Wiki für Mitarbeiter erstellen. Sie können Dokumente miteinander verknüpfen, Codeblöcke, Bilder und Seitensprünge einfügen, ganz so, wie Sie es von einem Dokumentationswerkzeug erwarten.

Wie Sie den Kommentaren auf der rechten Seite entnehmen können, können Sie damit auch Genehmigungsprozesse durchlaufen und gemeinsam an der Erstellung der Dokumentation arbeiten. Insgesamt ist es ein großartiges Tool für die interne Entwicklung und Erstellung von Dokumentationen, vielleicht mit der Absicht, sie später zu veröffentlichen oder sie einfach für den internen Gebrauch zu behalten.

Atlassian REST API Browser (für die Verwendung von APIs)

Atlassians REST API Browser (RAB) ist standardmäßig in JIRA Server, Confluence Server und Stash-Instanzen enthalten. Er dient zum Auffinden von APIs, die in JIRA/Confluence-Umgebungen verwendet werden können, und ist auch ein Ort, an dem Sie Ihre Dokumentation hosten können.

Dokumentieren Sie Ihre API mit diesem Tool, um Ihrer JIRA/Confluence-kompatiblen API mehr Aufmerksamkeit zu verschaffen. Die Dokumentation von Atlassian dazu finden Sie hier.

Tettra (für den internen Gebrauch)

Tettra ist eine Art Wissensdatenbank, mit der Sie Ihre Entwicklung oder irgendetwas anderes dokumentieren können.

Wir verwenden Tettra intern bei Process Street für eine Reihe von Anwendungsfällen. Im Alltag verwende ich Tettra, um alle meine Prozesse an einem einzigen Ort zu dokumentieren, damit ich nie vergesse, wie einer mit dem anderen zusammenhängt oder wie die verschiedenen Automatisierungen, die wir aufgebaut haben, eingerichtet wurden.

Tettra ist großartig, wenn man eine Art Bibliothek erstellen will. Das bedeutet, dass es sich hervorragend für Softwaredokumentation oder auch nur als internes Wiki für Ihr Unternehmen eignet.

Da Tettra speziell für das Wissensmanagement entwickelt wurde, verfügt es auch über eine Reihe anderer unterstützender Funktionen. Zum Beispiel kann es Vorschläge machen, welche zusätzlichen Inhalte oder Abschnitte Sie hinzufügen sollten, um ein vollständigeres Bild Ihrer Organisation zu erhalten und wie die Dinge zusammenpassen.

Sie können hier ein kleines Video sehen, wie ein Entwicklungsteam Tettra verwenden könnte: How Product & Engineering Teams Use Tettra.

Oder Sie können hier nachlesen, wie wir Tettra zusammen mit Process Street verwenden: Workflows und Checklisten automatisieren: Process Street Case Study.

Schauen Sie mal rein!

Apiary (for API use)

Apiary ist nicht nur ein Ort, an dem Bienen leben, sondern auch ein spezieller Host für API-Dokumentation. Schreiben Sie in Markdown, fügen Sie Mock-API-Aufrufe hinzu, und Apiary fasst das in etwas zusammen, das Sie unten sehen:

Jeder kann die API testen, ohne in die App gehen oder einen Aufruf programmieren zu müssen, was es zu einer sehr zugänglichen Möglichkeit macht, Ihre API zu teilen, sie ausführlich zu dokumentieren und damit zu prahlen, was sie kann.

Wir haben besprochen, wo Sie Ihre Softwaredokumentation aufbewahren sollten, jetzt ist es an der Zeit, sich anzusehen, wie man sie schreibt.

Werkzeuge zum Schreiben von Software-Dokumentation

Software-Dokumentation wird oft in Markdown geschrieben, um Hyperlinks und Formatierungen zu ermöglichen, während sie gleichzeitig als reiner Text vorliegt, damit sie neben den Codedateien in der Versionskontrolle bestehen kann. Das bedeutet, dass viele meiner bevorzugten Schreibwerkzeuge einfache Markdown-Editoren sind, mit denen das Schreiben Spaß macht. Darüber hinaus gibt es auch ein paar sehr effektive Lösungen, die nicht auf Markdown basieren.

MarkdownPad (Windows)

MarkdownPad ist der beliebteste Markdown-Editor für Windows, den es in einer kostenlosen und einer Premium-Version gibt – beide mit einer Menge toller Funktionen. Er ist optimiert für Blogposts, Websites, Artikel, READMEs und natürlich Software-Dokumentation.

Sie können MarkdownPad kostenlos erhalten oder die Premium-Version für 14,95 $ erwerben.

iA Writer (Mac)

iA Writer ist ein einfacher, schöner Markdown-Editor mit einer Bibliotheksfunktion, mit der Sie leicht auf andere Dokumente in der Seitenleiste verweisen können. Es fehlen zwar interne Links zwischen den Dokumenten, wie man sie bei Software-Dokumenten erwarten würde, aber die kann man ja immer noch nachreichen, wenn das Dokument in seiner endgültigen Form vorliegt (d.h. wenn es auf einer Website im Internet landen soll).

Wenn Sie Ihre gesamte Dokumentation in einer einzigen, aufgebrochenen Seite schreiben, können Sie Seitensprunganker verwenden, um den Benutzern die Navigation zu erleichtern.

iA Writer kostet 9,99 $ im Mac App Store.

ProProfs Knowledge Base

Profs Knowledge Base ist ein fantastisches kleines Tool für alle Phasen der Dokumentenerstellung: vom Schreiben und Bearbeiten bis hin zum Anpassen, Einrichten von Arbeitsabläufen und Veröffentlichen. Sie können Multimedia hinzufügen, vorhandene Inhalte aus Word-Dokumenten, PDF oder PPTs importieren, mehrere Versionen des Dokuments speichern und bei Bedarf wiederherstellen.

Aber die wahre Schönheit dieses Tools liegt in seiner Benutzerfreundlichkeit. Jeder und jede kann es zur Erstellung von Software-Dokumentation verwenden. Egal, ob Sie schon seit Jahren Software dokumentieren oder erst vor kurzem damit angefangen haben, es ist ein unglaublich einfaches und leicht zu bedienendes Werkzeug.

ProProfs ist kostenlos, oder Sie können auf das Premium-Paket upgraden, das 112 $ pro Monat kostet.

SimpleMDE (Browser)

Während Sie technisch gesehen Markdown in jedem Texteditor schreiben können, weil es eine Möglichkeit ist, einfachen Text zu formatieren, und nicht unbedingt ein „Werkzeug“, wird es Sie nicht überraschen, dass es auch in Ihrem Browser möglich ist! SimpleMDE ist sowohl ein funktionaler Markdown-Editor, der auf JavaScript basiert, als auch ein Open-Source-Projekt, von dem Sie lernen und das Sie bei Bedarf für Ihren eigenen Gebrauch anpassen können.

SimpleMDE ist 100% kostenlos! Holen Sie sich den Quellcode auf GitHub hier.

reStructuredText-Editoren

Markdown ist eine der beiden am häufigsten verwendeten Sprachen für das Schreiben von Software-Dokumentation, aber es gibt noch eine andere, die wir bisher nicht betrachtet haben, und das ist reStructuredText. Sie ist Markdown sehr ähnlich, aber es lohnt sich, sie für die Zwecke der Software-Dokumentation zu erlernen.

Docutils, der Schöpfer von reStructuredText, hat hier eine Liste von reStructuredText-Editoren zusammengestellt, die Folgendes umfasst:

Der Sinn von reStructuredText ist, dass es einfach ist, zwischen verschiedenen Formaten zu konvertieren, insbesondere von einfachem Text zu einer statischen Website. Weitere Informationen finden Sie hier.

Tools zur automatischen Generierung von Dokumentation aus dem Quellcode

Es geht nichts über die menschliche Note, wenn es um Dokumentation geht (das zeigt sich deutlich in den Dokumentationen von Slack und Giphy, um nur einige zu nennen). Als Ausgangspunkt (vor allem für umfangreiche Quellcode-Bibliotheken) ist es jedoch am besten, die Basisdokumentation automatisch zu erstellen. Dies funktioniert durch die Analyse der Funktionen und Kommentare des Quellcodes, und es gibt je nach Sprache einige verschiedene Optionen:

Bevor Sie sich ausschließlich auf die automatische Generierung verlassen, empfehle ich, diesen StackExchange-Thread zu lesen, in dem die Vor- und Nachteile abgewogen werden.

Abschließende Worte zur Software-Dokumentation

Es gibt viele ausgefallene Lösungen, Schnellreparaturen und Tools, die (ehrlich gesagt) fast identisch sind. Was am Ende zählt, ist, dass

Was am Ende am meisten zählt, ist, dass:

a) Sie für jedes Stück Software, das Sie entwickeln, eine Softwaredokumentation schreiben
b) Sie sie umfassend schreiben und sie an einem Ort bereitstellen, auf den der Benutzer zugreifen kann

Ich habe vorhin erwähnt, dass ich noch ein paar weitere Vorlagen für den Entwicklungsprozess habe, die Sie sich vielleicht ansehen möchten?

Nun, hier sind sie…

Process Street Entwicklungsprozessvorlagen

Bevor ich Ihnen diese Vorlagen vorstelle, lassen Sie mich noch ein wenig erklären, was Process Street ist.

Wir wissen also, dass Process Street superstarke Checklisten sind. Es ist eine Software, die Ihnen helfen wird, Prozesse zu erstellen und zu verwalten.

Aber warten Sie, Process Street hat noch mehr zu bieten!

Sehen Sie sich dieses Einführungsvideo an, um herauszufinden, was ich meine:

Sie sehen also, Sie können nicht nur eine Vorlage für den Entwicklungsprozess erstellen und jedes Mal, wenn Sie den Entwicklungsprozess abschließen müssen, einzelne Checklisten davon ausführen, sondern Sie können sie mit diesen zusätzlichen Funktionen anpassen

• Aufgaben stoppen
• Dynamische Fälligkeitsdaten
• Aufgabenberechtigungen
• Bedingte Logik
• Aufgaben genehmigen
• Widget einbetten
• Rollenzuweisungen

Aufgaben zuweisen, Genehmigungen einholen, eine Reihenfolge erzwingen, in der die Aufgaben erledigt werden, und Sie können den Prozess über Zapier, Webhooks oder API-Integration mit Tausenden von Apps verbinden.

Schauen Sie sich dieses Webinar über unsere neuesten Funktionen an und erfahren Sie, wie Sie sie optimal nutzen können:

Werfen Sie einen Blick auf die folgenden vorgefertigten Vorlagen:

Checkliste für die Netzwerksicherheitsprüfung

Diese Vorlage kann von einem Risikomanager oder einem entsprechenden IT-Experten verwendet werden, um ein Netzwerk auf Sicherheitsschwachstellen zu prüfen.

Klicken Sie hier, um auf die Checkliste für die Netzwerksicherheitsprüfung zuzugreifen!

Monatliche Website-Wartungscheckliste

Nutzen Sie diese monatliche Website-Wartungscheckliste, um die Ladegeschwindigkeit Ihrer Website zu optimieren, nach Schwachstellen zu suchen und Ihre Sichtbarkeit bei der Suche zu überprüfen.

Klicken Sie hier, um auf die monatliche Website-Wartungscheckliste zuzugreifen!

Lehrgang zum Testen von Software

Dieser Prozess kann verwendet werden, um ein komplettes Softwareentwicklungsprojekt von Anfang bis Ende zu verwalten, einschließlich Design, Kundenhandling und Überprüfungen nach der Einführung.

Klicken Sie hier, um zum Software-Testing-Tutorial zu gelangen!

Und das war’s.

Sie können nun das verwenden, was Ihnen das Leben leichter macht. Ich hoffe, Sie finden Ihr neues Lieblingswerkzeug in dieser Liste.