Wie erstelle ich eine dokumentation

Wie erstelle ich eine dokumentation

Beispiel für Entwicklerdokumentation

Technische Redakteure und Unternehmenskommunikatoren sind Fachleute, deren Arbeitsgebiet die Dokumentation ist. Im Idealfall verfügen technische Redakteure sowohl über Fachwissen als auch über Kenntnisse in den Bereichen Schreiben, Verwaltung von Inhalten und Informationsarchitektur. Technische Redakteure arbeiten in der Regel mit Fachexperten (KMU) zusammen, z. B. mit Ingenieuren, technischen Experten, Medizinern usw., um die Anforderungen der Benutzer zu definieren und dann die entsprechende Dokumentation zu erstellen. Die Unternehmenskommunikation umfasst auch andere Arten von schriftlicher Dokumentation, zum Beispiel:

Eine in der Simulationsbranche übliche Art von Software-Dokumenten ist das SDF. Bei der Entwicklung von Software für einen Simulator, die von eingebetteten Avionikgeräten über 3D-Geländedatenbanken bis hin zu vollständigen Bewegungssteuerungssystemen reichen kann, führt der Ingenieur ein Notizbuch, in dem die Entwicklung des Projekts oder Moduls detailliert festgehalten wird. Das Dokument kann eine Wiki-Seite, ein MS-Word-Dokument oder eine andere Umgebung sein. Es sollte einen Anforderungsabschnitt und einen Schnittstellenabschnitt enthalten, in dem die Kommunikationsschnittstelle der Software beschrieben wird. Oft wird ein Abschnitt mit Notizen verwendet, um den Konzeptnachweis detailliert zu beschreiben und dann Fehler und Verbesserungen zu verfolgen. Schließlich gibt es einen Abschnitt über die Tests, der dokumentiert, wie die Software getestet wurde. Damit wird die Konformität mit den Anforderungen des Kunden dokumentiert. Das Ergebnis ist eine detaillierte Beschreibung des Softwareentwurfs, der Erstellung und Installation der Software auf dem Zielgerät sowie aller bekannten Fehler und Abhilfemaßnahmen. Dieses Build-Dokument ermöglicht es künftigen Entwicklern und Betreuern, sich rechtzeitig mit der Software vertraut zu machen, und bietet außerdem einen Fahrplan für die Änderung des Codes oder die Suche nach Fehlern.

Was ist ein Beispiel für eine Dokumentation?

Beispiele sind Benutzerhandbücher, Weißbücher, Online-Hilfen und Kurzanleitungen. Dokumentation auf Papier oder in Papierform ist immer seltener geworden. Die Dokumentation wird häufig über Websites, Softwareprodukte und andere Online-Anwendungen verbreitet.

  Wo werden gescannte dokumente gespeichert mac

Was gehört zu einer guten Dokumentation?

Verfassen Sie eine umfassende Dokumentation, die alle Aspekte des Projekts ausführlich beschreibt. Schreiben Sie eine Dokumentation, die überschaubar ist. Schreiben Sie eine Dokumentation, die Beispiele für die Verwendung der Software enthält. Schreiben Sie eine Dokumentation, die Wiederholungen enthält, wenn dies sinnvoll ist.

Beispiel für eine technische Dokumentation

Die Dokumentation ist ein wesentlicher Bestandteil, um ein Open-Source-Projekt für die Benutzer nützlich zu machen. Sie ist jedoch nicht immer die oberste Priorität der Entwickler, da sie sich vielleicht mehr darauf konzentrieren, ihre Anwendung zu verbessern, als den Nutzern zu helfen, sie zu verwenden. Deshalb ist es für Entwickler so wertvoll, die Veröffentlichung der Dokumentation zu erleichtern. In diesem Tutorial zeige ich Ihnen eine Möglichkeit, dies zu tun: die Kombination des Docsify-Dokumentationsgenerators mit GitHub Pages.

Standardmäßig fordert GitHub Pages die Benutzer auf, Jekyll zu verwenden, einen Generator für statische Websites, der HTML, CSS und andere Webtechnologien unterstützt. Jekyll generiert eine statische Website aus Dokumentationsdateien, die im Markdown-Format kodiert sind, das von GitHub aufgrund seiner .md- oder .markdown-Erweiterung automatisch erkannt wird. Diese Einrichtung ist zwar schön, aber ich wollte etwas anderes ausprobieren.

