Die 10 Gebote der Dokumentation

Toyota ist als die effizienteste Organisation auf dem Planeten außerhalb des menschlichen Körpers bekannt, und eine ihrer Philosophien besteht darin, Dokumentation zu vermeiden. Anstatt einen "Prozess" zu machen, wenn jemand am Fließband mehr Schrauben benötigt, haben sie einfach 5 Behälter auf ihrem Regal und wenn man leer ist, bewegen sie es vom Regal und jemand kommt jede Stunde vorbei und füllt alle Regale auf von der Rückseite. Sie müssen nichts dokumentieren, der Prozess erledigt das für Sie.

Da war ein neuer Artikel über Quartz die über Apples Aufmerksamkeit für Checklisten sprachen.

Es stellt sich heraus, dass der Schlüssel zu Apples Kreativität, Geschwindigkeit und Anpassungsfähigkeit auf seiner Oberfläche das genaue Gegenteil der freizügigen Kreativität ist, die man erwarten könnte. Es ist eine Checkliste ... eine wirklich lange.

Was mich dazu gebracht hat darüber nachzudenken, was meine Philosophie über Checklisten ist. Es ist viel falsch mit Checklisten. Sie sind veraltet. Sie können lang und langweilig und sich wiederholend sein. Wie alle Metriken können sie sich auf die falschen Dinge konzentrieren. Aber all das gilt auch für das Überspringen von Checklisten, oder? Ich meine, das dritte Mal, dass Sie den gleichen Fehler gemacht haben, ist es wahrscheinlich an der Zeit zuzugeben, dass Ihnen die Einhaltung einer Checkliste Zeit gespart haben könnte .

Aber Checklisten sind nur dann gut, wenn sie angewendet werden, und sie werden oft aktualisiert, und Sie sind immer noch in der Laune eines Menschen, der, um ehrlich zu sein, nicht perfekt gebaut ist.

Problem der realen Welt

Wir haben einen Standard Drupal Installieren beginnen wir mit den meisten Kunden, die auf Drupal sind. Dazu gehören Module, Einstellungen, Standardbenutzer und unsere Standardtestdaten. Es war eine Checkliste, aber es war immer veraltet. Dann ging jemand hinein und machte es so spezifisch, dass jeder, der nur über begrenzte Kenntnisse von Drupal verfügte, es tun konnte, also hassten all die eingefleischten Drupal-Leute im Laden es, also nahmen wir das heraus, und dann konnten wir niemanden neu trainieren darauf und nur ältere Drupal-Entwickler konnten ihm folgen, also begannen wir hart zu programmieren Drusch.

Drush bedeutet, dass jeder, der Erfahrung mit Drupal hat, ein paar Codezeilen ausführen kann und alles "magisch passieren" würde. Kein "menschlicher Fehler" mehr, es ist eine Checkliste, aber anstelle eines unordentlichen Menschen, der einer Checkliste folgen wollte, folgte ihm ein Computer.

Das Problem dabei war, dass selbst die einfachste Änderung einen Entwickler benötigte und jede Änderung getestet werden musste und so ziemlich schnell auseinander fiel.

Schließlich stießen wir auf die naheliegende Lösung, die in Drush fest programmiert war und die es schwierig machte, sie zu ändern.

Jetzt haben wir einfach eine Seite namens "Klon mich" oder so ähnlich und wenn wir einen neuen Client haben, kopieren wir ihn einfach. Das Ändern hat früher einen Programmierer und viele andere Aufgaben mit sich gebracht, jetzt kann jeder mit dem Passwort in unserem Team etwas ändern. Wenn ein Designer andere Testdaten wünscht, ändern sie diese und es wird automatisch in unserem nächsten Projekt sein. Wenn ein PM entscheidet, dass wir einen anderen Standardbenutzer für Trainingszwecke benötigen, erstellen sie einen und es wird in unserem nächsten Projekt sein.

Wir hatten das Glück, Gavin für ein paar Jahre hier bei Gravity Switch zu haben. Er hat einiges zu unserer Kultur und unserem Code beigetragen, aber seine Weisheit darüber, wann man Dinge "hacken" soll und wann man sie prozedurieren kann, ist etwas, das sich wirklich verändert, wenn ich an die Dokumentation herangehe.

Gavin hat uns gelehrt, dass guter Code selbstdokumentierend ist.

Die 10 Gebote der Dokumentation

1. Du sollst nicht überdokumentieren - Wenn es länger dauert zu dokumentieren als zu tun, überexzierst du es.
2. Sie sollten vor dem Dokument automatisieren - Nehmen Sie den menschlichen Faktor wann immer möglich heraus.
3. Du sollst das gleiche nicht dreimal durcheinander bringen - Wenn du versagt hast oder das gleiche zweimal herausfinden musst, ist es Zeit für eine Prozedur.
4. Wenn es scheitern wird, lass es scheitern - Die schwierigsten Dinge sind die Dinge, die du am ersten (und sogar am zehnten) Mal vermisst, wenn du sie durchprüfst. Wenn Sie die Wahl haben, einen Prozess zu erstellen, der das Fließband stoppt oder Ihre Site zum Absturz bringt, wenn ein Fehler auftritt oder einen kleinen Fehler verursacht, wählen Sie immer die Website "take down", da das Problem zum ersten Mal auftritt .
5. Du sollst den Prozess dahin bringen, dass man darüber stolpern muss - weil es gefunden werden muss.
6. Own it - Wenn Sie einem Prozess folgen, denken Sie daran, dass Ihre Aufgabe darin besteht, das beste Ergebnis zu erzielen. Es ist nicht der Prozess zu folgen. Steige immer skeptisch und schaue kritisch auf die Ergebnisse.
7. Geben Sie zu, wenn es nicht funktioniert - Manchmal sehen die Dinge gleich aus, aber nicht. In unserer Welt brauchen wir immer Standard-Testdaten, aber der Prozess, um das in WordPress zu erstellen, ist völlig anders als das Erstellen in Drupal, also brauchen wir völlig andere Prozesse.
8. Reparieren Sie es schnell - Wenn Ihr Prozess veraltet ist, ignorieren Sie nicht einfach das Problem und wing es, oder wählen Sie die Teile aus, die Sie folgen möchten. Fix es wie du gehst. In den meisten Fällen dauert es nur ein paar Minuten länger, und diese Minuten werden sich in Stunden verwandeln, wenn Sie oder jemand anderes den Prozess das nächste Mal benutzt.
9. Wählen Sie Ihre Schlachten - Steve Krug (der Meister der Benutzerfreundlichkeit) sagt, dass Sie oft testen sollten. Finde dein größtes Problem. Machen Sie die MINDESTE Menge an Arbeit, die Sie tun können, damit es nicht länger Ihr größtes Problem ist, und wiederholen Sie dann. Sie versuchen nicht, einen kleinen Knick aus dem System zu bekommen, Sie versuchen, das GANZE System besser laufen zu lassen.
10. Revisit - Wenn Sie einen Prozess ein Dutzend Mal verwendet haben und ihn nicht geändert haben, sollten Sie überlegen , wie Sie ihn effizienter gestalten oder automatisieren können.

• ← So entwerfen Sie für mobile Geräte, wenn Sie keine haben
• So optimieren Sie die Zielseite Ihrer Website für Mobilgeräte →