Hallo,
ich frage mal in die Runde: Welchen Stellenwert hat für euch die
Dokumentation?
Lest ihr sie überhaupt oder kommt die erstmal in Ablage P?
Ich denke, dass der Großteil der hier versammelten Leute gewisse
Kompetenzen mitbringt und es wird in absehbarer Zeit mein Job sein,
Dokumentation und Datenblätter etc. (generell Papierkrieg, der sich
nicht auf organisatorische Dinge bezieht) zu erledigen.
Daher würde ich ganz gerne ein grobes Gefühl dafür bekommen, was der
normale Industriekunde/professionelle Anwender erwartet. Wie zufrieden
seid ihr mit Unterlagen zu Bauteilen, Anlagen, Teilen, etc.? Legt ihr
darauf überhaupt Wert, d.h. macht euch eine optisch ansprechende
Dokumentation Freude oder muss diese nur im Notfall schnell ihren Zweck
erfüllen?
Mit Dokumentation ist dabei alles mögliche gemeint, beispielsweise
klassische Datenblätter, Bedienungsanleitungen, Ersatzteilkataloge,
Schulungsunterlagen, Konformitätserklärungen, Sicherheitshinweise (sehr
wichtiges Thema für uns!)...
Ja, ich weiß, dass das nicht das favorierte Gebiet der meisten
Ingenieure ist, aber ohne vernünftige Doku geht es spätestens seit dem
Produkthaftungsgesetz nicht mehr.
Arbeitet ihr lieber mit jemanden zusammen, der den Papierkram für euch
macht (dafür werden wir ausgebildet) oder schreibt ihr lieber selbst
bzw. müsst selber schreiben?
Danke für Rückmeldungen.
also ich bin einer der Doku von Firmen bekommt und ich kann dir sagen
wenn das Zeug ein paar Jahre in Betrieb ist, hast Du alles was Du aus
der Inbetirebnahmephase noch weißt vergessen und dann bin ich froh über
jedes Blatt Papier das ich auftreiben kann.
Daher wird keine Rechnung bezahlt, bis die Doku nicht astrein ist
schreiberling schrieb:> ich frage mal in die Runde: Welchen Stellenwert hat für euch die> Dokumentation?
Kommt immer darauf an von welcher Seite du das siehst:
mal ein Beispiel weg von den Elektronik:
Du hast einen Oldtimer (KFZ) und durchaus ein Händchen fürs Schrauben.
Jetzt ist die Kupplung im Eimer und du musst dazu Getriebe ausbauen und
weil man schon mal so weit ist dichtet man getriebe und Kurbelwelle auch
noch neu ab.
Was würdest du da ohne ein möglichst gutes Werkstatthandbuch machen?
Anderes Beispiel: Wie willst du einen µC programmieren ohne gute Doku
seines internen Aufbaus? Egal, ob IO, Timer, A/D Wandler, DMA, etc. pp.
Datenblätter sind unersetzbar.
Optisch Ansprechend ist halt immer die Frage. Es sollte nicht bunt,
kitschig, cool oder sonstwas sein (z.B. ein Firmenlogo als Wasserzeichen
oder sowas).
Gut strukturiert und schlicht. Sprich: Es gibt nur "okay" und "scheiße"
:P
Ersatzteilkataloge sind dahingehend schwierig, dass die Webportale sich
doch leichter durchsuchen lassen :P
Bei BDAs kommt es ganz auf die Thematik an. Beispiel: Oszilloskop vs.
selbsterklärender TV. Oder Kühlschrank.
Bei den rechtlichen Papieren kann ich dir nicht viel dazu sagen, aber
ich denke da geht es ja mehr darum, dass sie vorhanden sind und gut.
durch kann dir sagen, es gibt nix schlimmeres wie wenn die Doku fehlt
oder hanebüchen is.
ich hab grad den Job ne Anlage zu dokumentieren und der der es
verdrahtet hat is ein totaler Chaot der teilweise seine eigenen Notizen
nimmer blickt oder es von nem HiWi machen lassen hat und nicht weiß der
getrieben hat :-)
schreiberling schrieb:> Welchen Stellenwert hat für euch die Dokumentation?
Mit der Konformitätserklärung (CE-Zeichen) wird auch die Dokumentation
Normen- und Vorschriftenkonform (z.B. nach VDI 4500) erklärt. Somit kann
ein Wettbewerber auch bei mangelnder Dokumentation ein ihm unliebsames
Produkt vom Markt verschwinden lassen.
schreiberling schrieb:> Welchen Stellenwert hat für euch die Dokumentation?> Lest ihr sie überhaupt
Vernünftige Doku spart sehr viel Zeit.
Je nach dem, ob es um Software oder Hardware geht:
vernünftig heisst kurz und kompakt, nicht den Müll tausender bedruckter
Blätter den Doxygen generiert. Es geht vor allem um Grundlegendes: Was
muss man installieren und wie einrichten, wie heisst das Startprojekt,
wie testet man, was steckt in den Testfällen, wie ist das Dateiformat.
Wenn neben einen int i; der Kommentar // Zählvariable steht, ist das
einfach nur blöd, wenn neben einem STRING216 aber // Error: File %s not
found steht, spart das das nachschlagen in irgendwelchen Resourcen,
besser wäre natürlich STR_FILE_NOT_FOUND
bei Hardware ist das eine Mappe mit allen Informationen, die man beim
Bau genutzt hat, von Datenformat über Datenblätter bis Spicesimulation,
Schaltplan und Layout, Beschaffungsquellen, gemachte Oszillogramme etc.
also schlicht und einfach alles was mit dem Projekt zu tun hatte kommt
in einen Ordner. Denn wenn du nach 10 Jahren eine Änderung machen sollt,
ist der Entwicklungsrechner garantiert schon verschrottet, und die 3 1/2
Diskette von damals passt auch nicht mehr,
Die Mppe ist sogar gut bei Hobbyprojekten, man vergisst sogar seine
eigene Arbeit.
schreiberling schrieb:> Daher würde ich ganz gerne ein grobes Gefühl dafür bekommen, was der> normale Industriekunde/professionelle Anwender erwartet. Wie zufrieden> seid ihr mit Unterlagen zu Bauteilen, Anlagen, Teilen, etc.? Legt ihr> darauf überhaupt Wert, d.h. macht euch eine optisch ansprechende> Dokumentation Freude oder muss diese nur im Notfall schnell ihren Zweck> erfüllen?
optisch ansprechend ist bei Schulungsunterlagen nett.
Ansonsten NEIN, das muss den Zweck erfüllen.
Meine Lieferanten müssen die Datenblätter selber in die
Dokumentationsdatenbank für das Service and Maintenance mit Metadaten
einpflegen inkl. Sicherheitsdatenblatt, Konformitätserklärung. Fehlt
dies ist es ein "wesentlicher Mangel" der erbrachten Leistung.
vgl. FIDIC Mustervertrag 1.1.6.1, 1.8, 1.10, 7.3 und 9.1
Nach pdf gescannt geht gar nicht. Das ganze muss voll indexierbar sein.
Was nützt denn ein gescannter Ersatzteilkatalog? Nix.
Was nützt eine gescannte Zeichnung? Nix.
Da brauch ich ja ewig um mich da durchzuwühlen. Ausserdem brauch ich
Metadaten, wie den Umsatzsteuer-ID des Herstellers, denn die gleiche ich
mit dem Konkursregister ab.
Es geht ja nicht nur um den Notfall, sondern dass die Anlage auch in
Jahrzehnten noch gewartet oder umgebaut werden kann. Hätten wir das vor
40 Jahren schon gemacht, müsste ich heute das PCB und den Asbest nicht
erst suchen.
Bisphenol A und TBBPA waren Suchworte welche unmittelbar Treffer
ergaben.
schreiberling schrieb:> Wie zufrieden> seid ihr mit Unterlagen zu Bauteilen, Anlagen, Teilen, etc.? Legt ihr> darauf überhaupt Wert, d.h. macht euch eine optisch ansprechende> Dokumentation Freude oder muss diese nur im Notfall schnell ihren Zweck> erfüllen?
Optisch ansprechend muss sie nicht sein, nur überhaupt verfügbar.
Damit meine ich: Vorhanden und auch vom Laptop aus irgendwo zum Download
aufzutreiben. (Zumindest für Standardkrempel)
Die aktuelle Lage ist da sehr düster. Man bekommt doch oft nur ein
Pamphlet mit sinnlosem Inhalt: "Danke für Ihre €€€. Wir sind die
Größten. Sie könnten an diesem Produkt sterben, ist aber nicht unser
Problem. Zum Einschalten grünen Knopf drücken. Technische Daten: Groß.
Schwer. Lila. - Ende der Doku"
Ich brauche keinen Gesetzestext! Ich brauche Schaltpläne, Maßzeichungen,
Sollwerte, Oszi-Bilder, Kalibrierdaten, Prozeduren zum Abgleichen usw.
Die brauche ich auch sofort! Nicht erst über den Firmenserver, nach
Login, NDA Unterzeichnung, ...
Keine Ahnung wie oft ich mir schon was aus Fotos und
Ausschreibungstexten und ähnlichem Müll zusammenreimen musste, weil
entweder 1. die Doku nicht öffentlich ist oder 2. ich nicht der
registrierte Ansprechpartner meines Arbeitgebers bin oder 3. ich wegen
Firmenpolicy da keinen Account haben darf oder 4. das Ding irgendwer
dokumentiert hat der in Rente ist und der Vertriebler das nur verhökert
oder 5. ich nur Doku im Rahmen eines laufenden Projekts von meinem
direkten (bezahlten) Ansprechpartner bekomme, nicht so zwischendurch für
ein altes Produkt das ich nicht verbaut habe.
Die Kunden watschen das natürlich als Ausrede ab wenn man vorm
Schaltschrank steht und wegen so einem Blödsinn nicht weiter kommt.
Selbst mit €€€ winken ("Bereitstellung der IBN-Unterlagen gegen
Berechnung" hilft bei manchen nicht.
Die deutsche Industrie-Elite tut sich da besonders negativ hervor.
Dort liegt es aber auch teilweise an der Firmenkultur, selbst schon
erlebt: Person A dokumentiert nach DIN und Firmen-/Kundenrichtlinie, das
ergibt also bloß ein wasserdichtes Pflichtenheft (Ausschreibungstext) um
sich gegenseitig den Hintern aus der Schusslinie zu halten. Person B
implementiert (unter Anstrengung mit vielen Rückfragen) anhand dieser
"Doku", darf aber selbst nicht dokumentieren!
Die Insider-Info aus den Rückfragen existiert, wird aber noch nicht
einmal firmenintern aufbereitet. Zum Urlaub/Rente/Auslandsjahr gibt es
dann eine Übergabe und viele große Fragezeichen.
Tr schrieb:> Die Insider-Info aus den Rückfragen existiert, wird aber noch nicht> einmal firmenintern aufbereitet. Zum Urlaub/Rente/Auslandsjahr gibt es> dann eine Übergabe und viele große Fragezeichen.
Interessanter wird diese Geschichte noch wenn Doku 3x hin und zurück
übersetzt wurde. Dann sind durch Informationsverlust alle nützlichen
Feinheiten in der Folgeversion einfach verschwunden, die später im
Störfall sehr hilfreich sein könnten.
z.B. altes Beispiel Sonnenfinternis:
https://www.spin.de/forum/msg-archive/7/2006/10/48219
schreiberling schrieb:> macht euch eine optisch ansprechende> Dokumentation Freude oder muss diese nur im Notfall schnell ihren Zweck> erfüllen?
Sie soll ordentlich strukturiert alle Informationen beinhalten die
notwendig sind um es in jeder denkbaren (und undenkbaren) Weise zu
betreiben oder seine Eignung dafür festzustellen.
Wenn etwas in Worten ohne viel mehrdeutiges Geschwurbel nicht vernünftig
oder vollständig zu formulieren ist dann füllt den Platz lieber mit gut
beschrifteten Skizzen und Diagrammen und macht Beispiele. Beispiele sind
immer gut. Beispielschaltungen, Beispielcode.
Wenn es mehr als nur eine Handvoll Seiten hat dann erwarte ich dass das
PDF ein klickbares Inhaltsverzeichnis in der Seitenleiste hat! Verweise
auf Abbildungen, Tabellen, Anhänge, andere Abschnitte im Text bitte auch
alle verlinken.
Dokumentation ist nicht Papierkram. Zum einen weil's eh nicht mehr auf
Papier ist, zum Anderen weil es laengerfristig absolut essentiell ist.
Oops, das Projekt laeuft schon seit 5 Jahren - wie war das nochmals ?
Oops, das Projekt laeuft nun schon seit 10 Jahren - wie war das nochmals
?
Erinnert ihr euch an das Projekt von vor 5 Jahren. Wir moechten das
nochmals, aber besser, ..
Zu jedem Projekt kommen die Startbedingungen, Welches Problem ist zu
loesen, wie Loesen wir's. Der Kontext. Die Ueberlegungen zur Hardware
Entwicklung, Ueberlegungen zur Firmware dazu, und die Ueberlegungen zur
PC Softwareentwicklung. Wobei darunter nicht das Pfichtenheft zu
verstehen ist, sondern der Ablauf. Da steht drin, weshalb eine gewisse
loesung verwendet wurde, und ebenso, wie man's beim naechsten Prototypen
verbessern wuerde, und weswegen. Denn irgendwann geht's raus, und die
naechste Entwicklungsrunde ist vielleicht erst in ein paar Jahre, oder
gar nie. Wenn der Kunde die erste Serie des Produktes zertifiziert und
nachher nur genau das haben will, laesst man vielleicht eine
Weiterentwicklung sein. Vorerst.
Derswegen wird alles zusaetzlich zur Projektdokumentation auf 1. einem
Wiki fuer geordneten Inhalt und 2. auf einem Blog fuer den zeitlichen
Ablauf festgehalten.
Zwölf M. schrieb:> Da steht drin, weshalb eine gewisse> loesung verwendet wurde
Was alles nicht funktioniert hat und warum, ist mindestens so wichtig
wie die am Ende gewählte Lösung. Ich kenne das aus dem
wissenschaftlichen Bereich, wo man in Sackgassen landet und danach
merkt, dass diese Fehlversuche schon in längst bekannten
Veröffentlichungen zwischen den Zeilen angedeutet wurden. Misserfolge
veröffentlicht leider keiner.
> Wiki fuer geordneten Inhalt
Und das muss niedrigschwellig und formlos benutzbar sein.
Zum Thema technische Dokumentation und die gesetlichen Vorgaben gibt es
einiges an Literatur und außerdem VDI Richtlinien. Das ist alles schon
ziemlich genau geregelt und vorgegeben was darein muss. Grundsätzlich
gilt in der EU, dass die Dokumentation Teil des Produkts ist.
Fe3C schrieb:> Zum Thema technische Dokumentation und die gesetlichen Vorgaben gibt es> einiges an Literatur und außerdem VDI Richtlinien.
OK!
Was ist mit der sonstigen Dokumentation, die so anfällt?
Messungen bei XY, die nach 2 Jahren mit einem Nachfolgemodell verglichen
werden sollen.
Ja es gab Messungen, ja die liegen irgendwo auf dem Server, nein der die
Messungen gemacht hat ist schon wieder weg, frag mal den Dingens, der
hat aber Urlaub, ...
Und falls man die Messungen gefunden hat, kann man auch nur raten, was
der damals wie mit was gemessen hat.
Schlechte Dokumentation merkt man erst, wenn es schon zu spät ist.
@Lu Ru Ganz genau!
Die Doku hat einfach einen essentiellen Stellenwert.
Was ich schon in Firmenprojekten gesehen habe : ein Graus!
Viele Firmen könnten sich soviel Kosten, Verzug in ihren Projekten
sparen, wenn sie nur wollten.
Was ich schon gehört habe: Doku ist der beste Code!
Keine Zeit es gibt keine Doku vielleicht später..
Schon mein SW Prof hat gesagt bevor überhaupt etwas entwickelt wird:
Dokumentieren, Dokumentation
Dann bevor die erste Zeile codet wird:
Tests schreiben! (Test driven Development )
Und wieder: Dokumentieren, Dokumentation
Dann anfangen mit dem entwickeln.
Und wieder: Dokumentieren, Dokumentation
Wie auch vorher schon genannt wurde:
Evtl auch eine zeitlich nachvollziehbarer Log (Blog)
Dann eine Grunddokumentation
Evtl noch ein HTML Doc aus dem Code generieren (zB Java Doc etc)
Mein Grundsatz:
Ohne Doku kein Projekt mehr! Auch wenn sie etwas kostet am Anfang, der
Aufwand bietet langfristig mehr als genug Mehrwert!
Das erkennen oft Projektleider/Schäffs etc. nicht. Da sie 1. keine
Ahnung von der Materie haben (und auch wirklich deppert sind!), oder in
ihrem Leben noch nie in einer einzigen SW Engineering Vorlesung gesessen
sind...
Leider!
schreiberling schrieb:> Welchen Stellenwert hat für euch die> Dokumentation?
Hängt vom Produkt ab.
> Lest ihr sie überhaupt oder kommt die erstmal in Ablage P?
Siehe oben. Beispiel: Die Holde kaufte kürzlich einen neuen Satz Messer
für die Küche. Der kam mit Dokumentation in Form eines dieser großen A1
Faltblätter. In X Sprachen stand nur immer wieder der gleiche
Scheißedreck drin -> Ablage P.
> Wie zufrieden> seid ihr mit Unterlagen zu Bauteilen, Anlagen, Teilen, etc.?
Wie soll man das beantworten? Die Bandbreite reicht von "meinen die
Idioten das ernst!?" bis zu "aber das ist mal gut gemacht!"
> Legt ihr> darauf überhaupt Wert,
Bei komplizierteren Dingen als Messer, natürlich.
> d.h. macht euch eine optisch ansprechende> Dokumentation Freude
Form follows function. Sie darf gerne ansprechend gestaltet sein. Die
Gestaltung darf aber nicht vom eigentlichen Zweck ablenken. Minimum bei
der Gestaltung ist, dass die Jahrhunderte alten Grundregeln der
Typographie und des Schriftsatzes eingehalten werden.
> oder muss diese nur im Notfall schnell ihren Zweck> erfüllen?
Nicht nur im Notfall muss sie den gerade anstehenden Zweck schnell
erfüllen.
> Arbeitet ihr lieber mit jemanden zusammen, der den Papierkram für euch> macht (dafür werden wir ausgebildet)
Auch das kann ich nicht beantworten. Ich habe schon mit Technical
Writern zusammenarbeiten müssen, die nicht mal in der Lage gewesen wären
die Funktion eine Kloschüssel richtig zu beschreiben. Da macht man es
lieber selber.
Am anderen Ende des Spektrums waren Technical Writer die mir mal so
nebenbei ein paar Fehler aus einer Berechnung rausgepopelt haben.
Entscheidend ist, ob es am Ende für mich mehr oder weniger Arbeit ist.
> oder schreibt ihr lieber selbst> bzw. müsst selber schreiben?
Das hängt vom Thema ab. Manches ist einfach ein Qual. Besonders alles wo
irgendwo Juristen mit im Spiel sind. Meine schlimmsten Schreiberlebnisse
habe ich beim Schreiben von Entwürfen für Patente. Da kannst du
schreiben was du willst, der Herr Patentanwalt macht aus dem Entwurf
gequirlte juristische Elefantenscheiße.
Ich darf anmerken, dass es verschiedene Arten von Dokumentation
(beziehungsweise insgesamt von dem "Schreiben") gibt.
Eine Recherche ergab, dass das gesamte Fach sich "Technische
Kommunikation" nennt. Der Verband, die Tekom, scheint nicht so groß wie
der VDI (wen es interessiert :-)), aber er ist EU- weit zumindest
aufgestellt (mehr ist mir unklar).
Die Internetseite ist tekom.de bwziehungsweise tekom.eu. Auf XING wird
ein Forum betrieben, in das man evtl. aufgenommen wird (dann spart man
die Mitgliedsgebühr; jedenfalls hierfür, für die Newsgroup auf XING
fällt keine an).
Mir scheint das eine gute Sache; ist aber der Verband für die gesamte
"Technische Kommunikation" (juhu, wir (?) haben eine berufsständische
Vertretung neben dem VDI !).
Bin übrigens auch Technik- Schreiber, aber inhaltlich für längere
Themen, die Doktorarbeiten entsprechen, oder sogenannten (kurzen)
Papers.
Vielleicht sollte man das Wörtchen "gute" Mal einfügen.
Es gibt praktisch keinen Bereich mehr, der ohne ordentliche
Dokumentation auskommt.
Ein ordentlicher Klumpen Source Code ist ohne Dokumentation schon nach
kurzer Zeit nur noch Mist. Vor allem, wenn der Leser nicht ein eineiiger
Zwilling des Schreibers ist.
Ein Manual ist im Grunde genommen auch nichts anderes als eine
Dokumentation. Natürlich kann man sich auch mit der geht-so-besser
Methode nähern. Dann aber wird man sehr schnell feststellen, dass die
600 Seiten nicht so ganz für die Katz waren.
Wenn Dir eine Mahnung ins Haus flattert, die auf eine Rechnung verweist,
die vor einem halben Jahr gestellt wurde, so kann eine eigene
Dokumentation helfen - oder die der Bank.
In allen sicherheitskritischen Bereichen also praktisch der ganzen
Produktion (Medizin, Auto, Lebensmittel und, und, und) ist diese sogar -
ich finde zurecht - vorgeschrieben. Deine Erben haben dann oft sogar
noch die Möglichkeit, Ihr Leid mit Geld zu lindern. Wenn die letzte
Pille umwerfend war, oder die Bremse nicht das hielt, was der Hersteller
versprochen hat.
Sebastian S. schrieb:> Es gibt praktisch keinen Bereich mehr, der ohne ordentliche> Dokumentation auskommt.
Erstaunlicherweise kommen alle Apps ohne jede Dokumentation aus ... aber
leider nicht alle Anwender. ;-)
Sebastian S. schrieb:> Es gibt praktisch keinen Bereich mehr, der ohne ordentliche> Dokumentation auskommt.
Theoretisch 100% richtig!
Praktisch besteht da häufig Nachholbedarf.
Sebastian S. schrieb:> In allen sicherheitskritischen Bereichen also praktisch der ganzen> Produktion (Medizin, Auto, Lebensmittel und, und, und) ist diese sogar -> ich finde zurecht - vorgeschrieben. Deine Erben haben dann oft sogar> noch die Möglichkeit, Ihr Leid mit Geld zu lindern. Wenn die letzte> Pille umwerfend war, oder die Bremse nicht das hielt, was der Hersteller> versprochen hat.
Da ist das Problem!
Die unzureichende oder überhaupt nicht vorhandene Dokumentation fällt
einem oft erst auf die Füsse, wenn es gekracht hat oder "die letzte
Pille umwerfend war".
Wobei die Dokumentation bei "Pillen", so hoffe ich schon deutlich besser
kontrolliert werden, bevor diese auf den Markt kommen, als bei Apps.
Sebastian S. schrieb:> Vielleicht sollte man das Wörtchen "gute" Mal einfügen.
Nee, im Ernst, ich lasse das hier ausdrücklich als Lob deines Beitrages
ein. (Im medizinischen Bereich ist es übrigens gerne ein Problem, wenn
das umwerfende Medikament bereits vom Markt genommen wurde, und zwar
eben wegen der umwerfenden Wirkung).
Das nur nebenbei, weil ich das Problem aktuell beobachten konnte: die
Dokumentation gibt der (ansonsten gute) Pharmahersteller schlicht nicht
'raus.
Langer Rede kurzer Sinn: Gut gegeben, dein Beitrag. Sehr anschlaulich.
