Projektdokumentationen

von Marco Weber

Zwischen dem Upload und der Abrechnung gibt es eine Aufgabe, die man keinesfalls vernachlässigen sollte: Zu einem abgeschlossenen Projekt gehört eine sauber ausgearbeitete Projektdokumentation.

Da ist es nun – das Web-Projekt. Der Abschluss-Check ist durchgeführt, vom Kunden wurde die Freigabe zur Veröffentlichung erteilt und seit dem Upload auf den Webserver ist sein Internetauftritt weltweit zugänglich von jedermann abrufbar. Damit ist dieser Auftrag also im Prinzip fertig. Bliebe nun noch, die Rechnung zu schreiben und zu hoffen, dass bald darauf der Zahlungseingang verbucht werden kann. Somit wäre damit eigentlich alles in Butter: Haken drunter, Schulter klopfen, und auf geht’s zu neuen Taten.

Wozu eine Dokumentation?
Schöne bunte Internetseiten lassen sich zwar toll am Bildschirm ansehen, aber man kann sie nicht anfassen und sie zeigen nur das Ergebnis der Menge an Hirnschmalz und Zeit, die sowohl von Auftragnehmer- als auch von Auftraggeberseite in oft mühevoller Puzzlearbeit in das Projekt gesteckt wurde. Daher ist es schon aus psychologischer Sicht gewiss ganz vorteilhaft, wenn man dem Kunden nach getaner Arbeit auch wirklich etwas in die Hand drücken kann, anstatt nur eine URL zu nennen. Denn schließlich wird dieser auch gutes Geld für die erbrachte Leistung bezahlen. Seien wir ehrlich: Wenn ich etwas kaufe, möchte ich auch etwas dafür bekommen – und bei virtuellen Gütern tun wir uns doch immer etwas schwerer. Das gleiche Gefühl hatte wohl schon jeder beim Bezahlen von Versicherungen, Provisionen oder Bankgebühren. Lässt man dagegen eine Broschüre oder Visitenkarten drucken, hält man zum Abschluss das Ergebnis greifbar in der Hand.

Mit der Projektdokumentation bietet sich also die Möglichkeit, aus den Dateien im weiteren Sinne eine „Hardware“ zu schaffen, die man dem Kunden zum Abschluss überreichen kann – sauber gedruckt, hübsch aufgemacht und geheftet und vielleicht sogar zusammen mit der bereits erwähnten Rechnung. Das kann dann sicherlich auch positiven Einfluss auf die Zahlungsmoral haben kann.

Eventuell zeigt der Auftraggeber diese Doku sogar Dritten, die von der Website angetan waren, und bringt auf diesem Weg vielleicht einen der nächsten Interessenten ins Haus.
Als Ergänzung sollte dieser Dokumentation auch eine CD beigelegt werden, die den aktuellen Projektstand zur „Offline-Betrachtung“ und als eine Art erstes Backup für den Kunden beinhaltet. Gegebenenfalls können darauf noch ergänzend Originalfotos und Grafiken oder weitere verwendete Daten abgelegt werden.

Nachschlagewerk für eigene Zwecke
Für den Webdesigner oder Entwickler selbst bietet sich beim Erstellen einer Dokumentation nochmals eine zusätzliche Kontrollmöglichkeit, bei der er sich mit dem kompletten Projekt nochmals auseinandersetzen und gegebenenfalls Feinheiten aufdecken und erforderlichenfalls nachbessern kann.

Für den Webdesigner wird die Dokumentation erst zu einem späteren Zeitpunkt wertvolle Dienste leisten. Während der laufenden Projektarbeit ist man mit dem Thema vertraut. Navigation, Farben, Seitenlayout, Fachbegriffe und so weiter hat man gewiss in der Zeit der Vorbereitung und Umsetzung parat oder weiß zumindest sofort, wo man sich diese Informationen abrufen kann. Es folgt das nächste Projekt und noch ein weiteres – und dann werden vielleicht erste Änderungs- oder Ergänzungswünsche des Kunden geäußert. Ist dann bereits einige Zeit verstrichen oder gar der neue Kollege erstmals mit diesem Auftrag betraut, werden die Erinnerungen an die Details immer verschwommener, manche Themen sogar wieder ganz in Vergessenheit geraten. Dies ist der Zeitpunkt, wo das bekannte „Wie-war-das-damals-gleich-noch-mal?“-Syndrom auftaucht und man sich erst einmal wieder ins Thema hinein finden muss. Dann geht die große Sucherei los und ohne ein kompaktes Nachschlagewerk hat man auf jeden Fall die schlechteren Karten, fündig zu werden. Ein Griff zur vorhandenen Doku liefert schnell wichtige Anhaltspunkte und spart damit automatisch zeitlichen Aufwand und schlussfolgernd daraus natürlich auch Geld.

