Entwickler, warum Sie die Dokumentation nicht überspringen sollten

Bei der Entwicklung mobiler Apps, Web-Apps, Desktop-Apps oder JavaScript-Bibliotheken spielt die Dokumentation eine wichtige Rolle, die den Entwicklungserfolg der Software bestimmen könnte. Wenn Sie jemals eine Dokumentation erstellt haben, stimmen Sie mir zu, dass dies für Entwickler die am wenigsten bevorzugten Dinge sind.

Im Gegensatz zum Schreiben von Code (wozu sich die Entwickler angemeldet haben) muss und sollte die Dokumentation (die wir nicht gemacht haben) leicht verdaut werden jeder. Technisch müssen wir eine Maschinensprache (Code) in eine für den Menschen verständliche Sprache übersetzen, die härter ist, als es sich anhört.

Auch wenn dies sehr mühsam sein kann, ist das Schreiben der Dokumentation wichtig und bringt Vorteile für Ihre Benutzer, Ihre Kollegen und vor allem für Sie.

Gute Dokumentation hilft Benutzern

Dokumentation hilft dem Leser verstehen, wie ein Code funktioniert, offensichtlich. Viele Entwickler machen jedoch den Fehler, davon auszugehen, dass die Benutzer der Software kompetent sind. Daher kann es sich bei der Dokumentation um dünnes Material handeln, bei dem viele der wichtigsten Elemente, die in der Dokumentation enthalten sein sollten, übersprungen werden. Wenn Sie sich mit der Sprache auskennen, können Sie die Dinge auf eigene Faust herausfinden. Wenn Sie nicht sind, sind Sie verloren.

Die für Benutzer bestimmte Dokumentation besteht in der Regel aus dem praktischen Gebrauch “wie man”. Die Faustregel beim Erstellen von Dokumentation für allgemeine Benutzer ist das es sollte eindeutig sein. Die Verwendung menschenfreundlicher Wörter ist technischen Begriffen oder Fachjargon vorzuziehen. Anwendungsbeispiele werden ebenfalls sehr geschätzt.

Ein gutes Layout-Design würde den Benutzern auch wirklich dabei helfen, jeden Abschnitt der Dokumentation ohne Augenbelastung zu durchsuchen. Ein paar gute Beispiele (meine Favoriten) sind die Dokumentation für Bootstrap und WordPress. “Erste Schritte mit WordPress”.

Es hilft auch anderen Entwicklern

Jeder Entwickler hat seinen eigenen Codierstil. Bei der Arbeit in einem Team müssen wir jedoch häufig Codes mit den anderen Teamkollegen teilen. Also ist es wichtig zu einen Konsens über einen Standard haben um alle auf der gleichen Seite zu halten. Eine ordnungsgemäß geschriebene Dokumentation wäre die Referenz, die das Team benötigt

Im Gegensatz zur Endbenutzerdokumentation wird in dieser Dokumentation jedoch normalerweise beschrieben technische Verfahren Wie bei der Benennung von Codes, die zeigt, wie bestimmte Seiten erstellt werden sollen und wie die API zusammen mit den Codebeispielen funktioniert. Oft müssten wir die Dokumentation auch in den Code schreiben (bekannt als Bemerkungen) um zu beschreiben, was der Code tut.

Darüber hinaus in dem Fall, wo Sie haben neue Mitglieder beitreten Ihr Team später kann diese Dokumentation eine zeitwirksame Methode sein, um sie zu trainieren, sodass Sie ihnen nicht einen 1-zu-1-Code für den Code geben müssen.

Seltsamerweise hilft es auch dem Coder

Das Lustige an der Codierung ist das manchmal Selbst die Entwickler selbst verstehen den von ihnen geschriebenen Code nicht. Dies gilt insbesondere für Fälle, in denen die Codes Monate oder sogar Jahre unangetastet bleiben.

Ein plötzliches Erfordernis, die Codes aus einem oder anderen Grund erneut zu betrachten, würde einen dazu veranlassen, sich zu fragen, was in ihren Gedanken vorging, als sie diese Codes schrieben. Seien Sie nicht überrascht: Ich war schon einmal in dieser Situation. Das ist genau wenn ich wünschte Ich hatte meinen Code richtig dokumentiert.

Indem Sie Ihre Codes dokumentieren, können Sie schnell und ohne Frustration Ihren Codes auf den Grund gehen und so viel Zeit sparen, die für das Einspielen der Änderungen aufgewendet werden kann.

