Dokumentationsplan Einleitung

Bei VirtL nehmen die verschiedenen Benutzer und Benutzerinnen verschiedene Rollen, die wir als Akteure beschreiben, war. Je nach Wissen, Bedürfnissen und Aufgaben gehen wir unterschiedlich mit dem System um und agieren somit unterschiedlich mit dem System. Ein Akteur ist eine Rolle und wird daher immer mit der Akteuer beschrieben. Wir haben hier also auch an die Leserinnen gedacht ;). Die verschiedenen Akteuere sind in folgender Grafik dargestellt. Eine detailierte Beschreibung der Akteure findest du im Abschnitt Die Personengruppen (Akteure) und deren Informationsbedürfnisse.

Den verschiedenen Akteure werden mit diesem Dokumentationsplan eine einfache Navigation durch die Dokumentation ermöglicht.

Dokumentationsarten

Es gibt drei verschiedene Dokumentationsarten die innerhalb dieses Projektes gepflegt werden:

Howto

Howtos geben den Lesern einen schnellen Einblick in einzelne Themengebiete.

Um ein Howto lesen zu können müssen die Leser kein Grundwisssen mitbringen. Die Leser werden durch die einzelnen Kapitel geführt. Alle Unterkapitel bauen auf den vorigen Kapitel auf. Howtos beschreiben ein Themengebiet nur oberflächlich.

Folgende Dokumentation wird als Howto in diesem Projekt verwaltet:

• Präsentationen
• Anwender Bedienungsanleitungen
• Administrationskurzbeschreibungen">
• Funktionsbeschreibung des Systems
• Projekthomepage Indexseite
• Glossar
• FAQ
• Dokumentationsplan

Tutorials

Mit Tutorials können die Leser sich in bestimmte Themengebiete einlernen. Die Tutorials beschreiben schrittweise die Zusammenhänge im System. Jedes Kapitel baut auf die vorigen Kapitel auf. Ein Grundwisssen wird von den Lesern nicht erwartet. Ein Tutorial beschreibt das System exakter als ein Howto, jedoch nicht jedes Detail.

Folgende Dokumentationen werden als Tutorials in diesem Projekt verwaltet:

• Installationsanleitungen
• Programmers Guides
• Checklisten
• API Dokumentation
• Architekturübersichten

Manuals

Ein Manual beschreibt einen Sachverhalt bis in das letzte Detail. Die Leser müssen ein gewisses Grundwisssen mitbringen. Dies können sie sich mit den Howtos und den Tutorials erwerben. Manuals sind wesentlich ausführlicher als Howtos und Tutorials.

Folgende Dokumentationen werden als Manuals in diesem Projekt verwaltet:

• Klassendokumentationen
• Anwendungsfallbeschreibungen
• Testszenarien
• Styleguides
• Betriebshandbücher
• Bedienungsanleitungen
• Administrationshandbücher
• Datenbankadministration
• Serveradministration
• ISP Dokumentation
• Systemkonfigurationsbeschreibung

Sonstige Dokumentation

Der aufmerksame Leser hat sicherlich mitbekommen, dass zum Beispiel Emails, Korrespondenz, Projektleitungsdokumentation, Besprechnungsnotizen usw. nirgends eingeordnet werden können. Das liegt daran, dass diese Dokumentationsarten nicht im Dokumentationsmanagement gewartet werden und deshalb im Unterordner Projektmanagement in VirtL abgelegt werden.

Die Personengruppen (Akteure) und deren Informationsbedürfnisse

Das System wird von Personen mit verschiedenen Informationssichtweisen verwendet. Der Entwickler will das System bis in das letzte Detail verstehen um es erweitern zu können. Der Anwender will das System nur so umfassend verstehen um die Funktionen des Systems verwenden zu können. In diesem Kapitel werden die verschiedenen Personengruppen katagorisiert und deren Anforderungen an die Dokumentation beschrieben.

Akteur Interessierter

Diese Anwendergruppe will sich schnell und einfach über das System eine Meinung bilden können. Jeder der das erste Mal die Webseite mit der Applikation aufruft und sich einen Überblick über die Dokumentation verschafft ist ein potentieller Akteur Interessierter.

