funkyfrogstock - Fotolia
Best Practices und Tools für die Softwaredokumentation
Softwaredokumentation unterstützt dabei, Entwicklungsprojekte zu gestalten und bestehende Angebote zu verbessern. Wir stellen Tools für die Softwaredokumentation vor.
Unternehmen, die Software entwickeln, stehen immer wieder vor der Frage, wie sie ihre Dokumentation veröffentlichen sollen. Darauf gibt es keine einfache Antwort. Es gibt viele Tools für die Softwaredokumentation, aber es gibt keinen klaren Marktführer. Es gibt zwar Standards für die Erstellung von Softwaredokumentationsseiten, aber selbst diese gemeinsame Basis löst nicht alle Probleme.
Hier erhalten Sie einen Einblick in die Arten von Referenz- und Leitfaden-Softwaredokumentation, Dinge, auf die Sie bei Dokumentations-Tools achten sollten, und die beliebtesten Tools auf dem Markt, von SwaggerHub bis ReadMe.
Arten der Softwaredokumentation
Mitarbeitende in vielen Rollen, vom Vertriebsmitarbeiter für Cloud-Dienste bis zum internen Softwareentwickler, müssen Material für Anwender bereitstellen und verwenden dafür Softwaredokumentations-Tools. Um die Optionen zu verstehen, beginnen wir mit einer Frage, die sich speziell an Softwareentwickler richtet: Wie sollte ein Unternehmen APIs und SDKs dokumentieren?
APIs und SDKs sind zwei Arten von Softwareprodukten, die Entwickler für andere Entwickler schreiben. APIs dienen als Frontends für Software und Benutzer, um mit Ihrer Software zu interagieren. Ein SDK bietet eine Reihe von Tools mit einem bestimmten Zweck. Um zum Beispiel eine App auf einem Android-Gerät darzustellen, verwenden Sie das Android-SDK, um dem Programm die Bildschirmausrichtung, den Typ des Mobilgeräts, die Farben und so weiter mitzuteilen. Anhand von APIs und SDKs gehen wir die verfügbaren Softwaredokumentationstypen und ihre Verwendung durch.
Referenzen. Referenzen geben die technischen Parameter für die Verwendung von Objekten, Methoden und Funktionen an. Sie bieten keine Anleitungen, sondern nur die spezifischen Informationen, die für die Verwendung der Objekte und Funktionen erforderlich sind. Referenzen sind knapp formuliert, was sie schwer verständlich machen kann.
Der Standard für die Dokumentation von APIs ist die OpenAPI-Spezifikation (OAS) (früher bekannt als Swagger-Spezifikation). OAS generiert automatisch eine Referenzdokumentation, die Codebeispiele in verschiedenen Sprachen enthalten kann. Ein Programmierer muss jedoch unzählige Stunden mit dem Ausfüllen von OAS-Definitionen verbringen. Um den Zeitaufwand für die OAS-Definitionen zu rechtfertigen, haben einige Unternehmen die Beschreibungen als Architektur-Tool übernommen, um zu Beginn von Entwicklungsprojekten Standardcode zu generieren.
Ein weiterer Standard, der speziell für Java gilt, ist Javadoc. Javadoc erfordert etwas weniger Aufwand als OAS, aber die Referenzdokumentation, die damit erstellt wird, ist so kompliziert, dass Programmierer stattdessen eher Handbücher bevorzugen.
Leitfaden. Entwickler schreiben Anleitungen, um die Verwendung des SDK oder der API zu erklären. Im Gegensatz zu Referenzen ist ein Leitfaden oder Guide eine Freiform-Erzählung. Er folgt keinem festen Format, sondern ist in der Regel in Absätzen mit Abbildungen, Tabellen, Listen und Diagrammen geschrieben. Leitfäden bieten Hintergrundmaterial und Codebeispiele, definieren Konzepte und erklären Parameter und zurückgegebene Werte.
Ein Leitfaden geht detaillierter auf die Parameter ein, die für die Verwendung der Software erforderlich sind, als eine Referenz, und er enthält Links zwischen den Abschnitten, um dem Benutzer zu helfen, verwandte Informationen zu finden.
10 Merkmale guter Tools für die Softwaredokumentation
Es ist einfacher, verschiedene Arten von Softwaredokumentation zu erstellen – für verschiedene Arten von Software – wenn man das richtige Werkzeug hat. Eine gute Dokumentation kann ein Produkt im Laufe der Zeit sogar noch besser machen. Suchen Sie nach Tools mit diesen Eigenschaften:
1. Markdown- und HTML-Unterstützung. Tools für die Softwaredokumentation, die sowohl Markdown als auch HTML unterstützen, sind zu bevorzugen. Markdown ist ein weit verbreiteter Standard für Softwaredokumentation. Es handelt sich dabei im Wesentlichen um eine verkürzte Form von HTML, die für die Erstellung von Handbüchern zu wortreich und umständlich sein kann. Markdown eignet sich im Allgemeinen für Autoren, die HTML-ähnliche Textmodifikatoren zur Erstellung von Listen, Tabellen und mehr verwenden möchten. Außerdem gibt es bei Markdown Einschränkungen: Sie können beispielsweise keine Schriftarten ändern oder Objekte mit Rahmen versehen. Daher ist die Möglichkeit, HTML und Markdown zu mischen, hilfreich.
2. Feedback. Feedback macht Software besser, und Dokumentationswerkzeuge bieten verschiedene Möglichkeiten, Feedback zu sammeln und zu überprüfen. Alltägliche Produktbenutzer werden Funktionen entdecken, an die Sie nie gedacht haben. Diese Benutzer werden Ihnen helfen, Fehler in Ihrer Website aufzudecken und klärende Fragen zu stellen. Einige Tools verbinden Softwarebenutzer und Entwickler per E-Mail oder mit einer Frage-Schaltfläche für Kommentare. ReadMe, ein beliebtes Dokumentationswerkzeug, ermöglicht es Benutzern, Seiten auszuchecken und Änderungen daran vorzunehmen. Diese Änderungen werden dann in eine Warteschlange gestellt, damit die Entwickler sie genehmigen, ablehnen oder mit anderen Änderungen zusammenführen können.
3. Benutzerdefinierte, in der Cloud gehostete Domains. Sie müssen Ihre eigene Produktdokumentation nicht mehr hosten. Beginnen Sie beispielsweise bei ReadMe mit einer Domain wie ihr-produkt.readme.io. Wenn Sie dann bereit sind, die Domain zu veröffentlichen, ändern Sie den Pfad in dokumentation.ihr-unternehmen.com und fügen einen DNS-Eintrag hinzu, der auf ReadMe verweist.
4. Zugriffskontrolle. Bei den meisten Softwareentwicklungen ist nicht ein einziger Autor für die gesamte Dokumentation verantwortlich. Autoren verschiedener Rollen und Ebenen fügen Informationen hinzu. Suchen Sie also nach einem Tool, das eine Zugriffsverwaltung bietet.
5. APIs für einfache Integration. Machen Sie es Ihren Benutzern leicht. Das von Ihnen gewählte Tool sollte es den Nutzern gestatten, per Mausklick APIs direkt aus der Dokumentation heraus zu starten.
6. Client-seitige Backups. Tools für die Softwaredokumentation sollten es Ihnen ermöglichen, Ihre eigenen Sicherungen zu erstellen. Verlassen Sie sich bei der Sicherung Ihres Systems nicht auf jemand anderen.
7. Technische Unterstützung. Einige Anbieter von Tools bieten nur spärlichen Support. Suchen Sie sich einen Anbieter, der Ihnen hilft, wenn eine Seite beschädigt ist, oder der Ihnen helfen kann, etwas wiederherzustellen, das verloren gegangen ist. ReadMe erhält in dieser Hinsicht eine schlechte Note, zumindest bei Entwicklerkonten; ReadMe Enterprise kann einen besseren Support bieten.
8. Anpassbare Landing Pages. Idealerweise lässt ein Softwaredokumentations-Tool die Verwendung von HTML und Style Sheets auf Landing Pages zu.
9. Inhaltsverzeichnisse. Dokumentationswerkzeuge sollten es Ihnen erlauben, ein klares Inhaltsverzeichnis für eine einfache Navigation zu erstellen.
10. Kontrolle über die Veröffentlichung. Sie sollten in der Lage sein, Seiten nach Bedarf zu veröffentlichen und wieder zu entfernen.
Tools für die Softwaredokumentation
Da Sie nun wissen, worauf Sie achten müssen, befassen wir uns mit Softwaredokumentationswerkzeugen. Es gibt viele Softwaredokumentationsplattformen, die auf OAS/Swagger ausgerichtet sind. OAS beschränkt die Benutzer auf Referenzdokumente, aber die Tools erweitern die Möglichkeiten.
Hier sind einige Tools für die Softwaredokumentation:
ReadMe ist vielleicht die beste Option, da es sowohl OAS-Referenzen als auch Leitfäden verarbeiten kann. Die kürzlich erfolgte Plattformaktualisierung und der langsame Support auf Entwicklerebene sind jedoch gewöhnungsbedürftig. Angesichts der geringen Auswahl auf dem Markt für Softwaredokumentation sollten Sie sich anpassen und bei einer Option bleiben, die Ihren Anforderungen entspricht. Hier sind ein paar Hinweise zu drei beliebten Optionen:
SwaggerHub. SwaggerHub, ein Produkt von SmartBear, ist eine gute Option, um sich mit Swagger und OAS vertraut zu machen und um Dokumentation zu hosten. SwaggerHub enthält einen Spezifikationseditor zum Schreiben von OAS-Spezifikationen.
SwaggerHub bietet eine Demoseite namens Petstore mit einem YAML-Editor. Mit OAS dokumentieren Sie jeden Endpunkt, jede Methode, jeden Fehlercode, jeden Parameter und jedes Objekt entweder in YAML- oder JSON-Formatierung. So enthält der Petstore-Editor Endpunkte wie POST zum Hinzufügen eines so genannten Haustiers. Auf der Website können Sie Endpunkte ausprobieren, Parameter und Authentifizierungsinformationen eingeben und dann APIs ausführen.
ReadMe. Dieses Dateiformat eignet sich für Anleitungen in freier Form. ReadMe leistet gute Arbeit mit manuell erstellten APIs und solchen, die automatisch von OAS generiert werden. Bei einem stabilen Produkt und einer breiten Benutzerbasis ist es leicht, über die erwähnten Mängel von ReadMe hinwegzusehen.
Zu Beginn fragt ReadMe nach Ihrem Produktnamen und danach, ob Sie eine REST API oder etwas anderes dokumentieren möchten. Außerdem wird nach einem temporären Domänennamen gefragt, den Sie später in Ihre bestehende Domäne umwandeln können. Nachdem Sie diese Informationen eingegeben haben, werden Sie zur Hauptseite weitergeleitet. Hier können Sie Anleitungen erstellen, mit OAS arbeiten, Referenzmaterial verfassen und die Website anpassen.
Wenn Sie angeben, dass Sie OAS verwenden werden, fragt ReadMe Sie nach der URL, unter der diese Spezifikationen gespeichert sind. ReadMe übernimmt diese Spezifikationen und generiert automatisch Dokumentation und Codebeispiele. Sie geben dann den statischen Teil Ihrer API-Definition ein, zum Beispiel die Haupt-URL, sowie die Art der Anmeldeinformationen, die Sie verwenden möchten, zum Beispiel OAuth oder einen geheimen Schlüssel.
Für Anleitungen arbeiten Sie mit dem ReadMe-Editor. Sie können Markdown direkt in den Editor eingeben oder Widgets verwenden, um Markdown-Objekte zu erstellen. Auf dem Bildschirm unten können Sie auch auf die Unterstützung für HTML unterhalb der Widgets zugreifen, indem Sie auf View all klicken.
GitHub Pages. Die Unterstützung von GitHub für Markdown hat dazu beigetragen, dass GitHub zu einem Standard für das Hosting von Anwendungscode geworden ist. Die meiste Open-Source-Software ist in Repositories auf GitHub gespeichert, darunter auch bekannte Projekte wie Elasticsearch. Jedes Programm beginnt mit einer in Markdown geschriebenen Landing Page namens README. Nehmen wir das Beispiel von Elasticsearch und seiner README-Seite. GitHub ist jedoch keine gute Plattform für die Dokumentation von Software. GitHub generiert zum Beispiel kein Inhaltsverzeichnis. Um ein solches zu erhalten, müssen Benutzer Bilder manuell in einen Ordner hochladen und dann Links zu ihnen erstellen. Andere Produkte erledigen diese Aufgabe einfacher.
Mehrere Softwareprojekte schreiben ihr eigenes Frontend für GitHub. Diese Projekte arbeiten mit einem Tool wie Jekyll, das HTML aus Anweisungen auf GitHub-Seiten generieren kann. Dieser Ansatz kombiniert Markdown mit einer speziellen Markdown-ähnlichen Syntax, was nicht ideal ist.
