Dokumentieren Sie Ihre Projekte mit Daux.io

() translation by (you can also view the original English article)

Final product image — What You'll Be Creating

Die Dokumentation eines Projekts kann ein Ärgernis sein, muss es aber nicht sein. Es gibt eine ganze Reihe von Werkzeuge, um die Arbeit zu erledigen - ich benutze Daux.io wegen seiner Flexibilität oft.

In diesem Artikel zeige ich Ihnen, warum Sie dokumentieren sollten, wie Sie Daux.io bekommen können und wie Sie es jetzt verwenden können, um Ihre Projekte viel besser zu machen.

Warum wird Dokumentation benötigt

Das Schreiben der Dokumentation für Ihr Projekt könnte die wichtigste Entscheidung sein, die Sie treffen. Der Grund, warum das bei webbasierten Projekten oft übersehen wird, ist, dass nicht viel auf dem Spiel steht.

Nehmen Sie zum Beispiel eine Boeing 787. Dieses Produkt verfügt über umfangreiche Dokumentationen, die alle Aspekte vom Design bis zur Wartung abdecken. Es gibt sogar ein fast 150-seitiges Handbuch, das die 787 Merkmale dokumentiert, die bei der Planung von Flughäfen berücksichtigt werden müssen.

Warum sollte ein Flugzeug eine weitreichende Dokumentation haben, während eine Website das nicht tut?

Ich glaube, es gibt drei Hauptgründe:

Es ist viel mehr Geld involviert
Sicherheits-Bedenken
Größenprobleme

Websites haben selten Sicherheitsbedenken, aber sobald sich Geld oder Geld erholt, können Sie sicher sein, dass die Dokumentation auftaucht. Alle großen Projekte wie Twitter und Facebook haben erstaunliche Mengen von Informationen für Entwickler, Inhouse-und Drittanbieter gleichermaßen.

Websites, die viel Geld verdienen, wählen oft auch gute Dokumentation. Die Idee ist, dass, wenn etwas geändert werden muss, kann jeder auf die Dokumentation verweisen und die Website ist viel weniger wahrscheinlich, Geld aufgrund von Ausfallzeiten zu verlieren.

Bedeutet das, dass Sie ohne Dokumentation für ein kleineres Projekt auskommen? Sicher ist es, die Frage ist: sollten Sie?

Die Vorteile der Dokumentation

Die Dokumentation bietet einen gemeinsamen Referenzrahmen für ein Projekt. Der Nutzen davon ist ziemlich offensichtlich, wenn man in einem Team arbeitet, aber es wird übersehen, wenn jemand alleine arbeitet.

Wenn Sie Ihre lebenden Gebäudewebseiten bilden, sind die Chancen, dass Sie mindestens ein paar Jahre pro Jahr bauen. Werden Sie sich daran erinnern, wie eine Website, die Sie im Januar erstellt haben, automatisch ihren Inhalt twittert, wenn Sie im nächsten August darauf schauen? Was ist, wenn ein Unternehmen Sie auffordert, ein Projekt an einen anderen Entwickler zu übergeben? Sie verbringen möglicherweise jeden Morgen eine Stunde damit, Fragen zu Ihrem Code für den nächsten Monat zu beantworten.

Selbst der konsistenteste Kodierer ist inkonsistent. Wenn wir wachsen und lernen, neigen wir dazu, unsere Arbeitsweise zu verändern. Vielleicht haben Sie ein Build-Werkzeug wie Gulp in Ihren Arbeitsablauf eingeführt, vielleicht haben Sie angefangen, objektorientiertes PHP zu verwenden.

Dokumentation kann auch Situationen erklären, die im Code selbst nicht offensichtlich sind. Sie haben vielleicht absichtlich eine untergeordnete Lösung gewählt, einfach weil Sie gebeten wurden, etwas schnell zu tun, und das Ende die Mittel rechtfertigte. Das kann der Dokumentation hinzugefügt werden, vielleicht als eine Aufgabe, um später zu aktualisieren.

