Lesedokumente
Die Menschen lieben Open-Source-Software. Erstens ist der Code offen, so dass es sich sicherer anfühlt, mit einem Produkt zu arbeiten, wenn man sein Inneres gesehen hat. Zweitens kann man seinen eigenen Wert messen, indem man versucht, einen Beitrag zu leisten. Und drittens bietet Open Source einen fruchtbaren Boden für Online-Gemeinschaften, und ein Teil von ihnen zu sein, kann eine lustige und bereichernde Erfahrung sein.
Aber hier geht es nur um den Code, was ist mit anderen Dingen, die man als Open Source zur Verfügung stellen kann? Wie sieht es insbesondere mit technischer Dokumentation aus? Wie Sie wissen, benötigen die meisten Open-Source-Projekte die Mitarbeit von technischen Redakteuren. Und leider sind Open-Source-Benutzerhandbücher oft schlecht geschrieben oder fehlen ganz. Das behindert die Entwicklungsprozesse und schreckt potenzielle Mitwirkende ab.
Wenn Sie wirklich als technischer Redakteur bei einem Projekt helfen, Erfahrungen sammeln und mit Gleichgesinnten zusammenarbeiten wollen, oder wenn Sie vielleicht einen schmerzlosen Einstieg in die Open-Source-Programmierung suchen, können Sie versuchen, in den Bereich des technischen Schreibens für Open Source einzusteigen. Wir werden Sie durch die wichtigsten Schritte führen, die Sie dazu unternehmen sollten.
Was ist eine Open-Source-Dokumentation?
Offener Quellcode ist Quellcode, der für mögliche Änderungen und Weiterverbreitung frei zugänglich gemacht wird. Die Produkte beinhalten die Erlaubnis, den Quellcode, die Designdokumente oder den Inhalt des Produkts zu verwenden. Das Open-Source-Modell ist ein dezentrales Softwareentwicklungsmodell, das die offene Zusammenarbeit fördert.
Welche Software wird für die Dokumentation verwendet?
LaTex ist ein System zur Vorbereitung von Dokumenten und wird hauptsächlich zum Schreiben von wissenschaftlichen Arbeiten, technischen Papieren oder wissenschaftlichen Projektdokumentationen verwendet. Als solches ist es wahrscheinlich das am weitesten verbreitete Software-Dokumentationswerkzeug im akademischen Bereich. LaTex ist plattformübergreifend unter Windows, Linux und Mac OS verfügbar.
Beispiel einer Software für technische Dokumentation
Read the DocsSourceRead the Docs ist ein Open-Source-Softwaredokumentationstool, das verspricht, den Prozess für Entwicklerteams zu vereinfachen, indem es die Erstellung, Versionierung und das Hosting ihrer technischen Dokumente automatisiert.Entwickler können Projekte über GitHub importieren und dann Sphinx verwenden, um ihr proprietäres Dokumentationstool weiter anzupassen. Dazu gehört die Anpassung der Dokumenten- und Bibliotheksstruktur sowie der gesamten Benutzeroberfläche des Tools.Read the Docs FeaturesRead the Docs Pricing
Haroopad SourceHaroopad von HarooPress ist ein hochgradig visueller Dokumentenprozessor für technische und Entwicklungsteams.Der Charme von Haroopad liegt in seiner Einfachheit. Auf der Website des Teams heißt es: “Markdown ist einfach, hat aber … Portabilität und Erweiterbarkeit. Das Ziel von Haroopad ist ebenfalls einfach: Dennoch bietet Haroopad die Funktionalität und Anpassungsfähigkeit, die wir von diesen Open-Source-Lösungen erwarten.Haroopad FeaturesHaroopad Pricing
Confluence von AtlassianQuelleConfluence wird vom Entwickler Atlassian als “Teamarbeitsbereich, in dem sich Wissen und Zusammenarbeit treffen” bezeichnet. Confluence ist eine weitere umfassende Wissensmanagementlösung, wobei die Softwaredokumentation einer der Schwerpunkte des Tools ist. Der Fokus auf Zusammenarbeit bedeutet, dass alle Beteiligten an der Erstellung einer genauen, umfassenden und benutzerfreundlichen Softwaredokumentation beteiligt sind. Die Vorlagen von Confluence sind zwar anpassbar, wurden aber für bestimmte Anwendungsfälle entwickelt – auch für die Software-Dokumentation.Confluence-FunktionenConfluence-Preise
Dokument360
Open Source ist ein Quellcode, der frei zur Verfügung gestellt wird, damit er verändert und weitergegeben werden kann. Die Produkte beinhalten die Erlaubnis, den Quellcode,[1] die Designdokumente[2] oder den Inhalt des Produkts zu verwenden. Das Open-Source-Modell ist ein dezentrales Softwareentwicklungsmodell, das die offene Zusammenarbeit fördert[3][4].
Ein Hauptprinzip der Open-Source-Softwareentwicklung ist die Peer-Produktion, bei der Produkte wie Quellcode, Entwürfe und Dokumentation der Öffentlichkeit frei zugänglich sind. Die Open-Source-Bewegung in der Softwarebranche begann als Reaktion auf die Beschränkungen von proprietärem Code. Das Modell wird für Projekte wie die Open-Source-Technologie[5] und die Open-Source-Medikamentenentwicklung[6][7] verwendet.
Im Allgemeinen bezieht sich Open Source auf ein Computerprogramm, bei dem der Quellcode der Allgemeinheit zur Nutzung oder Veränderung gegenüber dem ursprünglichen Entwurf zur Verfügung steht. Der Code wird unter den Bedingungen einer Softwarelizenz freigegeben. Je nach den Lizenzbedingungen können dann andere den Code herunterladen, verändern und ihre Version (Fork) wieder der Gemeinschaft zur Verfügung stellen.
Beispiel für eine technische Dokumentation
Es ist aufregend, wenn offene Projekte von einer Handvoll Benutzer zu einem Team von Mitarbeitern anwachsen, die an der Software arbeiten und sie nutzen. Der Übergang von einem auf viele Mitwirkende ist ein wichtiger Moment für jedes Projekt. Wenn ein Projekt jedoch wächst und wächst, wird ein Bereich häufig vernachlässigt: die Dokumentation.
Fehlende oder unzureichende Dokumentation behindert die Skalierbarkeit eines Projekts. Die meisten potenziellen Benutzer überfliegen Ihre Dokumentation zuerst, um zu sehen, ob sie ihren Bedürfnissen entspricht und um zu beurteilen, wie schwierig die Benutzung sein könnte. Die Dokumentation prägt den ersten Eindruck Ihres Projekts: nicht nur bei potentiellen Benutzern, sondern auch bei potentiellen Mitwirkenden.
Das Verfassen und Verbessern der Dokumentation bietet einen klaren Weg für Personen, zu Ihrem Projekt beizutragen – vorausgesetzt, Sie bieten die richtigen Anleitungen und Prozesse, um sie zu unterstützen. In diesem Artikel werden bewährte Verfahren zur Gewinnung und Bindung von Open-Source-Dokumentationsmitarbeitern vorgestellt, die auf unseren Erfahrungen bei der Erstellung und Verwaltung der Dokumentation für Kubernetes basieren.
Beginnen Sie damit, Ihre bestehende Dokumentation zu bewerten. Sie können Ihre Mitwirkenden nicht um Hilfe bitten, wenn Sie nicht wissen, was Sie brauchen! Betrachten Sie Ihre Dokumentation aus der Perspektive Ihrer Benutzer: