PDA

Vollständige Version anzeigen : Doku ........ oder die Struktur des Wesens


Lupus
30.08.2001, 00:18
jo ...

das ist so eine Sache mit dem Programmieren wenn man es sich selbst beibringt.
In unsere Firma erstelle ich eine Bestellsoftware schon seit über 2 Jahre.
Zunächst nur mit Makros, seit Dez 2000 fange ich an a bissel in VBA rumzutricksen.

Für Chefs ist das ja nix anners wie mir Word und Excel ein Serienbrief zu erstellen und hat ständig Änderungswünsche.
Eigentlich wollte ich mal die Software Dokumentieren damit ich bei den vielen Versionen nicht den Überblick verliere welche Version kann was und welcher Kunde hat sie.
Wie ist der Datenverlauf, welche Daten liegen auf dem Server welche rechte hat der User mit den Daten usw.

Doch stehe ich da vor meiner Excel Tabelle und habe keine Ahnung wie man so etwas am besten macht.
Ich denke das die meisten Forumsteilnehmer etwas mehr Erfahrung haben wie ich und bestimmt hilfreiche Tips geben können worauf ich da achten muß.

Gruß undokumentierter Lupus

Ohnesorg
30.08.2001, 08:52
Hi Lupus, aaler Hessekopp... :D

Dokumentationen, das liebste Thema eines Programmierers. Hier darf er seinem Schreibwahn freien Lauf lassen, mit Screenshots herumschmeißen... und sie HASSEN!

Was in eine Doku gehört?
Relativ einfach:

Deckblatt (ist logisch)

Inhaltsverzeichnis (auch logisch)

Technische Voraussetzungen an das System
- Also Prozessor, RAM, HDD-Speicher, der zur Installation frei sein sollte

Versionshinweise der verwendeten Programme
- VB, VBA, Access, Betriebssystem, Netzwerkclient sowie alle Programme, die von Deinem Programm gestartet oder anderweitig verwendet werden.

Die Funktionalitäten, die von Deinem Tool/Programm erledigt werden

Komplette Bedienungsanleitung mit Unterstützung durch Screenshots

Glossar, in dem Fachausdrücke erklärt werden

ggf. Einen Anhang, der je nach Versionen eine Ergäntzung zum Grundprogramm (der ersten Version) darstellt. Wird aber nur benötigt, wenn die erste Version noch aktiv verwendet wird. Solltest Du lediglich eine Version in Aktion haben, erübrigt sich das.

ACHTUNG!
Schreibe Deine Doku niemals so, dass sie nur ein Fachmann versteht. Gehe grundsätzlich immer vom DAU aus und dass dieser es verstehen muss. Lass ggf einen Freund - der von programmiertechnischem Fachchinesisch keine Ahnung hat - nachlesen und mit dem Programm spielen. So erfährst Du, ob die Doku gut geschrieben ist.

Noch ein ACHTUNG!
Erstelle in jedem Fall einen Anhang mit einer technischen Dokumentation.
Darin steht geschrieben, welche Tabelle Deiner Datenbank welche Werte erhält und wie sie dort hinein kommen.
Makros sind in ihrem Aufbau und ihrer Arbeitsweise erklärt.
Module sind in Form des Quelltextes erklärt.
Hier kannst Du den Leser mit Fachchinesisch überrollen, da dieser Bestandteil lediglich für die KollegInnen da ist, die Dich ggf. vertreten und weiter daran basteln müssen, während Du nicht da bist.

Drittes ACHTUNG
Die Dokumentation steht und fällt mit Deiner Datenbank!
Sollte die Datenbank weiter vertrieben werden - Bsp. Zweigstellen, Schwesterfirmen, Tochterfirmen u. ä. - ist die Dokumentation das, was die Datenbank retten kann.
Ändert sich Deine Datenbank im Layout oder in Funktionalitäten, muss die Doku ebenfalls mitgeändert werden! So verhinderst Du, dass Du nach der dritten Änderung die komplette Doku neu geschrieben werden muss.