Dokumentieren mit Daux.io

Daux.io kann einige Leute zuerst verängstigen, weil es nicht einfach HTML ist, es kann nur mit einem Server in der Vorschau angezeigt werden. Es ist jedoch ganz einfach, alles einzurichten, und sobald Sie diese Hürde genommen haben, ist die Nutzung einfach und flexibel.

Daux.io bekommen

Der einfachste Weg, Daux.io zu bekommen, ist es von Github herunterzuladen. Sie können das Paket mit der Schaltfläche Herunterladen ZIP in der rechten Seitenleiste herunterladen. Wenn Sie ein erfahrener Github-Benutzer sind, können Sie es klonen, oder Sie können es sogar von Packagist via Composer herunterladen.

Wenn Sie von Github herunterladen, sollten Sie mit einem Ordner namens "daux.io-master" enden.

Benennen Sie diese in "Dokumentation" um und verschieben Sie sie zur besseren Übersichtlichkeit auf Ihren Desktop. Um Ihre Dokumentation zu schreiben, brauchen Sie eigentlich nichts. Sie können die Markdown-Dateien in jedem Editor bearbeiten und einen Befehl verwenden, um alles in HTML umzuwandeln, um sie einfach zu teilen. Es ist jedoch am besten, unsere Arbeit im Vorhinein zu sehen, also werden wir uns darauf vorbereiten.

Vorschau der Dokumentation

Um eine Vorschau der Dokumente anzuzeigen, benötigen wir einen Server. Glücklicherweise ist alles im Projektordner von Daux.io vorhanden, wir brauchen nur die Voraussetzungen, um den Server auszuführen: npm und Grunt.

Installation von npm und Grunt

Der einfachste Weg, um npm (Node Package Manager) zu greifen, ist die Installation von Node. Gehen Sie zur Node-Website und laden Sie das Installationsprogramm herunter. Nach der Installation sollten Sie den Befehl npm im Terminal (unter Linux/OS X) oder in der Eingabeaufforderung (Windows) verwenden können.

Kurzer Hinweis: Ich werde auf die Eingabeaufforderung unter Windows und das Terminal unter Linux/OS X mit dem gleichen Wort verweisen: Terminal.

Das nächste, was Sie brauchen, ist Grunt. Grunt wird tatsächlich über npm installiert. Wenn Sie den letzten Schritt bereits abgeschlossen haben, sollte es super einfach sein. Öffnen Sie das Terminal und geben Sie den folgenden Befehl ein:

1	npm install -g grunt-cli

Sie haben nun die Basiswerkzeuge, die Sie benötigen, um loszulegen. Wenn Sie neu bei npm sind, empfehle ich dringend, mehr darüber zu erfahren. Es ermöglicht Ihnen die einfache Installation von Werkzeugen und Sie müssen Node.js nicht unbedingt wissen, um Werkzeuge zu verwenden, die mit npm funktionieren (wie Grunt).

Alles, was Sie bisher brauchen, ist nur notwendig, wenn Sie diese Werkzeuge noch nicht installiert haben. Unabhängig davon, wie viele Instanzen von Daux.io-Dokumentationen Sie haben, müssen Sie das nicht erneut tun.

Tipp: Erfahren Sie mehr über Befehlzeilen-Werkzeuge, indem Sie der Anfängerserie The Command Line for Web Design von Kezz Bracey folgen.

Windows-Benutzer: Installieren von PHP

Dieser Schritt ist nur für Windows-Benutzer, OS X und die meisten Linux-Distributionen mit vorinstalliertem PHP, also wenn Sie auf diesen Plattformen sind, können Sie diesen Abschnitt überspringen. Leider ist die Installation der PHP-Befehlszeile in Windows ein wenig mühsam, hier ist der Rundown.