Erstmalig erfordert der Aufbau eines solchen Werks natürlich eine Menge Arbeit – aber das ist bekanntlich mit allen neuen Tätigkeiten so. Baut man dieses Grundgerüst aber geschickt und etwas variabel gestaltbar auf, hat man eine fundierte Vorlage, die übersichtlich strukturiert ist und auf die jeweiligen projektbezogenen Gegebenheiten und Besonderheiten angepasst werden kann. Kein Projekt gleicht dem anderen bis ins Detail – und auch die Kunden sind unterschiedlich in ihren Forderungen und Interessen. Somit wird auch eine Dokumentation, die für die „kleine“ Internetvorstellung eines handwerklichen Betriebs oder eines Angelsportvereins geschrieben ist, etwas anders aussehen, als für den Betreiber eines Shop-Systems oder Fach-Forums.

Welche Themen?
Was gehört nun inhaltlich alles hinein? Nachfolgend werden in dieser – nennen wir’s mal Dokumentation zur Dokumentation – einige Themen und Anhaltspunkte genannt, die als Leitfaden für Aufbau und Gliederung bei der Beschreibung eines Web-Projekts in Frage kommen können.

Umfang, Reihenfolge und die „Tiefe“ des Inhalts sind natürlich jedes Mal von den vorherrschenden Gegebenheiten abhängig und werden daher variieren.

Am Anfang ein Deckblatt
Es klingt banal: Das Heftchen liegt vielleicht irgendwo mal sichtbar auf einem Schreibtisch. Daher sollte auf der ersten Seite zu entnehmen sein, dass es sich um eine Projektdokumentation handelt und zu welchem Thema/Kunden oder welcher URL diese gehört. Ein Screenshot der Einstiegsseite des Webprojekts sorgt für sofortige Wiedererkennung, auch bei einem flüchtigen Blick.

Logisch: ein Hinweis auf den Verfasser mit Logo und Adresse sowie eventuell ein Copyright-Vermerk gehören dort auch, zwar dezent, aber dennoch sichtbar, platziert und erfüllen an dieser Stelle gewiss den Effekt einer Kleinanzeige.

Inhaltsverzeichnis
Wie in jedem vernünftigen Buch oder Magazin üblich, gehört an den Anfang ein Inhaltsverzeichnis mit den enthaltenen Kapiteln, Unterkapiteln und den zugehörigen Seitenzahlen. Damit erhält der Leser einen schnellen Überblick und eine ansprechende Suchmöglichkeit. Schließlich soll die Doku nicht nur ein „Aufsatz über eine Internetseite“ sein, sondern als Werkzeug dienen und die Funktion eines Nachschlagewerks bei Fragen zum Projekt wahrnehmen.

Glossar
Ans Ende der Niederschrift sollte man in Erwägung ziehen, ein Glossar mit anzubieten.
Es gibt Kunden, bei denen man getrost sagen kann, dass sie sich eigentlich nicht sonderlich für „solche Internetsachen“ interessieren und sich auch nicht intensiv mit IT-Themen auseinandersetzen. Dies ist hier keinesfalls abwertend zu verstehen. Jeder hat seine speziellen Neigungen und Fertigkeiten. Gewiss wird so mancher Webdesigner wohl weder eine Motorsäge bedienen, noch einen Ölwechsel am Auto vornehmen können. Diesem Kundenkreis ist es einfach nur Bedürfnis, eine Homepage, sprich Web-Präsenz, zu haben, um damit Werbung für eigene Zwecke zu platzieren (Handwerker und Dienstleister, Gastronomiebetriebe, Freiberufliche und so weiter) – deren eigentliches Tagesgeschäft liegt einfach in einem ganz anderen Metier. Gerade kleinere Unternehmen haben keine „EDVler“ mit Kenntnissen in der Website-Erstellung beschäftigt und gewiss war dies im Vorfeld auch mit einer der ausschlaggebenden Punkte, einen Webdesigner mit dem Aufbau „der Homepage“ zu beauftragen.