Das sollte aber reichen, für den Anfang.
Meine Datenbank besteht aus ca. 35 Formularen und erfüllt schon ein paar Aufgaben.... Für die Doku habe ich 5 Wochen gebraucht, bis sie an den Konzern gehen konnte... Dementsprechend wünsche ich Dir viel Spaß dabei!

Gruß vom Kleister-Meister Ohnesorg

Nockenwelle
30.08.2001, 17:36
Hi Lupus,

Ich rätsel hier gerade an einem Beweissicherungsverfahren.
Ist 'ne unschöne Sache, aber die Software, die wir beauftragt hatten war einfach miserabel umgesetzt.

Der vom Gericht bestellte Gutachter schreibt da unter anderm, dass es schon ein alleiniger Grund ist eine Software nicht abzunehmen, wenn Sie nicht ausreichend dokumentiert ist. D. h. jeder dem du deine Sachen verkaufst kann dir allein schon aus diesem Mangel einen Strick drehen.
Es gibt da Literatur zu. Ich schau morgen noch mal ins Gutachten(Ich glaub', da stand ein Verweis dazu)

Cu



[Dieser Beitrag wurde von Nockenwelle am 30.08.2001 editiert.]

Lupus
31.08.2001, 23:20
@Ohnesorg
na das hättest du mal zu mir sagen sollen .. tz tz aaler Hessekopp ... :D

Hört sich an als wäre das mehr arbeit wie die Entwicklung selbst ... oje ...
Die Punkte und die Achtungs sind mir schon klar. So ein bisschen jedenfalls ...
Dachte eigentlich mehr an eine hilfreiche Form um den Entwicklungsverlauf (kann ja immer wieder neue Versionen geben).
Denn die Bestellsoftware die ich mal mit Access 2.0 angefangen (nur Makros). Sie hat immer wieder geänderte und neue Funktionen bekommen.
Diese sinnvoll zu verfolgen fällt mir so was von schwer .... (liegt aber bestimmt auch an meiner Faulheit :D)
Was ich suche ist eine vernünftige Form der Doku.
Ich wollte erst für jedes Formular eine Exceltabelle machen, dort für jedes Feld eine Spalte für Funktion und des Datenverlaufs (also, wo die Daten hingehen), aber des ist ja soviel Arbeit und wirkt so :confused: Konfus.

Oder ist das ein Thema wo jeder Entwickler (huch .. ich nenne mich Entwickler und nimmer DAU) seinen eigenen Weg suchen sollte ? Aber es gibt doch bestimmt ein paar Beispiele und Tipps zu dem Thema ?


@Nockenwelle
Viel Glück dabei.
Die Literatur würde mich schon interessieren.
Nur gut das nicht ich es verkaufe, sondern die Firma in der ich arbeite ... :D

Gruß und danke Lupus

Ohnesorg
03.09.2001, 08:49
Hi Hesseko... Äh Lupus! :D :D
*Autsch!* Nicht schlagen! :D

Den genauen Weg, den die Daten in Deiner Datenbank zurücklegen benötigst Du lediglich für die Technische Doku. Dem User ist es grundsätzlich nicht klar, was hinter einer Software alles steckt.
Er würde es auch nicht verstehen, dass eine Datenbank im Grunde genommen nichts anderes ist, als eine Ansammlung von Tabellen und Abfragen.
"Wieso Tabellen? Ich dachte Tabellen werden in Excel verwendet?!"

Du musst grundlegend unterscheiden zwischen einer Technischen und einer Anwender bezogenen Doku.
Der Verlauf der Daten läßt sich besser über ein sogenanntes Struktogramm der Tabellen erklären. Eine grafische Darstellung der Datenverläufe wird besser aufgenommen und ist übersichtlicher, als eine Textversion.
Es gibt Programme, mit denen Du solche Struktogramme ganz einfach erstellen kannst. Leider habe ich so etwas nicht. Die gibt es aber mit Sicherheit auch kostenlos zum Downloaden. ;)

Gruß vom Kleister-Meister

Lupus
03.09.2001, 10:16
Hi ..

