Ein Leitfaden zum Schreiben Ihrer ersten Softwaredokumentation

Als Entwickler ist Ihr Stolz und Ihre Freude Ihr Code. Es ist lesbar, es erfüllt trockene Prinzipien, spiegelt Best Practices wider, und das Endprodukt ist ein großartiges Tool, das ein Problem für seine Zielbenutzer löst. Unabhängig davon, wie viel Arbeit Sie in Ihren Code gesteckt haben, wenn Ihre Software keine Dokumentation hat oder Sie Dokumentation als nachträglicher Gedanke schreiben und sie mit geringer Bedeutung behandeln, werden die Benutzer wahrscheinlich wenig Freude daran haben, damit zu arbeiten, und sie werden sie nur wenig Freude finden, und sie werden sie nur wenig Freude finden, und sie werden sie haben, und sie werden sie kaum Freude finden, und sie werden sie haben und mit ihm umgehen, und es Entscheiden Sie sich schließlich für ein anderes, benutzerfreundlicheres Produkt.

In diesem Artikel finden Sie eine Reihe praktischer Leitprinzipien, um Sie mit dem Schreiben Ihrer ersten Software -Dokumentation zum Laufen zu bringen.

Key Takeaways

• Gute Softwaredokumentation ist für die Einführung und das Verständnis von Benutzern von entscheidender Bedeutung und dient als Kommunikationsinstrument zwischen Entwicklern und Benutzern. Es sollte Tutorials, Anleitungen, Referenzleitfäden und Erklärungen enthalten, die einen umfassenden Leitfaden für die Funktionen der Software bieten.
• Die Zielgruppe für die Dokumentation sollte klar identifiziert werden, da dies den verwendeten Inhalt und die verwendete Sprache beeinflusst. Im Kontext dieses Handbuchs liegt der Fokus auf Dokumentation für Entwickler unterschiedlicher Vertrautheit mit der Software und nicht auf Benutzerhandbüchern oder Projektdokumentation.
• Die Dokumentation sollte leicht erfunden, gut strukturiert und regelmäßig aktualisiert werden. Es wird empfohlen, die Dokumentation in der Quellvertretung in der Nähe des Code zu halten, um sicherzustellen, dass sie bei der Auftreten von Code -Aktualisierungen relevant und genau bleibt. Das Einbeziehen einer FAQs -Seite kann auch dazu beitragen, gemeinsame Benutzeranfragen zu behandeln.
• Über die traditionelle Dokumentation hinaus können Blog -Posts als nützliches Tool zur Erläuterung von Softwarefunktionen, Bereitstellung von Tutorials und Teilen von Updates dienen. Dies kann eine Community um die Software fördern und zu ihrem Wachstum und Erfolg beitragen. Beispiele für gute Dokumentationspraktiken finden Sie in Plattformen wie Greensock, React und Vue.js.

Warum Dokumentation wichtig ist

In Bezug auf Ihre Software hat Mike Pope ein passendes Sprichwort, das so lautet: Wenn es nicht dokumentiert ist, existiert es nicht .

Warum ist das? Nun, nur um meine persönliche Erfahrung als Beispiel zu machen, suchte ich im Internet nach neuen JavaScript -Animationsbibliotheken, die ich ausprobieren konnte, und stieß auf eine mit einer Beschreibung der Funktionen, die mir sehr gut gefallen hat. Es gab jedoch keine Dokumentation, nicht einmal einen Abschnitt mit Erste Schritten, sondern nur eine API-Seite mit nackten Beinen ohne Erklärungen oder Beispiele. Glaubst du, ich habe diese Bibliothek verwendet? Natürlich habe ich es nicht getan. Ich war so frustriert damit, dass ich zu etwas überging, das für mich sinnvoller machte.

zur Frage von Warum gute JavaScript -Bibliotheken fehlschlagen , nicholos zakas gibt die folgende Antwort:

Mangel an Dokumentation . Egal wie wunderbar Ihre Bibliothek ist und wie intelligent das Design ist, wenn Sie der einzige sind, der sie versteht, tut es nicht gut. Dokumentation bedeutet nicht nur autogenerierte API-Referenzen, sondern auch kommentierte Beispiele und eingehende Tutorials. Sie benötigen alle drei, um sicherzustellen, dass Ihre Bibliothek leicht angenommen werden kann.

Ein weiterer wichtiger Grund, warum Ihre Software -Dokumente von entscheidender Bedeutung sind, ist, dass sie als Kommunikationsinstrument zwischen Ihrem gegenwärtigen Selbst und Ihrem zukünftigen Selbst und auch zwischen Ihrem gegenwärtigen Selbst und anderen Entwicklern dienen, die sich irgendwann möglicherweise an Ihrer Software arbeiten. Selbst wenn Sie lesbarer und kommentierter Code schreiben, bedeutet dies nicht unbedingt, dass Sie in sechs Monaten immer noch klar sein wird, warum Sie eine Funktion oder ein anderes Stück Ihres Codes geschrieben haben, wie Sie es getan haben.

Mit

Dokumentation können Sie die warum hinter dem Code übertragen. Ähnlich wie Code -Kommentare erklären die Warum und nicht die Wie , Dokumentation dient den gleichen Zweck. - Ein Anfängerleitfaden zum Schreiben von Dokumentation

Sie möchten sicherlich, dass die Leute Ihren Code verwenden und schließlich auch in der Lage sind, ihn zu aktualisieren und ihn zu verbessern. Dies alle tragen zum Wachstum einer unterstützenden Gemeinschaft hinter Ihrem Produkt bei, was für die Gewinnung von Robustheit, Reife und Erfolg wichtig ist.

Es wird mächtig schwierig, all dies zu erreichen, wenn Ihre Software keine großartigen Dokumente dazu hat.

WHO -Softwaredokumentation ist für

Wenn Sie etwas schreiben, stellen Sie sicher, dass es Ihnen klar ist, wer Ihr Publikum ist. Dokumente sind keine Ausnahme von dieser Regel. Dadurch wird in Ihrem Kopf klargestellt, dass Ihr Publikum wahrscheinlich mit Ihrem Produkt oder den Voraussetzungen für die Verwendung Ihres Produkts vertraut ist. Diese Informationen sind entscheidend für die Art und Weise, wie Sie den Inhalt und die Sprache erstellen, die Sie verwenden.

Es gibt zwei Arten von Dokumentationen, mit denen sich dieser Artikel nicht befasst:

1. Benutzerhandbücher. Zum Beispiel könnte meine Schwester beschließen, WordPress für die Veröffentlichung ihres eigenen Blogs zu verwenden. Sie ist keine Entwicklerin, aber sie hat gehört, dass Nicht-Devs ihren Blog in kürzester Zeit mit WordPress zum Laufen bringen können. Jetzt benötigt sie Anweisungen zum Herunterladen und Konfigurieren der Software auf ihrem Server, zum Schreiben, Veröffentlichen und Aktualisieren ihrer Beiträge, zum Hinzufügen von Bildern zu einem Beitrag usw. Mit anderen Worten, sie braucht einen Benutzer Handbuch.
2. Projektdokumentation. Diese Art von Dokumentation hat mehr mit dem Projekt zu tun als mit der Software selbst, obwohl einige seiner Inhalte in der Readme -Datei eines Projekts eingehen könnten. Um mit dem WordPress -Beispiel fortzufahren, könnte ich nach dem Erhalten von viel Übung bei WordPress entscheiden, dass ich der Software eine Funktion hinzufügen oder ein oder zwei Fehler beheben möchte. In diesem Fall muss ich Dinge wie Changelogs, Konventionen und Best Practices, Beitragsrichtlinien, die Teilnahme an Teamdiskussionen für die jeweilige Aufgabe usw. wissen.

Die Art von Dokumentation, die ich hier im Sinn habe, richtet sich hauptsächlich an Entwickler, die mit Ihrer Software unterschiedliche Maßstäbe haben und sie in ihren Projekten verwenden müssen. Wenn ich beispielsweise ein WordPress -Thema erstelle, muss ich wissen, wie man anfängt, wie man Stilblätter und JavaScript -Dokumente einbezieht, wie man mit der Datenbank kommuniziert, um Beiträge anzuzeigen usw.

Was ist in Ihre Dokumentation

aufzunehmen

Ein beliebter Ansatz ist die von Tom Preston-Würner beaufsichtigte Readme-Driven-Entwicklung. Es besteht aus dem Schreiben des Readme -Dokuments, bevor Sie überhaupt einen Code schreiben. Dieses Dokument ist eine Einführung in Ihre Software und umfasst normalerweise:

