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.
Dokumentation ist der Unterschied zwischen einem guten Software-Entwickler und einem schlechten Programmier-Frickler...
@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.
Thread beobachten
Seitenaufteilung abschaltenBitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.