isch schlage nicht, bin pazifist oder wie das heißt.
und wenn ich schlage .. dann ganz gewaltfrei :D

Mit Struktogramme meinst du etwa sowas wie FlowCharter ? Flussdiagrame und so ?

Gruß gewaltfreierbrutaler Lupus

Nockenwelle
03.09.2001, 23:15
Hi Lupus,

danke. Ich denke, das Ding hab' ich in Grund und Boden getestet :)
Der Sachverständige beziffert den Kostenaufwand für die Behebung der Fehler mit 190.000 Ohren. Dabei war ich im Beweisverfahren Teilweise noch 'zu fair'. Ich hätte evtl. auch das doppelte herausbekommen können(was reeller wäre). Das ist etwas zu viel, um mal eben drüber hinweg zu sehen. Zur Erstellung der Doku sind da 45.000 Märker inbegriffen.
Die Sache ist für mich damit vom Tisch(außer, dass da noch ne Klage anhängig wird).

Das nachträgliche Erstellen einer Doku beziffert er im übrigen mit einem Mehraufwand von 50%.

Tja, der Hinweis auf Literatur wahr mehr ein Verweis auf das geltende Computerrecht. Ich hör' mich aber noch mal um - kenne da 'n guten Proggi, der mir noch mehr als einen Gefallen schuldet. Im Heise-Forum hab' ich da mal was gesehen. Bei einigen Kompilern wird sowas weitgehend mitgeliefert.

Müssen wir beim Ruhrtreff Stacheldraht verlegen? Ich mein, ich kenn das...
Wer mag' schon die Hesse? Die mögen sich ja nicht mal selbst :)

Naja, alles was nicht Ruhrgebiet ist, ist ohnehin Bayern oder nutzlos :D :D also 88.

Der Hinweis von Ohnesorg ist ziemlich richtig. Du musst wissen, an wen sich deine Doku wendet. Hast du die technische Doku, und beschreibst du das eigentliche Endergebnis ergibt sich die Anwenderdoku fast von selbst.
Was meinst du eigentlich mit'Datenverlauf'. Hast du eine Kommunikationssoftware mit drin?
Wie lebendig ist deine Software denn noch? Hat sich das ganze jetzt in irgend einer Weise bewährt und stabilisiert(in der Form dass kaum noch Entwicklungsarbeit vonnöten ist)?

Ich hatte mal ne Zeit, da hat sich mein eigener Kenntnisstand zu den Anforderungen fast täglich geändert. Ein Kollege meinte: "Deine Datenbank wächst 'hysterisch'".
War aber auch so.
Da 'ne Doku zu schreiben, ist glatter Irrsinn, weil etwas fehlte->
- Zielvorgabe
- Grobkonzept
- Feinkonzept
in der Reihenfolge. Das Ergebnis ist mittlerweile so klasse, dass man Lieder darüber singt, aber der Weg dahin war steinig.
Sowas mach ich bestimmt nicht nochmal. Ich hab' zwar vom Thema vieles vieles drauf, aber die Probleme ergaben sich dann im Detail.

Mit dem Feinkonzept hättest du schon einen Teil deiner Dokumentation.

Naja, das nächste mal wird alles anders :D

Cu

peppi
03.09.2001, 23:42
pfui Nockenwelle,

was muß ich denn da über die Hessen hören???

Wir sind die nettesten Menschen in gaaaaanz Deutschland. Und wenn wir erst mal unseren Äppelwoi in einigen Mengen intus haben, ist unsere Nettigkeit kaum noch auszuhalten.

Falls ich auch komme (obwohl noch nicht 88 - nur knapp drunter) erwarte ich ja mal mindestens ein bißchen Staubzucker ... Du weißt schon ... !!!

Lupus
05.09.2001, 02:42
@Nockenwelle

uhi uhi .... mit so Sachen muss man sich als Entwickler (oder so wie ich der es mal werden will) rumschlagen ?
Ich glaube ich bleibe bei meinem erlernten beruf als Kfz-Mechaniker. Da ist der ärger nicht so groß.