Jeder der folgenden Anwendergruppen baut auf diese Dokumentation auf, somit sollen alle Akteure diese Dokumente lesen.

Anwender

Die Lesergruppe Anwender benötigt Informationen über die funktionalen Eigenschaften das System. Personen dieser Lesergruppe müssen kein ausgeprägtes technisches Verständnis mitbringen. Sie wollen mit wenig Informationen das System bedienen und beherrschen können.

Aufgaben

Die Anwender verwenden das System und liefern dem Projektteam die Änderungswünsche. Weiterhin liefern sie Informationen wenn das System nicht korrekt arbeitet.

Wegen Menschen wie dir haben wir dieses System erstellt. Also probier es aus und gib uns Bescheid, falls dir etwas nicht gefällt. Für positives Feedback sind wir natürlich auch zu haben.

Mitglied

Im Normalfall gehörst du, wenn du das System verwendest, zu dieser Sorte Mensch. Du legst deine Bücher und andere Medien im System ab und willst dass der Systemadministrator die Maschine am Leben hält. Du brauchst nicht alles über das System zu wissen. Dir ist es egal, ob wir ein geiles Pattern verwendet haben um irgend eine Funktionalität gewährleisten zu können. Dir ist auch egal, wie der Systemadministrator die Platte putzt. Du willst mit dem System arbeiten und brauchst deshalb Informationen was das System für dich alles tun kann.

Du bekommst vor allem Seiten zu sehen, die sich mit der Bedienung des Systems auseinandersetzen.

Aufgaben

Wie schon erwähnt besteht deine Aufgabe darin, das System zu benutzten. Für deine Änderungswünsche sind wir jedoch sehr dankbar. Wenn du das System benutzt und Fehler findest, sind wir für deine Anregungen sehr dankbar.

Gruppenadministrator

Wenn du ein Mitglied bist und deine eigenen Gruppen pflegen willst, dann bist du einer von denen...

Spaß bei Seite, der Gruppenadministrator, oder die Gruppenadministratorin, haben ein paar Knöpfe mehr zu bedienen als das einfache Mitglied. Du bekommst, falls du mal eine Gruppe zu pflegen hast, ein paar Seiten mehr zu lesen als das Mitglied. Ansonsten kannst du dich zurücklehnen und die Funktionen dieses Systems genießen.

Aufgaben

Du fügst zu deinen Gruppen Mitglieder hinzu, oder entfernst sie wieder.

Systemadministratoren

Diese Lesergruppe bringt ein ausgeprägtes technisches Wissen mit. Sie wollen das System als Ganzes verstehen um es betreiben und administrieren zu können.

Ja, bei uns ist der Systemadministrator ein Mensch der zu den Anwendern gehört. Das liegt daran, dass diese Personen ein fertig entwickeltes System pflegen. Ihr lieben Leute fummelt an der Software herum, die wir für euch zusammengeklebt haben.

Du brauchst ein recht tiefes Wissen über die Pflege und Hege von VirtL. Du willst Tablespaces für den Ansturm der Anwender anlegen und hin- und wieder das System mit einem neuen Release verwöhnen.

Aufgaben

Die Systemadministratoren sorgen dafür, dass das System betreibbar bleibt. Sie installieren das produktive System. Weiterhin kümmern sie sich um die Pflege und sorgen dafür, dass das System genügend Speicherplatz besitzt, Bugfixes und Releases planmässig eingespielt werden.

Die Testsysteme werden von den Systemadministratoren aufgesetzt und gepflegt. Die Tester können auf diese Systeme bei ihren Tests aufsetzen.

Da es sich bei dem System um eine Serverlösung handelt, muss ein Testsystem aufgesetzt und betrieben werden.

Akteur Entwickler

Das ist wieder eine Übergruppe. Ihr Kollegen fummelt am Sourcecode rum und helft uns weitere und noch tollere Releases zu erstellen.

SW-Entwickler

Das sind für jeden Projektleiter die Typen, die ihm zwar die schönen neuen Funktionen liefern, ihr seid aber auch die gefährlichsten Jungs und Mädels für uns. Ihr habt die Macht das System zu verändern und zu zerstören. Wir sind auch solche Pizzaessenden, Kaffeetrinkenden und im Leuchtstoffröhrenlicht am liebsten wohnenden Wesen. Wenn ihr an diesem System mit rumfummeln wollt, dann meldet euch bei uns. Zu tun gibt es wie immer genug!

