So erstellen Sie eine Website oder ein Blog im Jahr 2020 - Kostenlose und einfache Anleitung zum Erstellen einer Website

Die Bedeutung der Dokumentation für Webentwickler

Im Bereich der Entwicklung von Mobil-, Web- und Desktop-Anwendungen oder JavaScript-Bibliotheken spielt die Dokumentation eine wichtige Rolle für den Erfolg der Anwendung. Aber wenn Sie jemals Dokumentation gemacht haben, werden Sie mir zustimmen, dass dies die unbeliebteste Sache ist, die Entwickler tun.

Im Gegensatz zum Schreiben von Code (wozu sich Entwickler verpflichtet haben) sollte die Dokumentation für . leicht verdaulich sein. Technisch gesehen müssen wir eine Maschinensprache (Code) in eine für Menschen verständliche Sprache übersetzen, was schwieriger ist, als es scheint.

Auch wenn es sehr mühsam sein kann, ist das Schreiben von Dokumentationen wichtig und kommt Ihren Benutzern, Ihren Kollegen und insbesondere Ihnen selbst zugute.

Eine gute Dokumentation hilft Benutzern

Dokumentation hilft dem Leser. verstehen, wie Code funktioniert, offensichtlich. Viele Entwickler machen jedoch den Fehler, davon auszugehen, dass die Benutzer der Software kompetent sind.

Daher ist die Dokumentation möglicherweise spärlich und lässt viele der wesentlichen Elemente aus, die sie von Anfang an hätte enthalten sollen. Wenn Sie die Sprache beherrschen, können Sie Dinge aus eigener Initiative herausfinden; Wenn nicht, dann sind Sie verloren.

Die für Benutzer bestimmte Dokumentation besteht in der Regel aus praktischer Anwendung oder „How to“. Die allgemeine Faustregel beim Erstellen von Dokumentationen für allgemeine Benutzer lautet: es sollte klar sein. Es ist vorzuziehen, menschenfreundliche Wörter anstelle von Fachbegriffen oder Fachjargon zu verwenden. Auch reale Anwendungsbeispiele würden uns sehr freuen.

Ein gutes Layoutdesign würde Benutzern auch dabei helfen, jeden Abschnitt der Dokumentation zu lesen, ohne ihre Augen zu überanstrengen. Einige gute Beispiele (auch bekannt als meine Favoriten) dienen der Dokumentation Ohr Und WordPress‘ „Erste Schritte mit WordPress“.

Helfen Sie anderen Entwicklern

Jeder Entwickler hat seinen eigenen Codierungsstil. Aber wenn es darum geht, im Team zu arbeiten, müssen wir oft Codes mit anderen Kollegen teilen. Es ist also unerlässlich einen Konsens über einen Standard haben um alle auf dem gleichen Stand zu halten. Eine korrekt geschriebene Dokumentation wäre die Referenz, die das Team benötigt.

Aber im Gegensatz zur Endbenutzerdokumentation beschreibt diese Dokumentation normalerweise technische Verfahren Zum Beispiel die Code-Namenskonvention, die zusammen mit Codebeispielen zeigt, wie bestimmte Seiten erstellt werden sollten und wie die API funktioniert. Oftmals müssten wir auch eine Dokumentation inline mit dem Code schreiben (sogenannte Dokumentation), um zu beschreiben, was der Code tut.

Darüber hinaus für den Fall, dass Sie haben neue Mitglieder beitreten Wenn Sie Ihr Team später schulen, könnte diese Dokumentation eine effektive Möglichkeit sein, es zu schulen, sodass Sie ihm keine individuelle Analyse des Codes geben müssen.

Es hilft auch dem Encoder selbst.

Das Lustige am Codieren ist, dass es manchmal so ist Selbst die Entwickler selbst verstehen den Code, den sie geschrieben haben, nicht.. Dies gilt insbesondere dann, wenn die Codes über Monate oder sogar Jahre hinweg nicht geändert wurden.

Ein plötzliches Bedürfnis, die Codes aus dem einen oder anderen Grund zu überprüfen, würde einen dazu bringen, sich zu fragen, was ihnen durch den Kopf ging, als sie diese Codes schrieben. Seien Sie nicht überrascht: Ich war schon einmal in dieser Situation. Dann habe ich meinen Code richtig dokumentiert..