Die Doku ist vor allem für mich. Für die Anwender bekomme ich diese geschrieben (will mein Chef so, ich wehre mich nicht). Er meint, hat er nicht ganz unrecht, einer der sie benutzt schreibt eher es so das es jemand versteht. Der Entwickler selbst kennt die Software tech. zu gut und geht meist nicht auf das ein was für den User wichtig ist.
Datenverlauf damit meine ich:#
Artikelstamm wird auf dem Server gelassen vom User, Bestellte-Artikel verbleiben auf System vom User.
Bestellung fertig, Bestellung per E-Mail an uns.
Artikel die nicht im Artikelstamm waren, gehen an Einkauf. Der Bestellt und entscheidet ob diese Artikel im Artikelstamm auf Server aufgenommen werden.
Bestellung löschen aber vorher die Daten auf den Server ins Archiv.
Also, von wo nach wo die Daten innerhalb vom Access fließen.
"Deine Datenbank wächst 'hysterisch'"
jepp .. kann man so sagen, bei jedem neuen Kunden wird die Software geändert. Es kommt immer wieder zu Diskussion welche Version wir nun für welchen Kunden nehmen. Ist die Entscheidung getroffen, werden doch wieder Änderungen vorgenommen.
Wir sind flexibel ..... ist auch gut so, sonst hätte ich bald nix mehr zu tun :D

Vielleicht sollte ich doch endlich mal einen Kurs besuchen wo ich das alles erlernen kann. Bisher habe ich versucht (erfolgreich .. mal sich selbst lobend) mir alles selbst beizubringen.
Aber ich denke, es wird immer wieder Sachen geben die man gesagt bekommen muss, weil man nicht draufkommen kann.
Z.B. wie schreibt man eine tech. Doku!

@peppi

so isses ... gelle ...

Gruß aaler Hessekopp und Doku geschädigter Lupus

Ohnesorg
06.09.2001, 08:59
Hi

@Nockenwelle:
Wir gehen doch nicht aufeinander los! Im Grunde genommen lieben wir Hessen uns ohne uns jemals gesehen zu haben... So sind mir Hesseköpp numal.

@Gewaltbrutalfreier Hessekopp Lupus :D
*ich könnte mich wegschmeißen vor lachen*
An Deiner Stelle würde ich es nicht zulassen, dass "irgendein" User die Dokumentation meiner Datenbank übernimmt.
Die Doku ist immerhin auch bestandteil Deiner Daseinsberechtigung im Betrieb!
Übernimmst Du selbst die Doku, kannst Du die Funktionalitäten besonders hervorheben, die Dich bei der Entwicklung fast in den Wahnsinn getrieben haben. Frei nach der Motte: "Eigentlich macht Access sowas ja nicht, aber ICH habe es doch geschafft!!!"

Klar... teilweise hat Dein Chef recht damit, wenn er sagt, dass ein Anwender die Doku für Anwender am Besten schreiben kann. Ist er sich aber auch im Klaren darüber, dass gerade die Funktionen, auf die es ankommt darunter leiden können?

Meine Anwender-Doku wurde von meiner Freundin immer wieder korrekturgelesen. Sie hat den Anwender gespielt, der mit der Doku zurechtkommen muss.

Kleiner Tipp:
Normalerweise gehört auch das Pflichtenheft mit in die Doku. Also: Welche Aufgaben muss die Datenbank am Ende ihrer Entwicklungsphase erledigen können.
Tu Dir selbst einen gefallen und lasse diesen Part weg! Er ist erstens kein Pflichtteil der Datenbank und zweitens kann es passieren, dass Du Dich dadurch selbst wegrationalisierst, sobald Deine Datenbank dieses Pflichtenheft erfüllt!


Im Allgemeinen ist es tatsächlich so, dass eine gründliche, technische Doku nahezu genausoviel Zeit in Anspruch nimmt, wie die Programmierung.

Schreibst Du die technische Doku, hast Du automatisch - bei einer richtigen Aufgliederung - die Anwender Dokumentation mit integriert.