• Eine Erläuterung, was Ihre Software tut und welches Problem sie löst
• Ein Beispiel, das die Umstände veranschaulicht, unter denen Ihr Code normalerweise verwendet wird
• Links zum Code und Fehler Tracker
• FAQs und Möglichkeiten, um Unterstützung zu bitten
• Anweisungen zur Installation Ihrer Software
• Lizenzinformationen

Meiner Ansicht nach sollte eine solide Dokumentation, die Entwicklern, die Ihre Software/Bibliothek verwenden, wirklich helfen können, weit über die klassische Readme -Datei hinauszugehen. Nach Daniele Procida schlage ich vor, dass Sie die folgenden Elemente in Ihr Dokumentationsmaterial für eine großartige Benutzererfahrung aufnehmen.

Tutorials

Ein Anfänger wird gerne ein Tutorial in Ihren Software -Dokumenten finden. Bei Tutorials geht es darum, Benutzern zu zeigen, wie ein Projekt mit Ihrer Software abgeschlossen werden kann, damit sie schnell ein Gefühl dafür bekommen, was sie damit machen können.

Tutorials sind Lektionen , die den Leser an der Hand durch eine Reihe von Schritten führen, um ein Projekt abzuschließen. Sie sind das, was Ihr Projekt braucht, um einem Anfänger zu zeigen, dass er etwas damit erreichen kann. - Daniele Procida

Anleitungen

Anleitungen helfen Benutzern, eine reale Aufgabe mit Ihrer Software zu lösen. Procida vergleicht sie mit Rezepten in dem Sinne, dass es sich um Anweisungen handelt, die Sie den Benutzern geben, damit sie erfolgreich ein bestimmtes Ziel erreichen können. Im Gegensatz zu Tutorials, die an Anfänger abzielen, nehmen die Anleitungen an, dass Benutzer bereits einige Grundkenntnisse über Funktionen, Tools und die Ausführung einfacher Aufgaben besitzen.

Referenzführer

Referenzführer sind technische Referenzen des Code Ihrer Software - Funktionen, APIs usw. - und bieten eine grundlegende Beschreibung der Verwendung der Software. Beispielsweise finden Sie ein Beispiel dafür, wie eine bestimmte Klasse instanziiert, wie man eine bestimmte Methode aufruft und so weiter.

Referenzleitfäden sind

technische Beschreibungen der Maschinerie und wie man sie bedient. - Daniele Procida

Dies ist die Dokumentation, die Sie in den meisten Projekten wahrscheinlich finden. Entwickler sind in der Regel ziemlich gut darin, es zu schreiben, da sie alles über ihren Code wissen und wie man ihn verwendet.

Erläuterung

Erklärungen sind ein tiefes Eintauchen oder eine Diskussion über ein bestimmtes Thema, von dem Sie glauben, dass es für ein höheres Verständnis Ihrer Software relevant ist. Über Erklärungen weist Procida darauf hin -

Dieser Abschnitt der Dokumentation wird selten explizit erstellt, und stattdessen werden unter anderem Erklärungsausschnitte verstreut. Manchmal existiert der Abschnitt, hat aber einen Namen wie

Hintergrund oder andere Notizen und wird der Funktion nicht wirklich gerecht.

Ein Thema wird nicht durch eine bestimmte Aufgabe definiert, die Sie wie ein Anleitungen oder ein Tutorial lernen möchten, wie ein Tutorial. Es wird nicht durch ein Stück der Maschinen wie Referenzmaterial definiert. Es ist definiert durch das, was

Sie denken, dass dies ein vernünftiger Bereich ist, um zu versuchen, gleichzeitig zu decken. Daher kann die Diskussionsaufteilung manchmal etwas willkürlich sein.

Dinge, die Sie benötigen, um

zu achten

Lassen Sie uns einige nützliche Hinweise darüber durchgehen, wenn Sie Ihre Dokumente benutzerfreundlich und relevant machen.

Machen Sie Ihre Dokumente entdeckbar

Es ist eine gute Idee, etwas daran zu arbeiten, Ihre Software -Dokumentation leicht zu finden. Sie könnten einige SEO -Techniken zusammen mit einigen Marketingstrategien verwenden, damit möglichst viele Benutzer dies erreichen können.

Außerdem sollte das, was Sie in Ihre Dokumente einfügen, in eine Struktur organisiert werden, die die Suche nach bestimmten Informationen zu einem Kinderspiel macht. Steve Konves empfiehlt, dass Sie Ihre Dokumente in einem einzelnen verknüpften Baum strukturieren: Starten vom Stammknoten, der an einem offensichtlichen Ort platziert werden sollte, an dem jeder interessierte Benutzer entdeckt werden muss, können auf alle anderen Elemente leicht zugegriffen werden. Die Readme -Datei des Projekts eignet sich für sehr gut als großer Stammknoten für den gesamten Baum.