Ihr braucht ein sehr tiefes Wissen über das System. Die Anwenderdokumentation solltet ihr gelesen haben. Für euch haben wir auch noch die ganze Quelltext Dokumentation und die Programmierrichtlinien. Ihr seid also richtig belesen gelle?
Bevor ihr loslegt solltet ihr alle Dokumente, die den Anwendern zur Verfügung gestellt wurden, gelesen haben. Weiterhin solltet ihr euch im Untermenü Anwendungsfälle auskennen und die Sourcen einsehen.

Das technische Wissen dieser Lesergruppe ist sehr ausgeprägt. Sie wollen das System bis ins letzte Detail kennen und begreifen und benötigen somit die volle Breite der Dokumentationen.

Aufgaben

Die Entwickler erstellen die Softwarearchitektur, die Unit Tests, den Sourcecode, die Installationsscripts, Migrationsprogramme, das Hilfesystem und die vollautomatischen Regressionstests.

Bei den Testebenen kümmern sich die Entwickler um die Modul- und Integrationstests.

Die Entwicklungsumgebung wird von den Entwicklern selbst gepflegt.

Tester

Du suchst gerne anderer Leute Fehler?

Dann bist du vermutlich ein Tester oder eine Testerin.

Tester können sowohl Anwender als auch Entwickler sein. Wir haben tonnenweise Funktionen die getestet werden müssen.

Du solltest deinen Bereich gelesen und verstanden haben. Wenn du ein Anwendungstester bist, dann musst du die Anwenderdokumentation gelesen haben. Bist du ein Softwaretester, dann musst du unsere Dokumentation für die Programme und Testrichtlinien gelesen und verstanden haben.

Die Tester müssen das System so weit verstehen, dass sie die funktionalen und nichtfunktionalen Anforderungen testen können. Hierfür müssen sie die gesamte Dokumentation zumindest auf Plausibilität prüfen. Für ihre Tätigkeit müssen sie ein ähnliches technisches Verständnis wie die Anwender haben.

Aufgaben

Die Tester erstellen die Testfälle, Testdrehbücher und Testpläne. Sie geben den Entwicklern Vorgaben um so viel wie möglich Testfälle automatisieren zu können. Der Systemtest wird von den Testern durchgeführt.

Nach dem Systemtest kontrollieren die Systemadministratoren, ob das im Systemtest eingespielte System auch betreibbar ist.

Redakteur

Wie bitte? Du kannst einen ganzen Satz schreiben? So mit Tunwort, Hauptwort und vielleicht sogar mal ein Eigenschaftswort? Hey super!

Open Source Projekte leiden grundsätzlich an einer etwas miesen Dokumentation. Wir probieren zwar die Doku sauber zu halten, aber Menschen wie du können uns super helfen!

Wenn du eine Redakteurin oder ein Redakteur sein willst, solltest du die Anwenderdokumentation gelesen haben. Wenn du ein technisch orientierter Redakteur, oder eine technisch orientierte Redakteurin bist, dann krabbelst du auch noch in die Quelltexte der Entwickler rein und hilfst unsere Programmzeilen sinnvoll zu dokumentieren.

Falls du eine andere Sprache als wir beherrscht, also nicht nur C, PHP, Java und Grundkenntisse in Deutsch, sondern so was wie Englisch, Chinesisch, Spanisch usw. dann kannst du uns auch helfen die bisher erstellten Texte in die jeweilige Sprache zu übersetzen.

In dem Fall musst du mindestens die Anwenderdokumentation so weit verstanden haben, dass du das System bedienen kannst und verstehst was wir so geschrieben haben.

Die Redateuere müssen das System verstehen und die funktionalen und nichtfunktionalen Anforderungen beherrschen. Ihre Sprachkenntnisse müssen so ausgeprägt sein, dass sie die Dokumentation korrekt erstellen oder in eine andere Sprache übersetzen können. Beispiel: Eine Irin kann so gut deutsch um den deutschen Text gut verstehen zu können und übersetzt diesen ins Englische.