Vom Aufbau her und der Reihenfolge habe ich beigebracht bekommen:
Deckblatt
Inhalt
Einführung (Wie kam es zu dem Programm, kurzbeschreibung, was es alles kann)
Systemvoraussetzungen
Anwender-Dokumentation Frontend (Screenshots ohne Ende)
Anwender-Dokumentation (Schnelleinstieg in die Arbeit mit der Datenbank)
Anwender-Dokumentation Backend (falls vorhanden)
Erklärung zu allen Reports, Listen und Dokumenten, die aus der Datenbank erzeugt werden
Genaueste Beschreibung der Makros
Quelltext im kompletten Auszug
Quelltext-Teile erklärt
Erklärungen zu Abfragen (Was macht welche Abfrage, woher nimmt sie ihre Daten)
Beschreibung der Tabellen (Woher bekommt sie ihre Inhalte, wo werden diese weiterverwendet)
Struktogramm des Datenverlaufs (Flußdiagramm der Wege, die Daten zurücklegen)
Verknüpfungen zu Tabellen
Glossar in dem Fachbegriffe erklärt werden
Stichwortverzeichnis

Ich kann Dir leider nicht mehr geben, als den ungefähren Aufbau einer Dokumentation. Die Enstehungsgeschichte einer Doku ist in keine feste Schiene gesetzt.
Der genaue Aufbau ist vom Schreibstil des Autors, der Entstehungsgeschichte der Datenbank, der Funktionalität der Datenbank sowie vom Aufbau der Datenbank unwahrscheinlich abhängig.

Ich hoffe das hilft Dir soweit weiter.

@All:
Was ist denn nun eigentlich mit dem Ruhrtreff??? Findet da was statt oder wird das Ganze wegen Unterbesetzung gecancelt?

Gruß vom Pattex-Meister (Pattex ist auch Kleister! :D) Ohnesorg :cool:

Nockenwelle
06.09.2001, 13:49
@Lupus
Ja, damit muss ich mich u.a. auch rumschlagen - leider.
Aber was willst du machen. Wir haben eine Software beauftragt, noch einige Zusatzfunktionen zu Word etc. Kost' mal eben 800.000 Ohren- und was ist: Ich bekomme innerhab von 2 Jahren 8 Versionen die allesamt nicht mal annähernd einsatzfähig sind, zur Abnahme hingestellt.
Teilweise fehlten ganze Bereiche. Bei der vorletzten Version konnte man Beispielsweise keine Stammdaten eingeben http://www.ms-office-forum.de/ubb/smile.gif
Sowas kannst du schlecht auf die DAU's loslassen, die hauen dir das einfach um die Ohren(für die bist du dann der A****, der das ganze fabriziert hat)
Also noch eine Chance geben, sonst Geld zurück.
Und dann ging es zur Sache:
- Ablehnungsandrohung mitteilen
- Abnahme durchführen
- Ablehnung schreiben
- Gerichtliches Beweisverfahren einleiten
- Gutachten abwarten
- Gutachten Bewerten und kommentieren
Und soweit ist das nun. Evtl. müssen wir jetzt sofort Klage einreichen, damit uns keine Rechtsansprüche flöten gehen.

So ein Ortstermin des gerichtlichen Sachverständigen ist im übrigen ein ganz eigenes Erlebnis. Da saßen dann 2 Rechtsanwälte, Firmenchef und Entwickler des Softwarehauses, mein Abteilungsleiter, mein Gruppenleiter, 2 Vetreter von verschiedenen Ministerien, meine Kollegin und ich. Über 12 Stunden gingen die Termine. Und es ist, als würde dir jeder, jederzeit auf die Tastatur schauen. So ein Verhör ist dagegen Erholungsurlaub. Zu jederzeit musst du über den gesamten Projektverlauf über jede sch*** Vereinbarung Bescheid wissen, am besten mit Datum, wann und wo etwas niedergelegt bzw. beschlossen worden ist. Über einen Zeitraum von fast 4 Jahren(mittlerweile sind es 6. Der Sachverständige versprach zwar innerhalb von einem Monat das ganze fertig zu bekommen, am Ende waren es 20 Monate).