Eine gute Dokumentation zeichnet sich dadurch aus, dass man sich informieren kann, daher sollten Fachbegriffe, die im Text verwendet wurden, in einem Glossar mit kurzen Beschreibungen nachvollziehbar erläutert werden.

Stichwortverzeichnis
Je nach Umfang der Dokumentation ist ein alphabetisches Stichwortverzeichnis nicht unbedingt zwingend. Hier sollte man im Einzelfall abwägen, ob dies zur Übersichtlichkeit notwendig ist. Es gibt dem Ganzen aber einen gewissen Mehrwert und zeugt durchaus von Professionalität.

Quellenangaben
Hat man sich für die Dokumentation externer Quellen bedient, dann macht es auf jeden Fall Sinn, diese in einem Quellenverzeichnis zu erwähnen.
Zu den Quellenangaben gehören auch die Vorlagen für Rahmenbedingungen, beispielsweise ein bereits existierendes Corporate Design oder ein Styleguide.

Projektbeschreibung
Die textliche Beschreibung gehört beim Inhalt ziemlich an den Anfang – ähnlich einem Vorwort. Worum geht es überhaupt bei diesem Web-Projekt? Wer stellt sich oder sein Unternehmen vor und was wird zu welchem Zweck veröffentlicht?

Bei dieser Beschreibung macht es auch Sinn, auf die Zielgruppen einzugehen, für die der Webauftritt konzipiert und umgesetzt wurde. Hier handelt es sich um inhaltliche Aussagen, die sicherlich bei einem der ersten Planungsgespräche als Grundlage getroffen wurden. Falls mit einem Lasten- und/oder Pflichtenheft gearbeitet wurde, sind sie dort gewiss ebenfalls schon erwähnt, können aber dennoch in diesem „Abschlussbericht“ nochmals wiederholt werden.

Provider und Vertragliches
In vielen Fällen wird es so sein, dass das Projekt auf dem Server bei einem Webhosting-Provider liegt und der Kunde mit diesem den Vertrag abgeschlossen hat. Über das Verhältnis zu diesem „Dritten im Bunde“ sollten die wichtigsten Angaben zum Hoster in die Projektdokumentation aufgenommen werden, auch wenn dabei eventuell wenig eigene Arbeit mit hinein geflossen ist. In der Doku soll schließlich der „ganze“ Internetauftritt beschrieben werden.

Kontaktdaten, Vertragsnummern und -Bezeichnungen sind hier auf jeden Fall zu erwähnen. Die Nennung von Zugangsdaten oder gar Passwörtern jedoch sollte man hier besser vernachlässigen – schließlich kann die Dokumentation auch mal in die Hände Dritter geraten, denen man damit nicht unbedingt Tür und Tor zu öffnen braucht, um eventuell Unfug zu treiben.

Weiterhin sind Angaben über die wichtigsten Leistungen des Providers, die mit diesem Vertrag erworben wurden, durchaus informativ: Speichergröße des Webspace, Transfervolumen, Angaben zu E-Mail-Postfächern, Statistik, Datenbank(en), Scriptsprachen und so weiter können in Listenform mit aufgenommen werden.

Angaben zur Darstellung
Dieser Bereich der Dokumentation ist für Angaben zur allgemeinen Darstellung des Projekts gedacht. Wurde beispielsweise für bestimmte Mindestmaße an Pixeln bei der Bildschirmanzeige optimiert, sollte dies hier genannt werden. Außerdem gehören in diese Rubrik auch die Ergebnisse von Tests mit unterschiedlichen Browsern und Browserversionen sowie Angaben zur Validität des erzeugten Codes in Bezug auf die aktuellen Standards.

