# Logima Dokumentenablage in Projekten

> Finale Fassung: Version 1.0 vom 10. November 2021
> Abgestimmt in [Loomio](https://www.loomio.org/d/eVR3DEOW/ordnerstruktur-in-projekten/)

[TOC]

## Ziele

* Laufende Kommunikation mit dem Kunden
* Wissenssammlung für uns im laufenden Projekt
* Wissenssammlung für den Kunden im laufenden Projekt
* Wissenssammlung für uns und den Kunden, wenn wir Informationen von eigentlich abgeschlossenen Projekten zurückgreifen wollen.
* Erstellung von Wissen im Projekt (Konzepte, Protokolle, ...)
* Koordinierung der Arbeitspakete
* Durchführen von Angeboten, Abrechnung und Controlling

### Kommunikation mit dem Kunden

Bei der Kommunikation mit dem Kunden kann es zum Einen sein, dass er alle Dokumente und Artefakte selbst übernimmt und in einer eigenen Ablage für sich bereitstellt oder auch, dass er sich auf unsere Bereitstellung verlässt und nur darüber auf die Artefakte zugreift.

### Langzeitarchiv

Im laufenden Projekt kann man auf beliebige Plattformen und Dienstleister zugreifen um Wissen zu erstellen und auszutauschen. Mit der Zeit werden diese aber verschwinden oder nicht mehr zugreifbar sein. Sei es, weil Kosten in keiner Relation zum Nutzen mehr stehen oder das Produkt ganz vom Markt verschwindet. Beides kann auch schon nach relativ kurzer Zeit der Fall sein oder auch sehr plötzlich passieren.

Am stabilsten ist im Rückblick die Ablage in einem ordnerbasiertem Dateisystem auf das alle Beteiligten einfachen Zugriff haben. Auch eine Suche ist hier über Systemfunktionen einfach möglich. Die Informationen aus allen anderen Systemen verschwinden (selbst wenn man die Daten selbst exportieren kann, ist der Zugriff und das Suchen oft nur mit beträchtlichem Aufwand möglich).

## Grundstruktur und beteiligte Systeme

Das Ziel ist, dass ***alle relevanten Projektdaten*** datei- und ordnerbasiert abgelegt werden. Für laufende Projekte nutzen wir dafür **Sharepoint**.

Die allgemeine Definintion der relevanten Dokumente ist in diesem Dokument zu finden, kann für einzelne Projekte aber vom Projektleiter angepasst werden.

> [name=habakuk]
> [time=Wed, Sep 29, 2021 5:35 PM]
> Zu Bedenken:
> * DSGVO (gerade bei Online-Diensten)
> * [Revisionssichere Archivierung](https://www.buchhaltung-einfach-sicher.de/archivierung)

Für abgeschlossene Projekte oder sehr große Dateien nutzen wir einen **Fileserver** der von uns gehostet wird.

**Basecamp** wird zur ***Kommunikation mit dem Kunden*** genutzt. Alles was über Diskussionen mit dem Kunden hinausgeht wird zusätzlich als Datei in der dateibasierten Ablage (Sharepoint) abgelegt (oft auch erst dort erstellt und dann über Basecamp veröffentlicht).

**Jira** wird nur zur ***Arbeit inklusive der Arbeitsdokumentation*** an einzelnen Tickets genutzt. Dabei sollen durchaus Implementierungsentscheidungen hier dokumentiert werden (da anderes nicht praktikabel ist). Dokumente und grundsätzliches sollte aber in der dateibasierten Ablage stehen oder auch direkt im Git-Repository.

**Git** ist genauso stabil (wenn nicht stabiler) wie die dateibasierte Ablage, deswegen sollten und können neben dem eigentlichen ***Quelltext*** auch ***implementierungsnahe Informationen*** hier mit gespeichert werden (in [Architectural Decision Records (ADR)](https://adr.github.io/), ReadMe-Dateien, Code-Kommentaren, ....).

Zusätzlich kann in (eventuell eigenen) Git-Repositories auch (Endnutzer) ***Dokumentationen*** abgelegt werden, wenn sie als strukturiertes Text-Dokument verfügbar ist (Markdown, Ascii-Doc, HTML, ...). Die erzeugten Artefakte (Compilate oder erzeugte PDF oder HTML-Dokumentation sollte aber zusätzlich als Release in der dateibasierten Ablage abgelegt werden).

Sollten wir uns irgendwann für ein **Wiki** für das ***kollaborative Erstellen von Dokumenten*** entscheiden ist auch hier nicht von einer dauerhaften Verfügbarkeit im Sinne einer Langzeitarchivierung auszugehen. Deshalb sollten Dokumente hier ebenfalls, z. B. bei Veröffentlichung an den Kunden, als PDF exportiert werden und in der dateibasierten Ablage aufgenommen werden. Gleiches gilt für andere **Online-Kollaborationstools**.

## Datei- und ordnerbasierte Ablage (Sharepoint und Fileserver)

### Basisregeln

Der **Basispfad** für Kunden-Projekte ist `Kunden-Projekte/[KUNDE]/[JAHR]_[PROJEKTNAME]/` (z. B. *Kunden-Projekte/AcmeInc/1999_FirmwareNextGen/*). Jedes **Projekt** bekommt einen eigenen Ordner mit führender Jahreszahl, in dem das Projekt begonnen hat.

Alle Dokumente bekommen im Dateinamen einen **Zeitstempel** im Format `YYYY-MM-DD`, der dem Veröffentlichungsdatum bzw. Erstellungsdatum entspricht (z. B. *2021-02-28 Test Report für XY.zip*).

**Standard-Ordner,** die es in jedem Projekt bzw. für jeden Kunden geben, werden mit **führenden Zahlen sortiert**.

Wenn einzelne Ordner nach einiger Zeit zu viele Dokumente beinhalten können Unterordner für die **Archivierung** angelegt werden. Beispielsweise ein allgemeiner Archiv-Ordner **`../[KUNDE]/20_Abrechnungen/Rechnungen/Archiv`** oder Jahresarchive **`../[KUNDE]/20_Abrechnungen/Rechnungen/1999`**.

In jedem Projekt ist der **Projektleiter** für die Einhaltung der **Archivierungsregeln** zuständig und weisungsbefugt. Sind von diesem Dokument abweichende Regeln festgelegt, wird dafür im Projekt-Basispfad ein Dokument **`00_Archivierungsregeln.md`** (oder in anderem Format) angelegt.

### Dokumente mit direktem Kundenbezug

Da **Angebote, Controlling und Zeitabrechnungen** oft parallel passieren und auch vor einem konkreten Projekt werden diese Informationen beim Kunden aufgehängt.

* **`../[KUNDE]/10_Angebote`**
Hier werden alle Angebote für diesen Kunden abgelegt.
* **`../[KUNDE]/20_Abrechnungen/**`
Direkt hier werden Controlling-Dokumente abgelegt, die z.B. die laufend angebotenen und abgerechneten Zeiten für ein Projekt beinhalten.
* **`../[KUNDE]/20_Abrechnungen/Rechnungen`**
Hier werden die, meist monatlichen, Abrechnungen (also Rechnungen) abgelegt
* **`../[KUNDE]/20_Abrechnungen/Zeit`**
Hier sind die aufbereiteten Zeitabrechnungen pro Monat für den Kunden abgelegt. Oft langt es wahrscheinlich eine Zeitaufstellung für alle Projekte die aktuell beim Kunden laufen zu machen. Manchmal werden sie nach Projekten getrennt angelegt.
Das Finale-Ergebnis wird bei der Rechnung mit abgelegt, damit klar ist, was tatsächlich an den Kunden ging.

Zusätzlich gibt es noch **Dokumente die vom Kunden kommen,** die für mehr als ein Projekt relevant sind.

* **`../[KUNDE]/50_Kundendokumente`**
Alles was nicht nur für ein einzelnes Projekt relevant ist (z.B. Styleguides, Logos, Kataloge, …).

## Dokumente im Projekt

### Dokumentarten

#### Meeting-Protokolle

Es gibt auf jeden Fall **Protokolle zu Meetings**. Dazu gehören manchmal auch **extra Dokumente** die dafür vorbereitet werden oder die auch danach extra für das Meeting erstellt werden

#### Kunden-Dokument

Dokumente die wir vom **Kunden** bekommen, die wir für die Umsetzung des Projektes brauchen. Diese werden an einem Ort gesammelt abgelegt, außer sie gehören nur zu einem Teil-Feature und werden nicht öfter benötigt (dann werden sie dort abgelegt).

#### Ergebnis- und Arbeitsdokumente - Umsetzung

Im Projekt werden für den Kunden oder intern **verschiedenste Dokumente erstellt.** Oft gibt es zu einem fertigen Dokument auch verschiedene Artefakte (Grafiken, Office-Dokumente, Links zum Wiki in dem das Dokument vorbereitet wird, …), die zur Erstellung benutzt wurden.

Manchmal werden diese Dokumente unter Umständen auch an anderer Stelle erstellt (Wiki, Basecamp, Jira, …).

All dies gehört zur **Umsetzung** des Projektes.

Immer wenn ein Dokument für den Kunden freigegeben wird, dann muss es nicht nur auf der Kommunikationsplatform veröffentlicht werden, sondern auch hier. Falls es ein bearbeitbares Dokument gibt und z. B. nur das PDF veröffentlicht wurde, dann sollten hier beide Dokumente abgelegt werden.

Ist das Ursprungsdokument in einem externen System entstanden z. B. in einem Wiki, sollte hier ein URL-Link (URL-Datei) dafür abgelegt werden.

#### Releases

**Releases,** sind meistens compilierte Artefakte, die aber oft auch nicht für sich alleine stehen, sondern noch Nutzer- und Test-Dokumentation umfassen. Manchmal auch noch direkt den Quellcode-Stand.

Ab und zu haben wir auch reine Dokumenten-Releases, diese werden wie andere Releases behandelt (meistens werden veröffentlichte Dokumente für den Kunden aber nicht als Release behandelt).

#### Support-Dokumente

Nach dem Ende eines Projekts ist es oft noch nicht komplett abgeschlossen, oft gibt es viel später nochmal **Ergänzungen** - diese können je nach Umfang in einer eigenen Folgeprojekte-Ablage oder in der ursprünglichen Ablage behandelt werden.

Manchmal gibt es laufenden **Support,** für den auch Dokumente erstellt werden, meistens rechtfertigt das keine neue Projekt-Ablage.

### Ordnerstruktur

Hier die Ordnerstruktur, ergänzt mit Beispielen.

* **`10_Meetings/`**
Hier werden die Protokolle und dazugehörigen Dokumente abgelegt. Das Datum im Dokument ist das Datum des Meetings. Im Titel des Dokuments kann auch das (Haupt)-Thema mit angegeben werden.
* `01_Meetings/2021-05-24 Initiales Meeting Protokoll.pdf`
Das PDF, das an den Kunden ging.
* `01_Meetings/2021-05-24 Initiales Meeting Protokoll.doc`
Das Dokument, dass bei Bedarf noch Bearbeitet werden kann (z.B. bei Fehlern).
* `01_Meetings/2021-05-24 Initiales Meeting - Anhang Businesscase.pdf`
Ein Anhang zum Protokoll. Wenn es nur ein Dokument ist, kann es hier auch zusätzlich als Office-Dokument gespeichert werden. Wenn es aufwändiger erstellt wurde und es mehrere Artefakte dazu gibt (Revisionen, Grafiken, Berechnungen, …) sollten diese nicht hier gespeichert werden sondern bei den erstellten Dokumenten.

* **`20_Kundendokumente/`**
Dokumente, die vom Kunden kommen und für das gesamte Projekt (also nicht nur einzelne Features) relevant sind. Dokumente die für mehr als ein Projekt relevant sind, werden direkt unter dem Kunden abgelegt (z.B. Logos).

* **`30_Anbahnung und Vorbereitung/`**
Dokumente die für die Anbahnung und Vorbereitung relevant waren, werden hier abgelegt. Das können initiale Konzepte oder Business-Cases oder Schätzungen sein.
In diesem Ordner wird wieder mit Unterordnern gearbeitet, die durch das Datum sortiert werden.
* **`1980-05-31 Initiales Konzept/`**
* **`2020-10-31 Kostenschätzung/`**

* **`50_Umsetzung`**
Alle Dokumente die mit der Umsetzung zu tun haben.
Darunter werden Unterordner angelegt, die das Datum an denen einzelne Themen begonnen wurden enthält, und eine sehr kurze Überschrift zum Thema. Eventuelle Verweise auf Jira-Tickets können in Klammern am Ende ergänzt werden (nur, wenn es ein einzelnes Ticket betrifft).

Gibt es ganz klare Projektphasen kann eine zusätzliche Ebene mit den Phasen eingezogen werden. Auch hier wieder mit dem Datum an dem mit der Arbeit daran begonnen wurde.

Gibt es Themengebiete können dafür ebenfalls Unterordner, dann ohne Datum, angelegt werden (z. B. `Schnittstellen` oder `Konzepte` ). Darunter können, falls zu einem Thema nur ein oder zwei Dateien exisitieren dann auch direkt Dateien abgelegt werden (ohne zusätzlichen Unterordner). Dabei ist darauf zu achten, dass die Unterordner möglichst eindeutige Bereiche benennen und wiederspruchsfrei sind.

Spätestens wenn Dokumente, die nicht als Datei erstellt wurden (z. B. Wiki), für den Kunden veröffentlicht wurden wird hier dafür eine PDF-Kopie mit abgelegt und eventuell ein Link auf das System (URL-Datei).

* **`50_Umsetzung/2018-01-15 Konzeptphase/`**
* **`2018-03-29 Bluetooth Übersicht/`**
* **`50_Umsetzung/2020-06-11 Prototypphase/`**
* **`2021-04-13 Konzepte`**
* **`Schnittstellen`**
* **`2021-05-05 Bluetooth Protokoll Details (VAC-999)/`**
* **`2021-12-02 Dokumentation/`**
* `2021-05-25 OEM Interface.doxc`
* `2021-05-25 OEM Interface.pdf`

* **`80_Releases/`**
Hier werden Releases abgelegt. Unter Umständen nicht mit dem Zeitstempel im Dateinamen, sondern der Versionsnummer. Manchmal macht es Sinn für eine Version jeweils einen extra Unterordner anzulegen, manchmal langt es alles in einen Ordner zu legen.
* `0.0.1-rc.1_BlaBlub_Setup.exe`
* `1.0.0_BlaBlub_Setup.exe`
* `1.0.0_BlaBlub_Anleitung.pdf`
* `1.0.0_BlaBlub_TestReport.pdf`

* **`90_BugFixing/`**
Der Ort um Infos zu einzelnen Bugs abzulegen (falls notwendig). Jeweils Unterordner pro Bug, der dann auch das Datum, die Jira-Case Nummer beinhaltet und die Bug Summary.
* **`2017-01-13 Das Ding geht nicht (VAC-100)/`**
* **`2021-05-14 Summenfehler (VAC-1)/`**

* **`99_Support/`**
Alles was support-spezifisch ist wird hier abgelegt: Support-Anleitungen, Freischalt-Infos, …