Glücklicherweise unterstützt GitHub Pages HTML-Dateien, was bedeutet, dass Sie auch andere Tools zur Website-Erstellung verwenden können, darunter Docsify, um eine Website auf der Plattform zu erstellen. Docsify ist ein MIT-lizenziertes Open-Source-Projekt mit Funktionen, die es einfach machen, eine attraktive, fortschrittliche Dokumentationsseite auf GitHub Pages zu erstellen.

Beispiel für Software-Dokumentation

Fast alle sind sich einig, dass eine gute Dokumentation für den Erfolg von Softwareprojekten wichtig ist, und doch haben nur sehr wenige Projekte tatsächlich eine gute Dokumentation. Selbst erfolgreiche Projekte haben oft nur eine unzureichende Dokumentation.

  Word 2016 leeres dokument vorlage

Die gute Nachricht ist, dass diese beiden Probleme gelöst werden können, wenn man versteht, wie Dokumentation funktioniert, und dass es vier verschiedene Arten von Dokumentation gibt – mit vier verschiedenen Funktionen. Die vier Arten von Dokumentation sind:

Anhand von Beispielen aus dem wirklichen Leben werde ich die wichtigsten Funktionen von Dokumentationen aufzeigen und erläutern, wie sie sich auf verschiedene Arten der Erstellung von Dokumentationen übertragen lassen. Die Umsetzung in die Praxis ist einfach, wenn man einige grundlegende Richtlinien kennt. Die Vorteile sind enorm und mit einem Minimum an Aufwand zu erreichen.

Ich werde nicht über Dokumentationswerkzeuge oder -software oder andere Themen sprechen, die bereits an anderer Stelle ausführlich behandelt wurden, sondern über einige vernachlässigte und schlecht verstandene Aspekte der Dokumentation, die Ihre Softwareprojekte und Teams erfolgreicher machen werden.

Wie man eine Projektdokumentation schreibt

Die Leute sehen sich den Code manchmal gerne an. Sie könnten daran interessiert sein, Fehler im Code zu melden, wenn sie Probleme gefunden haben. Machen Sie es den Leuten, die etwas zum Projekt beitragen wollen, so einfach wie möglich. Ich denke, der Python Guide leistet gute Arbeit mit dem Link zum Code-Teil.

Viele Leute haben die gleichen Probleme. Wenn das immer wieder vorkommt, sollte man wahrscheinlich die Dokumentation oder den Code verbessern, damit die Probleme verschwinden. Es gibt jedoch immer Fragen, die zu Ihrem Projekt gestellt werden, Dinge, die nicht geändert werden können, usw. Dokumentieren Sie diese, und halten Sie sie auf dem neuesten Stand. FAQs sind in der Regel veraltet, aber wenn sie gut gemacht sind, sind sie eine goldene Ressource. Tastypie hat mit seinem “Kochbuch”-Konzept gute Arbeit geleistet.

  Dokumente mit mehreren bearbeiten

Normalerweise haben die Leute Standards dafür, wie sie erwarten, dass Dinge in ihren Projekten erledigt werden. Sie sollten diese dokumentieren, damit die Leute, die den Code schreiben, die Dinge in der Norm des Projekts tun können. Open Comparison leistet in dieser Hinsicht hervorragende Arbeit.

Sobald die Leute herausgefunden haben, ob sie Ihren Code benutzen wollen oder nicht, müssen sie wissen, wie sie ihn bekommen und zum Laufen bringen können. Hoffentlich sollte Ihre Installationsanleitung für den einfachsten Fall nur ein paar Zeilen umfassen. Eine Seite, die weitere Informationen und Warnungen enthält, sollte von hier aus verlinkt werden, falls nötig. Ich denke, dass wir bei Read the Docs in dieser Hinsicht gute Arbeit leisten.

Esta web utiliza cookies propias para su correcto funcionamiento. Al hacer clic en el botón Aceptar, acepta el uso de estas tecnologías y el procesamiento de tus datos para estos propósitos. Más información
Privacidad