Heute habe ich eine wunderbare Seite für das Projektmanagement endeckt.
Ein wirklich kleine Seite mit nur einer einzigen Seite und nur einem Thema – Zeitschätzung.
Dieses Thema ist so mit der wichtigste für einen guten Projektmanager, da leider immer noch viel zu viele Projekte mit viel zu günstigen Zeiteinschätzungen gestartet werden und sich später alle wundern warum alles länger dauert als geplant.
Hier nun die Webseite: zeitschaetzung.de
Hier nun der dritte Artikel meiner Serie “Projektmanagement in kleinen Projekten”. Ich würde mich auch hier wieder über Feedback freuen.
In diesem Artikel geht es wie ihr evtl schon am Titel gesehen haben und das wahnsinnige Interessante und total von allen geliebte Thema Dokumentation. OK, dem einen oder anderen ist der Hauch Sarkasmus aufgefallen.
Jetzt werden sich einige Programmierer denken, ja ich Dokumentiere doch mit PHPDoc, JavaDoc, SonstwasDoc. Ja das ist auch Dokumentieren, aber diese Dokumentation ist nur für euch oder wenn ihr für Kunden arbeitet, deren Programmierer hilfreich. Ich möchte diese Dokumentation auf keinen Fall runterspielen, ich sage nur es ist nur einer von vielen Punkten wo in einem Projekt dokumentiert wird. Dokumentation übersteigt nunmal die einfache Quelltext-Dokumentation bei weitem. In einem guten Projekt kann man alle wichtigen und interessanten Dinge in einer Projektdokumentation nachschlagen.
Denn alle einfachen Handlungen und vorallem auch komplexere Aufgaben in einer Software sollten Dokumentiert sein, so das später sich neue Benutzer sehr einfach in das Stück Software einlesen können. Bei kleinen Projekten macht das meist sogar noch einen größeren Ausschlag. Denn wollt ihr jedem neuen User der Software erklären wie man dies, das oder jenes bewerkstelligt?
Hier würde eine gute und vorallem auch aktuelle Dokumentation für den End-User oder den Admin viel Probleme vereinfachen oder sogar lösen. Und aktuell kann ich nicht oft genug sagen und nicht weit genug hervorheben. Denn nichts ist so schlecht wie eine veraltete und dadurch falsche Dokumentation. Sogar keine Dokumentation wäre in diesem Fall besser als eine Falsche, was wir aber natürlich garnicht erst anfangen wollen. Eine veraltete Dokumentation kann zu Fehlbedienungen des Programms und im Extremfall sogar zu Problemen mit dem Programm führen. Nicht nur einfache “Es geht nicht”-Probleme sondern auch “Upps, warum ist das jetzt abgestürzt”-Probleme. Deshalb Dokumentation immer aktuell halten.
So genug zum warum wir Dokumentieren sollten jetzt zum Praktischen Teil, wie wir Dokumentieren wollen. Wie ich bereits erwähnt habe ist die Quelltextdokumentation nur ein Punkt unter vielen in der kompletten Dokumentation. Und da dieser Punkt einer der unter Programmierern bekannteste und auch am besten ausgebaute im Internet ist werde ich mich hier auf einen kurzen Satz dazu beschränken. Macht es, dokumentiert euren Quelltext! So das soll es dazu gewesen sein.
Nun erstmal eine kleine Übersicht was man so alles in einem Projekt dokumentieren kann: Installation, Konfiguration, Updaten, Benutzung als Admin, Benutzung als User, Information für Anpassungen usw. Je nach Projekt kommen dann noch einzelne Handbücher für die einzelnen Benutzerebenen wie Moderatoren oder Redakteure.
Ihr solltet beim Dokumentieren darauf achten das ihr immer schon für die in Entwicklung befindliche Version schreit, so das ihr mit jeder herausgegebenen Version auch gleich die Fertige Dokumentation ausliefern könnt. Und die Dokumentation am besten auch in einem relativ einfachen Format schreiben, so das es auch in der Versionsverwaltung mit aufgenommen werden kann und dort auch gedifft werden kann.
Für das schreiben lohnt sich meist LaTeX oder wenn man den Overkill des lernen von LaTeX nicht haben will gibt es auch noch eine einfache Variante: reStructuredText
So da wir nun wissen was wir wie dokumentieren können gibt es nun noch ein paar Tipps zum Strukturieren der Dokumentation. Die Struktur sollte immer so gehandhabt werden, das alles in Logische Einheiten aufgespalten wird. Klingt logisch aber es sollte erwähnt werden. Wenn sich Themen in der Dokumentation überschneiden, immer auf den entsprechenden Abschnitt in der Dokumentation verweisen und nicht doppelten Text verfassen. Doppelte Text führen beim Updaten der Dokumentation nur dazu das sie im schlimmsten Fall ein und den selben Sachverhalt grundverschieden erklären. Daher wie im Netz, immer verlinken.
Die logischen Bereiche sind nach meiner Erfahrung am besten so kurz wie möglich zu halten und sich wirklich auf die Aufgabe konzentrieren die man gerade beschreibt. Denn derjenige der die Dokumentation liest will nichts davon wissen was man denn noch so alles in Menü X anstellen kann sondern er liest den Abschnitt weil er genau das wissen will was die Überschrift verspricht. Und genau deswegen sollten Überschriften in der Dokumentation, wie eigentlich auch sonst überall, gut gewählt und treffend sein. Denn wenn jemand eine Dokumentation liest, ist es meine Erfahrung, das er etwas ganz spezielles wissen will. Ich persönlich habe noch nie jemanden erlebt der gesagt hat: So ich lese mir mal die Komplette Dokumentation für Ding X durch.
Ein weiterer Tipp ist, wenn ihr ein Grafisches Programm habt, bebildert die Dokumentation denn nach wie vor gilt: Ein Bild sagt mehr als tausend Worte. Und vorallem im Bereich der Softwaredokumentation ist eine bebilderung hilfreich. Aber auch hier gilt wieder sie müssen IMMER Aktuell sein und das wirkliche Abbild des Programms zeigen, den auch hier kann wieder extrem viel Frust entstehen wenn die Bilder in der Dokumentation nicht mit denen die man als Benutzer selber sieht übereinstimmen.
Also nun zu guter letzt eine Zusammenfassung für alle die, die es nicht ertragen können meine schreklichen Schachtelsätze zu lesen.
1. Für alle Benutzergruppen (einzeln) Dokumentieren
2. Dokumentation IMMER aktuell halten
3. Screenshots und Bilder sind immer gut
4. Wie alles, auch die Dokumentation Versionieren
5. Dokumentation immer kurz und treffend halten
und der wichtigste Punkt: Dokumentiert, tut es einfach
Zum Thema Dokumentation von IT Umgebungen habe ich schon vor längerem ein Super Tool gefunden. I-dotit, kurz für I documentate it. Aus meiner Sicht ein wirklich gutes Tool um eine CMDB, eine Change Management Database, aufzubauen.
Wir haben es damals eingesetzt als wir, bei einem ehemaligen Arbeitgeber, eine neue Serverumgebung installiert haben. In dem Tool konnte man JEDES Detail eines Servers und dessen Verkabelung dokumentieren. Und auch dessen Position in einem Rackschrank.
Auflösung ging im Groben auf diese Weise Gebäude enthält Raum enthält Schrank enthält Server enthält Netzwerkkarte enthält Interface enthält Port enhält IP Adresse. Diese ist mit einem Switch Verbunden in einem gewissen Netzwerk. Der Switch hat ein Stromanschluss der an eine KVM angebunden ist. So weiter will ich jetzt euch nicht nerven aber ihr merkt worauf ich hinaus will.
Also aus meiner Sicht wirklich ein Blick wert für alle die unter euch die sich mit der Verwaltung von Rechnern konfrontiert sehen.
Zugegeben am Anfang werdet ihr etwas Fluchen alles einzutragen, aber ab Version 1.0 soll eine XML Schnittstelle vorhanden sein über die Daten eingetragen werden. Ihr könnt aber auch, wenn ihr bereit seid Geld auszugeben, ein Plug-In dazukaufen das per H-Inventory Rechner in das System einliest.
Auf jeden Fall lohtn es sich ab sagne wir mal 2-3 Server oder 5-6 normalen Client PCs.
Viel Spaß beim ausprobieren.
Hier nun der zweite Artikel meiner Serie “Projektmanagement in kleinen Projekten”. Ich würde mich auch hier wieder über Feedback freuen.
Zu aller erst will ich erst einmal sagen das ich diese Ordnerstruktur für Web basierte Projekte mit PHP und Javascript erstellt habe und nutze. Ich weiß nicht in wie weit diese Struktur für andere Programmiersprachen/Verwendungszwecke tauglich ist, daher dieses kleine Vorwort.
Nun zur Struktur. Da jedes Projekt auch eine Dokumentation haben sollte sollte hier zu aller erst ein Ordner für die Dokumentation erstellt werden. Ja OK ein einfacher Ordner – man der muss mich für blöd halten. Nein, aber viele vergessen einfach das Dokumentation zum Projekt gehört und speichern ihre Dokumente dann einfach mal hier und mal dort, anstatt sie gleich mit in die Projektstruktur mit aufzunehmen. Das hat wiederum den Vorteil das die Dokumentation auch mit in der Versionskontrolle liegt und dadurch auch ältere Versionen wiederherstellbar sind, aber dazu mehr im Versionskontrolle Artikel.
Den Dokumentationsordner teile ich in meinen Projekten meist noch in einen Ordner für das Datenbankdesign und die eigentliche Dokumentation auf.
Nun zur Struktur für den Quelltextbaum des Projekte. In diesem erstelle ich meist einen Ordner, da ich ja hier von Webprojekten rede, der die eigentliche Webroot ist. Diesen nenne ich meist public oder htdocs je nach dem. Einen Ordner für Externe Bibliotheken wie PEAR, Zend Framework oder sonstige Frameworks. Einen Ordner für Selbstgeschriebene Klassen und Funktionen, einen für Konfigurationsdateien und zu guter letzt einen Ordner für Temporäre Dateien wie Cachedateien oder Uploads. Diese Grundstruktur halte ich für alle meine Projekte ein und habe bisher immer wieder mitbekommen das diese Variante für mich die beste ist.
Meist erstelle ich auch noch eine extra Struktur im Webroot Ordner für die Dateien die an den User garantiert ausgeliefert werden, wie Bilder, CSS, Javascript und evtl. auch Flash. So kommen neue Dateien immer da hin wo sie hingehören und mich muss nicht lange nach ihnen Suchen.
Neuerdings erstelle ich mir in dem Grundordner, in dem ja schon der Dokumentations und der Quelltext Ordner liegen, noch einen 3. Ordner für Sonstige Dateien die zum Projekt gehören, wie Vorlagen für ein Design, Stockfotos oder Screenshots die als Anregung dienen sollen.
Ordner Struktur
\docs \db \doku \src \extern \libs \temp \public \images \css \js \flash \misc
Ich hoffe dieser kleine Artikel hilft euch ein wenig mit dem Aufbau einer eigenen Struktur für eure Projekte.
Und wie immer – Feedback erwünscht.
Nachdem ich letzte Woche schon über das Onlinetool von Autodesk gebloggt habe, ist mir heute ein weiteres Visio ähnliches Tool unter die “Maus” gekommen. Lovely Charts.
Ich habe mal kurz hinein geschaut und muss sagen es gefällt mir jetzt schon besser als das Autodesk Tool.
Warum? Wegen der schönerem Icons und der einfachere Bedienung. Also evtl. auch ein Blick wert.
Dieses Wochenende werde ich hoffentlich den Artikel zur Strukturierung eines Projektdateisystems Fertigstellen. Diesmal wird es auch ein paar mehr Links und Weiterführende Informationen geben als in meinem Artikel über die Projektstrukturierung auf Papier.
Ich würde mich immer noch über Anregungen was dieses Thema angeht freuen.
Einfach dafür hier ein Kommentar unter dem Artikel hinterlassen.