Barrierefreiheit
Für manche Kunden stellt sich Barrierefreiheit oder besser Barrierearmut bislang noch nicht von besonderer Bedeutung dar und wird daher gerne mal etwas nachlässig behandelt. Schon zu Beginn des Projektes sollte man auf dieses Thema eingegangen sein und den Auftraggeber dahingehend etwas sensibilisiert haben. Was schließlich als Ergebnis für den Aufbau und Inhalt der Seiten dabei herausgekommen ist, kann in der Dokumentation Erwähnung finden.

Bei Themen wie diesem können in der Dokumentation gewiss auch allgemeine Informationen mit einfließen, die keinen direkten Bezug zum Projekt haben – oder man geht im Glossar auf diese Punkte ein.

Verwendete Techniken und Programme
Hat man mit Programmen wie Dreamweaver, NVU und so weiter gearbeitet oder auch „von Hand“ codiert, braucht dies gewiss nicht als Betriebsgeheimnis betrachtet zu werden und kann hier erwähnt sein.

Von Bedeutung sind auf jeden Fall auch Angaben zu Stylesheets, eventuellen Scripten oder vielleicht kam auch eine Frameset-Technik zur Anwendung, deren Aufbau erläutert werden sollte. Eine solche Beschreibung des Gerüsts kann auch auszugsweise Codeschnipsel oder ganze Scripte oder Stylesheets in Textform enthalten. Angaben zu eingebetteten Flash-Objekten, PDFs oder auch anderen Dateien, die beispielsweise zum Download oder zur Ausführung bereit stehen, sollten hier ebenfalls Erwähnung finden.
Kommt eine Datenbank zur Anwendung, ist auch dafür eine Beschreibung mit allen erforderlichen Eckdaten unerlässlich. Gleiches gilt für verwendete Perl- und PHP-Scripte oder wenn Content-Module oder vollständige Content Management Systeme eingesetzt werden. Logisch: Existieren bereits Handbücher oder Dokumentationen zu fertig verwendeten Modulen, dann brauchen diese natürlich nicht abgetippt werden, ein Verweis auf diese Dokumente (die man aber gegebenenfalls auch mitliefern kann) sollte genügen. Wichtig ist in einem solchen Fall auch, ganz klar herauszustellen, dass es sich dabei um „beigestellte“ Dinge handelt, die nicht aus eigener Entwicklung stammen. In diesem Fall wäre dies auch wieder ein nennenswerter Punkt für die Quellenangaben.

Ordnerstruktur und Namensgebung
Gerade bei statischem Aufbau ist es sinnvoll, die komplette Ordnerstruktur und Namensgebung zu beschreiben, auch mit den Konventionen, die bei der Datei- und Verzeichnisnamensgebung beachtet wurden – Kleinschreibung, Umlaute, Sonderzeichen…

Mit diesen Informationen kann sich der Kunde – aber auch der Designer – jederzeit schnell einen Überblick verschaffen, welche Elemente auf dem Webserver, an welcher Stelle zu finden sind. Zur Auflockerung und schnelleren Erkennung bietet sich ergänzend dazu ein Screenshot der Verzeichnisstruktur als Wegweiser an.

Design und Farbgebung
Dieser Themenblock kann sehr umfangreich gestaltet werden. Seine Kernaussage lässt sich aber in einer Frage zusammenfassen, die es darin zu beantworten gilt:
Warum wurden welche Farben, Schriften, Grafiken und so weiter, für welche Zwecke im Webauftritt verwendet?

Angaben zu Textgrößen und natürlich die verwendeten Farbwerte – webecht oder auch nicht – sollten hier in einer übersichtlichen Auflistung Erwähnung finden, mit der man auch jederzeit schnell (wieder) einen Überblick erhält.

Bei der Beschreibung sollte man darauf achten, dass diese für den Kunden auch „sprechend“ formuliert ist, und nicht nur von CSS-Klassen oder „H1 bis H6“-Tags die Rede ist. Es ist daher vorteilhaft, auch für Leser (Kunden), die sich mit diesen Themen nicht eingehend beschäftigen, einen brauchbaren Überblick anzubieten.