Gehen Sie weiter zur PHP-Herunterladen-Seite und greifen Sie auf die Version von PHP zu, die Sie möchten. Ich habe die Version "VC11 x86 Non Thread Safe" beim Testen verwendet. Ich habe dieses Archiv heruntergeladen und in meinen Stammordner C:/ extrahiert und den resultierenden Ordner in "php" umbenannt. Am Ende des Prozesses sollten Sie einen Ordner namens "php" in Ihrem Hauptverzeichnis C:/ haben, der Ordner sollte irgendwo eine "php.exe" enthalten.

Als nächstes müssen wir sicherstellen, dass der PHP-Befehl von überall ausgeführt werden kann. Unter Windows 7 besteht die einfachste Möglichkeit darin, zum Startmenü zu gehen, klicken Sie mit der rechten Maustaste auf Computer und wählen Sie Eigenschaften. Klicken Sie in der linken Seitenleiste auf Erweiterte Systemeinstellungen. Klicken Sie auf die Registerkarte Erweitert und dann auf die Schaltfläche Umgebungsvariablen unten.

Pfad auf Windows bearbeitenSie müssen auf den Pfad im oberen Bereich klicken und dann bearbeiten. Am Ende des Werts fügen Sie einen Ordnerverweis hinzu, etwa so: "C:\Users\Dani\ environment". Das sollte ein Ordner in Ihrem eigenen Benutzerordner sein. Sobald Sie fertig sind, speichern Sie alles und erstellen Sie diesen Ordner. (Wenn Sie eine andere Windows-Version verwenden, werfen Sie einen Blick auf Computerhope. Dort wird aufgeführt, wie Sie das in mehreren Versionen tun können).

In diesem Ordner erstellen Sie eine Datei namens "phppath.cmd". Bearbeiten Sie diese Datei mit einem beliebigen Texteditor und fügen Sie folgenden Inhalt hinzu:

1	PATH=%PATH%;C:\Users\Dani\environment
2	php -v

Wenn Sie fertig sind, navigieren Sie in diesen Ordner über die Eingabeaufforderung, indem Sie cd%userprofile%/ environment eingeben und den folgenden Befehl ausführen: phppath.

Schließen Sie schließlich die Eingabeaufforderung und öffnen Sie sie erneut. Php sollte nun global verfügbar sein. Auch das müssen Sie nur einmal und nur unter Windows tun.

Einrichten von Daux.io

Navigieren Sie noch in Ihrem Terminal zum Projektordner. Denken Sie daran, dass es zu diesem Zeitpunkt auf unserem Desktop sein sollte. Auf Windows können Sie den folgenden Befehl verwenden, um zum Projektordner zu gelangen:

1	cd %userprofile%/Desktop/documentation

Unter OS X können Sie den folgenden Befehl verwenden:

1	cd ~/Desktop/documentation

Der erste Befehl, den Sie eingeben sollten, ist npm install. Sobald das abgeschlossen ist, führen Sie npm update aus, um sicherzustellen, dass alles auf dem neuesten Stand ist. Diese Befehle installieren und aktualisieren alle Abhängigkeiten von Daux.io. Sie müssen das für jede Instanz von Daux.io tun, die Sie haben.

Die Vorschau ausführen

Wir sind nun endlich bereit, unsere Dokumentation zu betrachten. Das ist nun eine Sache von einem Befehl, Sie müssen nur grunt in das Terminal eingeben (stellen Sie sicher, dass Sie sich beim Ausgeben des Befehls im Dokumentationsordner befinden).

Nach ein paar Sekunden des Nachdenkens sollten Sie so etwas sehen:

Das bedeutet, dass der Server läuft und eine neue Registerkarte in Ihrem Browser bereits geöffnet hat. Ist das nicht der Fall, sehen Sie sich die IP-Adresse neben "Zuhören" im Terminal an und tragen Sie diese in Ihren Browser ein. In meinem Beispiel ist diese IP "127.0.0.1:8085".

Hinweis: In einigen Fällen wird die Registerkarte geöffnet, es wird jedoch "keine Seite gefunden" oder ein ähnlicher Fehler angezeigt. In diesem Fall laden Sie die Registerkarte nach ein paar Sekunden neu, der Server benötigt möglicherweise etwas mehr Zeit für die Initialisierung.