Wenn Sie Hilfe von den Benutzern Ihrer Software erhalten, können Sie die Antworten schreiben und auf einer leicht zugänglichen FAQs -Seite zur Verfügung stellen. Dies verringert die Zeit, in der Sie den Benutzern helfen, aber es gibt Ihnen auch eine klarere Vorstellung von der Art von Informationen, die Benutzer am häufigsten benötigen, damit Sie sie zuerst dokumentieren und an einem prominenten Ort in Ihren Dokumenten behalten können.

Stellen Sie sicher

ist einfach auf Ihre Software -Dokumentation zuzugreifen. Wenn Benutzer jedoch herausfinden, dass der Inhalt veraltet ist oder der Beispielcode oder Anweisungen zu fehlerhaften Ergebnissen führen, wird dies gelinde gesagt frustrierend. Dennoch schlägt Steve Konves vor, dass Sie Ihre Dokumente in der Nähe des Code halten - zum Beispiel in der Quellensteuerung. Wenn Entwickler den Code aktualisieren, werden sie das Dokumentationsmaterial bemerken, wodurch die Aktualisierung der DOCs zu einem viel wahrscheinlicheren Ereignis wird.

Testen Sie auch die Anweisungen und die Code -Muster, die Sie in Ihren Dokumenten bereitstellen.

, um das Auftreten von Fehler gründlich zu minimieren.

zusätzliches Tipp und einige beliebte Beispiele

Halten Sie nicht in der Dokumentation an. Blog -Beiträge eignen sich hervorragend, um Ihre Software und ihre Funktionen einem breiten Publikum potenzieller Benutzer bekannt zu machen. Verwenden Sie Ihr Blog, um Klarstellungen dessen anzugeben, was Ihr Produkt macht, benutzerfreundliche Tutorials, Tipps und Tricks, Walk-Throughs, Erklären Sie Updates usw. Sie können Ihr Blog in eine eigenständige Website einbeziehen, die Ihrer Software gewidmet ist-möglicherweise mit einem Forum - um die sich eine starke Gemeinschaft versammeln und wachsen kann.

Ein großartiges Beispiel für diese umfassendere Idee der Dokumentation meiner Ansicht nach wird von Greensock implementiert, einer weit verbreiteten JS-Animationsplattform, die ich viel benutze, nicht zuletzt, weil die Website einfach zu nutzende und gut zugänglich ist Strukturierte Dokumente, ein super hilfreiches Forum, Blog -Beiträge, schnelle Tipps und vieles mehr.

reag und vue.js können auch als großartige Beispiele gezählt werden. Sobald Sie auf die jeweiligen Websites zugreifen, gibt die Startseite mit, für die jede Bibliothek in einem kurzen Slogan gut ist, und geht dann weiter auf, warum die Bibliothek als großartige Wahl für Ihr Projekt angesehen werden kann. Beide Websites machen mit sanften Einführungen, illustrativen Ausschnitten und Anfängern, die mit der neuen Software ein wenig Vertrauen gewonnen haben, weniger einschüchternd mit sanften Einführungen, illustrativen Ausschnitten und Anfängern mit Code -Spielplätzen usw. erledigen. Details, wie Sie Hilfe erhalten, Informationen zum Ökosystem anzeigen, einen Nachrichten- oder Blog -Abschnitt anbieten usw.

Um die JS -Zone zu verlassen und mit großartigen Websites in den Gebiet der beliebten UI -Bibliotheken zu gehen, kann ich Bootstrap nicht weglassen. Auf der Bootstrap-Website finden Sie sofort, wofür die Bibliothek gut ist und wie Sie schnell beginnen können, sowie umfassende und gut strukturierte Dokumente und ein Blog, um die Benutzer über das Neue auf dem Laufenden zu halten.

Schlussfolgerung

Eine gute Dokumentation schreiben, hat ihre Herausforderungen, aber es zahlt sich sicherlich hundertmal aus, wenn Sie der Meinung sind, wie viel einfacher es für Ihre Benutzer sein wird, die Funktionen Ihrer Software zu implementieren. Dies wiederum trägt zur Popularität Ihrer Software bei, was es attraktiv macht und daher offen für die Möglichkeit, einer Gemeinschaft von Entwicklern zu führen, die bereit sind, ihre Zeit in das Erlernen des Lernens zu investieren und zu ihrem Wachstum, Stabilität und langfristig beizutragen Verwendung.