Zur besseren Veranschaulichung können verschiedene Screenshots oder Auszüge von Seitenbereichen gezeigt werden. Standardisierte Abmessungen oder Stilelemente von Grafiken oder Fotos, die im Projekt verwendet wurden, sollten bei den Angaben zum Design ebenfalls nicht fehlen.

Hat man sich einer Farbpalette bedient oder eine solche erstellt, gehört eine Abbildung davon ebenfalls in diese Rubrik – ebenfalls wieder ergänzt um die gewählten Farbwerte.
Favicon

Wurde dem Webauftritt ein Favicon zugewiesen, sollte dieses Miniatursymbol ebenfalls kurz beschrieben und am besten auch in einer Abbildung gezeigt werden. Gerade auch deshalb, weil manche der weit verbreiteten Browser dieses immer noch ignorieren und beim Kunden daher durchaus die Möglichkeit besteht, dass er es am Bildschirm gar nicht angezeigt bekommt.

Navigation auf der Website
In einem Kapitel sollte – beispielsweise ähnlich einer Sitemap – auf alle vorhandenen Navigationspunkte eingegangen werden. Eine sprechende Beschreibung der Inhalte, die dort jeweils enthalten sind, verschafft hier einen schnellen Überblick und zeigt gleichzeitig, dass man sich damit auseinandergesetzt hat, was wo platziert ist.

E-Mail-Adressen
Wurden E-Mail-Adressen eingerichtet, sollten hier natürlich alle genannt werden. Je nach Sachlage kann hier auch noch eine Erläuterung mit angebracht werden, was wo hingeschickt wird, beziehungsweise für welche Zwecke die einzelnen Adressen gedacht sind (bestellannahme@…, versandabteilung@…, beschwerden@… und so weiter)
Ein Verweis zu den insgesamt verfügbaren E-Mail-Adressen im Hosting-Vertrag (siehe auch Punkt Provider und Vertragliches) ist ebenfalls sinnvoll. Wurden Techniken zum Spam-Schutz von E-Mail-Adressen im Projekt angewendet, sollten diese ebenfalls in der „E-Mail“-Rubrik beschrieben werden.

Externe Links
Kaum ein Webauftritt kommt ohne Verlinkungen zu anderen Internetseiten daher. Es ist aus diesem Grund sinnvoll, die externen Verweise, die wild über das ganze Projekt verstreut sein können, in einer Liste aufzuführen, um auf einen Blick zu sehen, wo die Pfade nach „außen“ liegen und wohin sie führen.

Suchmaschinen
Wurden seitens des Webdesigners Anmeldungen zu Suchdiensten vorgenommen, können diese Eintragungen hier aufgelistet werden. Weitere Angaben, die bei den Metatags zur Beschreibung der Seiten gemacht wurden, können hier ebenfalls veranschaulicht werden.

Screenshots
Eine Sammlung von Screenshots aller erstellten Seiten sollte in einer guten Dokumentation nicht fehlen. Für die Anordnung bietet sich an, diese in der Reihenfolge der Navigationseinträge zu sortieren. Bei Effekten, wechselnden Anzeigen und Ähnlichem sollten diese ebenfalls mit abgebildet oder gegebenenfalls durch Erläuterungen ergänzt werden. Hat man viele gleichartige Seiten, zum Beispiel Artikelkataloge, Fotoalben und ähnliche identisch aufgebaute Dinge eingearbeitet, dann reicht es natürlich, einige Beispiele aufzuführen, anstatt die Seitenzahl der Dokumentation unnötig in die Höhe zu treiben.

Dies waren nun einige Beispiele für Themenblöcke, die in einer umfassenden Web-Projektdokumentation sinnvoll sind. Mit einem solchermaßen ausgestatteten Werk hat man für künftige eigene Recherchen ein hilfreiches Langzeitgedächtnis geschaffen und dem Auftraggeber etwas in die Hand gedrückt, worin er selbst ausführlich nachlesen kann, woraus seine Homepage besteht. Ein ergänzendes Hilfsmittel also, mit dem sich auch der Kunde kundig machen kann. ™

Erstveröffentlichung 03.05.2007