Sie sollten nun die Standarddokumentation im Browser sehen. Die Ansicht, die Sie sehen, wird ad-hoc aus der Dokumentation Markdown-Dateien generiert. Jetzt, wo wir sehen können, was wir tun, schauen wir uns die Dokumentation an.

Dokumentation schreiben

Im Ordner "documentation" sollten Sie einen Ordner "docs" sehen. Das enthält Ihre eigentliche Dokumentation, alles andere ist für Daux.io, um seine Magie zu tun. Daux.io verwendet eine spezielle Namenskonvention, um Ihnen die volle Kontrolle über die Reihenfolge der Seiten zu geben.

Jedes Element auf dieser Seite sollte mit einer Nummer und einem Unterstrich beginnen. Je höher die Zahl, desto niedriger ist die Seite in der Dokumentation. Wenn Sie eine einzelne Seite benötigen, erstellen Sie eine Markdown-Datei (zB: 04_Updating_Plugins), wenn Sie eine hierarchische Struktur von Seiten benötigen, erstellen Sie einen Ordner (zB: 05_Code_Styling).

Der Text hinter der Nummer bestimmt den Namen der Seite in der Dokumentation. Meine vorherigen Beispiele werden "Aktualisierung von Plugins" und "Code Styling". Achten Sie darauf, nur alphanumerische Zeichen und Unterstriche zu verwenden, Unterstriche werden in Leerzeichen umgewandelt.

Von nun an ist das Segeln fließend, Sie müssen lediglich Ihre Dateien in Markdowns Stil bearbeiten. Wenn Sie sich nicht mit Markdown auskennen, werfen Sie einen Blick auf den Markdown Cheatsheet. Es ist im Wesentlichen eine Möglichkeit, ohne HTML-Code Text zu markieren (Überschriften, Links, Bilder usw.).

Wenn Sie einen Abschnitt mit Unterseiten erstellen, die einen Ordner verwenden, können Sie Unterseiten auf die gleiche Weise wie zuvor angeben. Erstellen Sie im erstellten Ordner einzelne Dateien, indem Sie den Dateinamen mit einer Nummer (die der Seite ihre Reihenfolge gibt) und dem Namen, den Sie anzeigen möchten, beginnen.

Zielseiten

Eine weitere nette Sache, die Daux.io Ihnen ermöglicht, ist die Erstellung einer Zielseite für Ihre Abschnitte. Ihre gesamte Dokumentation kann eine Zielseite erhalten, wenn Sie eine "_index.md" - Datei erstellen. Sehen Sie sich das Standardbeispiel an, um ein Gefühl für die Formatierung zu bekommen.

Jeder Abschnitt kann auch eine Zielseite haben. Wenn ein Abschnitt keine Zielseite hat, klickt der Menüeintrag auf oberster Ebene nicht an eine beliebige Stelle, sondern öffnet nur die Unterbereichsliste. Wenn der Eintrag der obersten Ebene eine eigene Seite haben soll, erstellen Sie eine "index.md" - Datei in dem Ordner für den Abschnitt.

Verwalten mehrerer Dokumentationen

Einige Projekte erfordern möglicherweise mehrere Dokumentationen. Eine Website kann eine Endbenutzerdokumentation und eine Entwicklerdokumentation garantieren, die sehr unterschiedliche Informationen enthalten.

Eine Möglichkeit, mehrere Dokumentationsanforderungen zu verwalten, besteht darin, mehrere Instanzen von Daux.io zu erstellen. Das erfordert jedoch, dass Sie den Server separat ausführen und einige Dinge wieder einrichten. Zum Glück gibt es einen besseren Weg!

