Dokumentieren Sie den Teufel aus allem heraus.
Vor kurzem gab es auf Slashdot einen Thread zum Starten der Dokumentation, der mich dazu inspirierte, meine Gedanken zur Dokumentation niederzuschreiben.
Meine wichtigsten Punkte waren:
Prinzip Nr. 1: Es wird niemals getan
Die Dokumentation ist ein ständiger Aufwand, der immer hinter dem zurückbleibt, was in der Produktion ist. Änderungen werden ad-hoc vorgenommen, Dinge verschoben oder eingestellt oder nach dem Zufallsprinzip in Betrieb genommen. Dokumentation wird nie aufholen.
Sie müssen den Rechnungszahlern den Wert der Zeit (und damit des Geldes) für die Aktualisierung der laufenden Dokumentation verkaufen. Häufig lauten diese Unterhaltungen wie folgt: "Erinnerst du dich, als ich $ TIME damit verbringen musste, herauszufinden, wie $ THING kaputt war? Nun, als ich fertig war, gab es diese technische Notiz, in der $ THING genau beschrieben wurde, damit der nächste Kerl nicht mitkommt Ich muss alles herausfinden. "
Sie müssen es tun, obwohl Sie nie fertig werden.
Prinzip 2: Die einzige Sache, die schlimmer ist als keine Dokumentation, ist die falsche Dokumentation
Dies ist eher eine Binsenweisheit als ein Prinzip. Die Dokumentation kann Sie in den falschen Sinn wiegen, dass sich etwas in einem bekannten Zustand befindet, und dass Sie, wenn etwas schief geht, sofort damit beginnen können, es zu beheben.
Es ist wichtig, dieses Problem anzuerkennen.
Prinzip 3: Sie schreiben eine Dokumentation für Ihren Nachfolger
Die Wahrscheinlichkeit ist 95% von allem, was Sie dokumentieren, worauf Sie sich nie wieder beziehen müssen. Dokumentation ist eine Sammlung von Weisheiten für die Zukunft, nicht für Sie. Sie müssen also davon ausgehen, dass Ihr Publikum nur wenig oder gar nichts über die Besonderheiten weiß, wie die Dinge so sind, wie sie sind.
Und es wird einen Nachfolger geben. Ich weiß nichts über dich, aber ich habe nicht vor, für den Rest meines Lebens in diesen speziellen Umgebungen zu sein. Gelegenheiten kommen und gehen, und wenn sie kommen, gehst du manchmal. Aber das Leben geht hinter dir weiter, und je ruhiger du für deinen Nachfolger leben kannst, desto besser. Andernfalls könnten Sie eine Ansammlung ehemaliger Kunden haben, die leise schmeichelhafte Dinge über Sie sagen. Ich möchte sagen, dass es die gleichen 50 Leute sind, die überall in der IT in Ottawa arbeiten, weil man ihnen überall begegnet. Wenn Sie Ihrem Nachfolger helfen, können Sie in Zukunft möglicherweise Türen öffnen.
Bis zu einem gewissen Grad gibt es immer ein gewisses Maß an "Schuld dem Vorgänger", wenn Probleme auftauchen. Das gehört zum Geschäft. Ich habe es selbst gemacht. Aber bei mehreren Gelegenheiten, als ich den vorherigen Typen als eine Art Idioten verprügelt hatte, habe ich ansonsten erfahren, dass er wirklich seine Tat zusammen hatte und mehr über das wusste, was los war, als ich es damals tat.
Prinzip 4: "Warum" ist oft wichtiger als "Wie"
Wenn die meisten von uns ein System betrachten, denken sie, warum zum Teufel ist das so? Es gibt fast immer sehr spezifische Gründe für die getroffenen Konfigurationsentscheidungen. Unter diesen Umständen gibt das "Warum" das "Wie" vor und Sie müssen sicherstellen, dass der Leser die spezifischen Probleme versteht, die bei der Untersuchung der Rauchreste Ihrer Lösung gelöst werden.
Prinzip # 5: Es muss einfach sein oder du wirst es nicht tun
Dies bedeutet, dass Sie sich Ihrer Werkzeuge sowie derer, die Ihre Werkzeuge verwenden, sehr bewusst sein müssen.
Es muss einfach sein, die Dinge auf dem neuesten Stand zu halten. Wenn Sie sich anstrengen müssen, werden Sie Ausreden finden, um dies zu vermeiden, wenn es am besten ist, was unmittelbar nach einer Änderung der Fall ist.
Wenn Ihre Werkzeuge für andere nicht einfach zu verwenden sind, werden sie sie nicht verwenden. Dies kann in einer Teamumgebung besonders lähmend sein, da je größer das Team ist, desto wahrscheinlicher ist es, dass Sie auf ein Teammitglied treffen, das Ihre Werkzeugauswahl nicht mag.
Persönlich mag ich ein Wiki für Dokumente. Das Problem ist jedoch, dass ein Wiki Ihnen keine Struktur aufzwingt, sodass die Struktur von außen auferlegt werden muss. Dies führt immer irgendwo zu Konflikten, da jemand anderes eine bessere / andere Idee hat.
An einigen Stellen habe ich Word- und Visio-Dokumente verwendet, die als PDF "veröffentlicht" wurden, wobei das "neueste" PDF als maßgeblich gilt. Dies ist insofern gut, als Sie dann eine Sammlung haben, die Sie Ihrem Arbeitgeber / Nachfolger übergeben können. Wenn die PDF-Dateien korrekt datiert sind, können sie eine historische Aufzeichnung dessen enthalten, was passiert ist, obwohl eine solche Aufzeichnung nicht einfach zu durchsuchen ist. Es ist schlimm, dass ich Word oder Visio nicht mag und gezwungen bin, ein grundlegendes Verständnis dieser Tools zu erlangen, um die Ideen effektiv zu kommunizieren.
Mein jetziger Arbeitgeber spielt mit der Idee von Word-Dokumenten in einem Sharepoint-Portal. Wir müssen nur sehen, wie weit wir dort sind