Projektdokumentation

Sie sollte alle Aspekte enthalten, die der Entwickler wissen muss und die er nicht direkt von der Code. Dazu gehören Dos und Don'ts bei der Entwicklung, vollständige Anweisungen für die Bereitstellung, Beschreibungen der externen Integration und so weiter. Dieser Beitrag führt Sie durch die Erstellung einer aussagekräftigen, schönen und lesbaren README-Datei für Ihr Projekt.

Eine gute Einführung für eine gut vorbereitete Projektdokumentation finden Sie auf github guides: https://guides.github.com/features/wikis/. Darin heißt es, dass "README nur die notwendigen Informationen für Entwickler enthalten sollte, um mit dem Projekt zu beginnen und dazu beizutragen".

Vor diesem Hintergrund stellen wir Ihnen eine Liste von Komponenten und bewährten Verfahren vor, die wir bei Codest für die Erstellung von Projektdokumentationen anwenden.

Kurze Einführung

- Titel des ProjektsDies ist ein Muss für jede README.

- StatusabzeichenWenn Sie externe Messungen der Codequalität, automatisierte Tests oder andere Tools verwenden, ist der Anfang des Dokuments ein guter Ort, um anderen zu zeigen, ob sie funktionieren.

- Beschreibung: Fügen Sie einige Sätze über das Projekt ein, um den Hauptzweck und die Aufgaben des Projekts kurz zu beschreiben.

Inhaltsübersicht

Ein Inhaltsverzeichnis kann für lange Dokumentationsdateien nützlich sein, aber wenn Ihre README recht kurz ist, ist es nicht notwendig.

Allgemeine Informationen

- Über den Abschnitt: Dies sollte eine detailliertere Beschreibung des Projekts sein - sie kann Informationen über Benutzer, ihre Rollen, einige verwirrende Fälle und Screenshots usw. enthalten.

- Mockups: ein Ort für Links zu UI/UX-Mockup-Ressourcen, falls vorhanden.

• Andere Informationen wie Zugang zu Servern oder Integration mit externen APIsBeispiele sind die URL-Adresse einer Staging-Instanz, gemeinsame, nicht sensible (!) Zugangsdaten, Links zur Dokumentation, einige Anleitungen, usw.

Einrichtung

- AnforderungenVoraussetzungen: Voraussetzungen, die erfüllt sein müssen, bevor mit der Einrichtung einer Anwendung begonnen wird, z. B. die Installation externer Tools.

- Einrichtung: eine Schritt-für-Schritt-Anleitung, die Sie befolgen müssen, um das Projekt zum Laufen zu bringen.

- Einstellungen: beschreiben, wo lokale Einstellungen gespeichert werden, und geben Hinweise, wie Sie Ihre eigenen Einstellungen erhalten können.

- Lokale Konfiguration: Wenn es einige Fälle für die lokale Einrichtung gibt, ist dies ein guter Ort für eine Erklärung.

Entwicklung

Dieser Abschnitt ist ein idealer Ort für Anweisungen wie die Entwicklung von Funktionen, Fehlerbehebungen, Hotfixes, allgemeine Funktionen, Tests, Styleguides, Code-Organisation, andere im Projekt verwendete Entwicklungswerkzeuge (z. B. Wächter oder Docker) und so weiter. Vergessen Sie nicht, alle Regeln zu erwähnen, die jeder Team Mitglied wissen sollte.

Einsatz

Geben Sie klare Schritt-für-Schritt-Anweisungen für jede Umgebung und alles, was man bei der Bereitstellung wissen sollte.

Andere Ideen für separate Abschnitte

- API-Dokumentation

- Changelog

- Externe Ressourcen: ein Ort für alle Arten von Links, die hilfreich sein können.

- Anwendungsstapel: eine Liste der im Projekt verwendeten Anwendungsstacks - kann eine kurze Beschreibung und den Namen des Anbieters enthalten.

Team

Es ist umstritten, ob es notwendig ist, die aktuellen Mitglieder des Projektteams anzuzeigen (github bietet standardmäßig eine vollständige Liste der Mitwirkenden), aber es ist immer schön, wenn Sie Ihren Namen als einen der Autoren eines Projekts sehen. Wenn Sie dies tun, halten Sie es so aktuell wie möglich.

Ein paar letzte Worte

Denken Sie daran: Jedes Projekt ist einzigartig und so ist auch seine Dokumentation. Es gibt keine Patentlösung für das Schreiben einer README. Befolgen Sie einfach die allgemeinen Tipps, und das Wichtigste ist, dass Sie immer an das Refactoring denken, das auch mit der README verbunden ist. Es ist immer eine gute Idee, das Dokument als Ganzes zu betrachten und es zu überdenken, wenn etwas anders dargestellt werden muss.

Und noch etwas: "Anweisungen" sind der Schlüssel, also schreiben Sie sie oft. Ich danke Ihnen!

Lesen Sie mehr:

• Prinzip offen-geschlossen. Muss ich es jemals anwenden?
• Wie schreibt man einen guten und hochwertigen Code?
• Vuelendar. Ein neues Projekt von Codest auf der Grundlage von Vue.js