häufig gestellte Fragen (FAQs) zum Schreiben von Software -Dokumentation

Was sind die wichtigsten Elemente, die beim Schreiben von Software -Dokumentation berücksichtigt werden müssen? Die verwendete Sprache sollte klar, präzise und leicht zu verstehen sein. Das Dokument sollte mit einem logischen Informationsfluss gut strukturiert sein. Es ist auch wichtig, Bilder wie Diagramme oder Screenshots einzubeziehen, wo dies erforderlich ist, um das Verständnis zu unterstützen. Stellen Sie schließlich immer sicher, dass das Dokument gründlich überprüft und für Genauigkeit und Klarheit bearbeitet wird. und klare Sprache. Vermeiden Sie Jargon und technische Begriffe so weit wie möglich. Wenn Sie sie verwenden müssen, stellen Sie sicher, dass Sie klare Definitionen bereitstellen. Organisieren Sie Ihre Inhalte logisch und verwenden Sie Überschriften und Unterüberschriften, um das Navigieren zu erleichtern. Fügen Sie ein Inhaltsverzeichnis und einen Index für längere Dokumente hinzu. Verwenden Sie Visuals wie Diagramme, Screenshots und Videos, um komplexe Konzepte zu veranschaulichen. und technische Dokumentation. Die Systemdokumentation bietet einen Überblick über das Softwaresystem, einschließlich der Architektur und des Datenflusss. Die Benutzerdokumentation enthält Anweisungen zur Verwendung der Software sowie Benutzerhandbücher und Hilfsführer. Technische Dokumentation ist für Entwickler bestimmt und umfasst Code -Kommentare, API -Dokumentation und Entwicklungsleitfäden.

Wie oft sollte die Softwaredokumentation aktualisiert werden? Software. Dies kann darauf zurückzuführen sein, dass neue Funktionen hinzugefügt werden, vorhandene Funktionen geändert oder Fehler behoben werden. Es ist auch eine gute Idee, die Dokumentation regelmäßig zu überprüfen, um sicherzustellen, dass sie immer noch korrekt und relevant ist.

Mit welchen Tools kann ich Software -Dokumentation schreiben? Einige beliebte Optionen sind Microsoft Word, Google Docs, Doxygen und Sphinx. Die Auswahl des Tools hängt von Ihren spezifischen Anforderungen und der Komplexität der Software ab.

Wie kann ich die Qualität meiner Software -Dokumentation sicherstellen? und bearbeiten Sie Ihre Arbeit gründlich. Erwägen Sie, einen Kollegen oder einen professionellen Redakteur Ihr Dokument zu überprüfen. Verwenden Sie im gesamten Dokument einen konsistenten Stil und Format. Stellen Sie sicher, dass die Informationen genau, aktuell und relevant sind. Zuletzt in Betracht, Feedback von Benutzern zu erhalten, um Verbesserungsbereiche zu identifizieren. Sie können dazu beitragen, komplexe Konzepte zu veranschaulichen und sie einfacher zu verstehen. Sie können auch große Textblöcke aufbrechen und das Dokument lesbarer machen. Beispiele für Visuals sind Diagramme, Screenshots, Flowdiagramme und Videos.

Wie kann ich meine Software -Dokumentation ansprechender gestalten? . Brechen Sie große Textblöcke mit Bildern und Kugelpunkten auf. Verwenden Sie Beispiele und Fallstudien, um Konzepte zu veranschaulichen. Geben Sie gegebenenfalls interaktive Elemente wie Quiz oder Übungen ein. Es gibt dem Dokument auch ein professionelles Erscheinungsbild. Konsistenz gilt für Sprache, Stil, Format und Visuals. Lesen Sie andere Softwaredokumentation, um von ihnen zu lernen. Nehmen Sie Kurse oder Workshops zum technischen Schreiben. Suchen Sie Feedback zu Ihrer Arbeit und sei offen für Kritik. Bleiben Sie mit den neuesten Trends und Best Practices in der Softwaredokumentation aktualisiert.

Das obige ist der detaillierte Inhalt vonEin Leitfaden zum Schreiben Ihrer ersten Softwaredokumentation. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!