Durch die Dokumentation Ihrer Codes kommen Sie schnell und ohne Frustration zum Ende Ihrer Codes und sparen so viel Zeit, die Sie für Änderungen aufwenden müssen.

Was macht eine gute Dokumentation aus?

Es gibt mehrere Faktoren, die zur Erstellung einer guten Dokumentation beitragen. Einige der wichtigsten sind die folgenden:

1. Gehen Sie niemals davon aus

Gehen Sie nicht davon aus, dass Ihre Benutzer sowohl wissen, was sie wissen, als auch was sie wissen wollen. Es ist immer besser Von Anfang an beginnen unabhängig vom Kompetenzniveau der Benutzer.

Wenn Sie beispielsweise ein jQuery-Plugin erstellt haben, können Sie sich davon inspirieren lassen SlickJSDie Dokumentation von. Es zeigt, wie man den HTML-Code strukturiert, wo man CSS und JavaScript ablegt, wie man das jQuery-Plugin auf seiner grundlegendsten Ebene initialisiert und es zeigt sogar das vollständige endgültige Markup nach dem Hinzufügen all dieser Dinge, was eine Art Selbstverständlichkeit ist. Klugscheißer.

Die Quintessenz ist, dass die Dokumentation mit dem Denkprozess eines Benutzers und nicht eines Entwicklers geschrieben wird. Wenn Sie Ihre eigene Dokumentation auf diese Weise angehen, erhalten Sie eine bessere Perspektive bei der Organisation Ihres eigenen Stücks.

2. Befolgen Sie den Standard

Durch das Hinzufügen einer Dokumentation, die zum Code passt, Verwenden Sie den erwarteten Sprachstandard. Es ist immer eine gute Idee, jede Funktion, die Variablen sowie den von der Funktion zurückgegebenen Wert zu beschreiben. Nachfolgend finden Sie ein Beispiel für eine gute Online-Dokumentation für PHP.

/**
 * Adds custom classes to the array of body classes.
 *
 * @param array $classes Classes for the body element.
 * @return array
 */
function body_classes( $classes ) {
	// Adds a class of group-blog to blogs with more than 1 published author.
	if ( is_multi_author() ) {
		$classes[] = 'group-blog';
	}

	return $classes;
}
add_filter( 'body_class', 'body_classes' );

Im Folgenden finden Sie einige Referenzen zur Formatierung der Dokumentation gemäß Best Practices in PHP, JavaScript und CSS:

Wenn Sie SublimeText verwenden, würde ich die Installation empfehlen DocBlockr Dadurch wird Ihr Code auf intelligente Weise mit der Online-Dokumentation vorab gefüllt.

3. Grafische Elemente

Verwenden Sie grafische Elemente, sie sprechen besser als Text. Diese Medien sind insbesondere dann nützlich, wenn Sie Software mit einer grafischen Oberfläche erstellen. Sie können Zeigeelemente wie Pfeile, Kreise usw. hinzufügen Alles, was Benutzern helfen kann, ohne Rätselraten herauszufinden, wohin sie gehen müssen, um Schritte auszuführen.

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

4. Schnitt

Sie könnten erwägen, einen Teil der Dokumentation in Listen und Tabellen mit Aufzählungszeichen aufzunehmen, da längere Inhalte dadurch für Benutzer einfacher zu scannen und zu lesen sind.

Fügen Sie ein Inhaltsverzeichnis hinzu und unterteilen Sie die Dokumentation in leicht verständliche Abschnitte, sodass jeder Abschnitt für das, was als Nächstes kommt, relevant bleibt. Seien Sie kurz und einfach. Nachfolgend finden Sie ein Beispiel für eine gut organisierte Dokumentation in Facebook. Das Inhaltsverzeichnis führt uns mit einem Klick dorthin, wo wir springen möchten.

5. Überprüfen und aktualisieren

Überprüfen Sie abschließend die Dokumentation auf Fehler und überarbeiten Sie sie bei Bedarf oder wenn wesentliche Änderungen am Produkt, an der Software oder an der Bibliothek vorgenommen werden. Ihre Dokumentation wäre für niemanden von Nutzen, wenn sie nicht zusammen mit Ihrem Produkt regelmäßig aktualisiert wird.