Und Teil des Beweisverfahrens ist die fehlende Dokumentation. Allerdings nur am Rande-als noch durchzuführende Tätigkeiten. Allerdings treibt die Doku den Streitwert mal eben um 45000 Ohren in die Höhe.

Hab' leider noch keine Antwort von meinem Proggi bekommen-sonst läßt der eigentlich nicht solange auf sich warten.

Cu

Lupus
07.09.2001, 05:43
@Uhukleister Ohnesorg
ich hoffe das mit der Liebe meinst du platonisch :D

Was die Daseinsberechtigung betrifft habe ich weniger Probleme.
In unsere Firma bin ich der einzige (51 Mitarbeiter) der sich in Access auskennt. Auch wenn es um Excel, Word ... bzw. Office oder sonst irgend eine Anwender Software geht. Bin ich immer derjenige der Angesprochen wird (dabei soll ich ja eigentlich Kopierer und Faxgeräte verkaufen, aber dazu bin ich vor 4 Jahren das letzte mal gekommen)
Und bin deshalb auch froh das ich die Arbeit der Bedienungsanleitung abgenommen bekomme.
Was mich bei der Entwicklung in den Wahnsinn treibt bekommt mein Chef sehr gut mit ,er hat sein Büro neben mir und hört regelmäßig wie der Ausdruck "AAAAAAAAAhhhh" bzw. "booooh ... bin ich gut" aus meinem Büro kommt. Oder das stampfen mit den Füssen auf den Boden, auch das nervt ... äh .. hört er.
Das Pflichtenheft schreibe ich selbst und bekommt auch keiner in die Hände.

Ansonsten, denke ich, haben mir die Tipps hier doch sehr geholfen und ich komme damit weiter.
Danke .....danke ... danke

@Nockenwelle

Machst mir ja richtig angst ....

Die Versionen ändern sich von Kunde zu Kunde. Ansonsten ist es immer die gleiche Software.
Fängt an mit so Kleinigkeiten:
Bei einem Kunde heißt Sammelbesteller dort Bestellkoordinator.
Artikel aus dem Katalog werden über Einkauf bestellt, Kunde B darf jeder diese Artikel selber Bestellen. Bei Kunde C muss der Artikel vom Vorgesetzten genehmigt werden.
Kunde D braucht für jede Kostenstelle eine eigene Bestellnummer .... usw.


Ich habe bei der Entwicklung der Software darauf geachtet das sie sich von selbst erklärt (ist nicht so umfangreich in den Funktionen, jedenfalls für den Anwender) und das klappert auch ganz gut. Zumal die Software in dem Organisationsablauf der Anwender angepasst wird.
Testdau's äh .. sorry Testuser die noch nie mit einer Software Artikel bestellt haben, konnten innerhalb weniger Minuten eine Bestellung auslösen.

Gruß danksangenderängstlichergewaltfreierbrutalerhessekopp Lupus

Nockenwelle
07.09.2001, 11:29
Hi Lupus,

solange dein Chef noch so Geräusche hört brauchst du keine Angst zu haben ;)

Cu

Lupus
13.09.2001, 23:40
he ..
das ist mein beitrag, da habe ich das letzte wort http://www.ms-office-forum.de/ubb/biggrin.gif

Nockenwelle
14.09.2001, 00:37
Na, wenn du meinst :D

AWSW
14.09.2001, 01:06
Versteh ich nicht --- ??? --- Was meint der Lupus damit, dass er der letzte in seinem Beitrag sein will --- hmmm???? --- Ahh jetzt hab ich´s auch ---> Uuuups :D

Ohnesorg
14.09.2001, 08:48
DAS IST JA WOHL DAS LETZTE... Wort! :D

AWSW
14.09.2001, 09:23
Hihi - nööö nööö,
glaub ich nich...

Gruß an den nichtimmomentdasletzteworthabendenkleinengelben?ehh:blonden Lupus :D

Lupus
15.09.2001, 12:26
von wegen ... :D

doch ich glaube das Günther das letzte Wort haben wird wenn er den Beitrag schließt :(