Sehen Sie sich die Datei "global.json" im Hauptdokumentationsordner an. Wenn Sie dies mit Ihrem Texteditor öffnen, sollten Sie sehen, dass der Parameter docs_directory auf docs gesetzt ist. Erstellen Sie eine Kopie des docs-Verzeichnisses, nennen Sie es "user_docs" und fügen Sie einige andere Dummy-Dateien hinzu, um es von der ursprünglichen Dokumentation unterscheiden zu können.

Ändern Sie nun den Parameter docs_directory in user_docs und laden Sie die Dokumentation in Ihrem Browser neu. Sie sehen nun den Inhalt des neuen Ordners. Auf diese Weise können Sie schnell zwischen den Dokumentationen hin und her wechseln, ohne den Server neu starten oder eine andere Instanz von Daux.io verwenden zu müssen.

Endgültige Dokumentation generieren

Natürlich müssen wir am Ende des Tages unsere Dokumentation verteilen. Das geschieht am besten in HTML-Form und Daux.io hat uns abgedeckt! Führen Sie im Terminal im Hauptverzeichnis Ihrer Dokumentation den folgenden Befehl aus:

1	php generate.php

Dadurch wird ein "statischer" Ordner mit allen HTML-Dateien und Assets erstellt, die zum Anzeigen der Dokumentation erforderlich sind. Sie können diesen Ordner komprimieren und an jemanden senden oder ihn auf einen Server hochladen und dort verlinken.

Erweiterte Projekteinrichtung

Es gibt eine Menge Dinge, die Sie über die Datei "default.json" steuern können. Standardmäßig wird es einen Made by Today-Link in der Seitenleiste geben, zusammen mit einigen Twitter-Links, die Sie entweder nicht benötigen oder die Sie an Ihr Projekt anpassen möchten. Die Daux.io-Hauptseite listet die Optionen auf, die Sie unter "Konfiguration" weiter unten auf der Seite verwenden können. oder beziehen Sie sich einfach auf die "default.json"- Datei.

Sie können "twitter": ["yourrtwittername"] verwenden, um beispielsweise Ihren eigenen Twitter-Link hinzuzufügen. Links können mit dem Parameter links gesteuert werden, hier ist, wie man ein Paar hinzufügt:

"links": {
    "GitHub Repo": "https://github.com/yourgithubrepo",
    "Support": "http://support.myproduct.com",
    "Made by Me": "http://mywebsite.com"
}

Sie finden alle Optionen auf der Daux.io-Hauptseite. Hier ist ein Beispiel für eine vollständige "default.json" - Datei für ein imaginäres Projekt.

{
    "title": "My Project",
    "tagline": "My Stylish Documentation",
    "docs_directory": "docs",
    "valid_markdown_extensions": ["md", "markdown"],
    "repo": "danielpataki/exampleproject",
    "twitter": ["danielpataki"],
    "theme": "daux-blue",
    "breadcrumbs": false,
    "template": "default",
    "clean_urls": false,
    "toggle_code": false,
    "date_modified": false,
    "float": false,
    "links": {
        "GitHub Repo": "https://github.com/danielpataki/exampleproject",
        "Support": "http://support.exampleproject.com",
        "Made by Daniel": "http://danielpataki.com"
    }
}

Schlussfolgerung

Das Einrichten von Daux.io mag auf den ersten Blick eine entmutigende Aufgabe sein, aber es ist nicht so langwierig, besonders auf Mac/Linux-Systemen, wo das meiste von dem, was wir brauchen, vorinstalliert ist. Wenn Sie nicht an Terminal- und lokale Server gewöhnt sind, kann es eine Weile dauern, bis Sie sich an die Umgebung gewöhnen, aber das wird sich verzehnfachen.

Sobald Sie mit Daux.io auf den Beinen sind, werden Sie feststellen, dass es einfach zu bedienen, flexibel und einfach zu warten ist. Ihr Projekt, Ihr Kunde, Ihre Mitarbeiter und die Endbenutzer Ihres Projekts danken Ihnen für Ihre Bemühungen, und hoffentlich wird Ihre Zeit für die Unterstützung des Projekts minimiert.