Was macht eine gute Dokumentation aus??

Es gibt verschiedene Faktoren, um eine gute Dokumentation aufzubauen.

1. Nehmen Sie niemals an

Gehen Sie nicht davon aus, dass Ihre Benutzer was wissen Sie wissen auch, was Sie will wissen. Es ist immer besser von vorne anfangen unabhängig vom Leistungsniveau der Benutzer.

Wenn Sie beispielsweise ein jQuery-Plugin erstellt haben, können Sie sich an die SlickJS-Dokumentation halten. Es zeigt, wie man das HTML strukturiert, wo man das CSS und das JavaScript platziert, wie man das jQuery-Plugin auf seiner grundlegendsten Ebene initialisiert, und sogar das vollständige endgültige Markup zeigt, nachdem man all das hinzugefügt hat, was offensichtlich ist.

Unter dem Strich wird die Dokumentation mit dem Denkprozess eines Benutzers und nicht eines Entwicklers geschrieben. Wenn Sie Ihre eigene Dokumentation auf diese Weise betrachten, erhalten Sie eine bessere Perspektive für die Organisation Ihres eigenen Stücks.

2. Befolgen Sie den Standard

Beim Hinzufügen von Dokumentation, die zum Code passt, Verwenden Sie den von der Sprache erwarteten Standard. Es ist immer eine gute Idee, jede Funktion, die Variablen sowie den von der Funktion zurückgegebenen Wert zu beschreiben. Hier ist ein Beispiel für eine gute Inline-Dokumentation für PHP.

 / ** * Fügt dem Array von Body-Klassen benutzerdefinierte Klassen hinzu. * * @param array $ classes Klassen für das body-Element. * @return array * / function body_classes ($ classes) // Fügt Gruppen von Blogs Blogs mit mehr als einem veröffentlichten Autor hinzu. if (is_multi_author ()) $ classes [] = 'Gruppenblog';  $ -Klassen zurückgeben;  add_filter ('body_class', 'body_classes');

Im Folgenden finden Sie einige Referenzen zur Formatierung von Inline-Dokumentation mit bewährten Methoden in PHP, JavaScript und CSS:

PHP: PHP-Dokumentationsstandard für WordPress
JavaScript: UseJSDoc
CSS: CSSDoc

Wenn Sie SublimeText verwenden, würde ich vorschlagen, DocBlockr zu installieren, das Ihren Code geschickt mit Inline-Dokumentation vorbelegt.

3. Grafische Elemente

Verwenden Sie grafische Elemente, sie sprechen besser als Text. Diese Medien sind besonders nützlich, wenn Sie Software mit grafischer Benutzeroberfläche erstellen. Sie können Zeigerelemente wie Pfeile, Kreis oder hinzufügen alles, was den Benutzern helfen kann, ohne Rätselraten herauszufinden, wohin die Schritte gehen sollen.

Im Folgenden finden Sie ein Beispiel aus der Tower-App, von dem Sie Inspiration erhalten können. Sie erklären effizient, wie die Versionskontrolle funktioniert, auf eine angenehme Art und Weise, die sie verständlicher macht als die Verwendung von Nur-Text-Befehlszeilen.

4. Schneiden

Sie sollten in Erwägung ziehen, einige Punkte in der Dokumentation von Listen und Tabellen mit Aufzählungszeichen zu verwenden, da längerer Inhalt für Benutzer einfacher zu scannen und zu lesen ist.

Fügen Sie ein Inhaltsverzeichnis hinzu und teilen Sie die Dokumentation in leicht verdaubare Abschnitte auf, wobei jeder Abschnitt für das, was als Nächstes kommt, relevant bleibt. Halten Sie es kurz und unkompliziert. Nachfolgend finden Sie ein Beispiel für eine gut organisierte Dokumentation in Facebook. Das Inhaltsverzeichnis führt uns dahin, wohin wir mit einem Klick springen möchten.

5. Überarbeiten und aktualisieren

Lesen Sie zum Schluss die Dokumentation auf Fehler und überprüfen Sie sie gegebenenfalls, oder wenn wesentliche Änderungen an Produkt, Software oder Bibliothek vorgenommen werden. Ihre Dokumentation ist für niemanden von Nutzen, wenn sie nicht regelmäßig neben Ihrem Produkt aktualisiert wird.