Rant: mangelhafte Dokumentationen

Für gestückelte Anleitungen nach jedem Update habe ich trotzdem kein Verständnis.
Eben. Genau da ist der Vorteil, dass die Anleitung immer komplett zur Version passt.

Was übrigens auch in der Umkehrung nicht ok ist: Anleitungen von alten Firmware-Versionen sang und klanglos von der Webseite wegzunehmen.

Manuals sollten eigentlich (a) format-frei und (b) device-neutral erstellt werden.
Auch die mündliche Erzählung oder Schrift auf Pergamentrolle ist ein Format und erfordert ein Device (Ohr oder Auge).

Aber im Ernst: jede Anleitung hat ein Format; selbst wenn es nur die Sprache der Anleitung ist. Und zB da haben HTML- oder PDF-Anleitungen den Vorteil, dass Du Sie in Übersetzungsautomaten schicken kannst: SQ-3P Anleitung auf ungarisch? Bitte sehr:
 

Anhänge

  • SQ-3P MIDI-sequencer on Arduino hu.pdf
    343,4 KB · Aufrufe: 6
Jetzt rat mal was ich als erstes mit der Anleitung zum SQ-3P gemacht habe. :mrgreen:

(Die find ich übrigens gut gelungen, fast perfekt.)
 
Die Ausgabe ist immer an ein Format und einen Device gebunden, da bin ich bei dir. Aber heute sollte die Erstellung/Speicherung von Inhalten unabhängig von der Ausgabe/Präsentation sein, so dass Inhalte dynamisch für den jeweilgen Use Case gerendert werden können. Das kann für dich dann HTML sein, für Jörg PDF, ....

Auf diese Weise können und müssen Inhalte auch nur an einem Ort zentral bewirtschaftet werden.

News- und Media-Netzwerke machen das zB so. Da wird ein Inhalt (zB Artikel) einmal zentral medienneutral erstellt und dann als semi-strukturierter Inhalt konsumierenden Anwendungen bereitgestellt, die Use Case spezifisch die Ausgabe rendern.
 
Da wird ein Inhalt (zB Artikel) einmal zentral medienneutral erstellt und dann als semi-strukturierter Inhalt konsumierenden Anwendungen bereitgestellt, die Use Case spezifisch die Ausgabe rendern.
Dass das firmenintern anders erstellt wird, ist bitte klar. Die "Bedienungs-Anleitung" unserer Software hatte im PDF-Format zuletzt 1200 Seiten. Sowas macht man nicht mehr im HTML-WYSIWYG-Editor. Nachdem wir festgestellt haben, dass niemand mehr das PDF runterlädt, stellen wir es nur noch online als HTML bereit, (auf Anfrage auch als Archiv).
 
Die "Bedienungs-Anleitung" unserer Software hatte im PDF-Format zuletzt 1200 Seiten. Sowas macht man nicht mehr im HTML-WYSIWYG-Editor. Nachdem wir festgestellt haben, dass niemand mehr das PDF runterlädt, stellen wir es nur noch online als HTML bereit, (auf Anfrage auch als Archiv).
Sieht gut aus. In welchem CMS bzw. Redaktionssystem macht ihr das, wenn ich fragen darf? Und ist der PDF-Export brauchbar? (Gerne auch PN, da doch ziemlich OT)

Übrigens, das mit den PDFs, die sich keine Sau runterlädt, kenn ich nur zu gut. Leider sind wir gegenüber bestimmten Kunden vertraglich zu PDF bzw. PDF-A verpflichtet.
 
Ich hab nix gegen .pdf, was mich frustriert sind Wikis.

Das sind meistens unglaublich wortreiche und dabei inhaltsleere und unvollständige unstrukturierte Texthalden.
 
Ich finds es unter anderem nervig wenn die Begriffe und Referenzen, Inhaltsangabe etc. mit den dazugehörigen Seiten innerhalb des PDFs nicht verlinkt sind.

genau, vor allem fehlen soundbeispiele und firmware updates, das wäre das mindeste was ich von einem gedruckten handbuch in 2023 erwarten würde. :P
 
Und warum wird seit vielen Jahren die SysEx Dokumentation von Geräten immer auf den St. Nimmerleinstag verschoben?
Beim Waldorf MicroWave war die vorbildlich.

Wenn es SysEx bei einem Gerät gibt, so wird der Entwickler ja genau wissen, was da was genau macht. Der Entwickler wird das auch im Code sicherlich dokumentieren. Warum dann bitte nicht veröffentlichen? Haben die Firmen Angst vor Editoren anderer, auch wenn sie selber nie welche herausgebracht haben und werden?

Das mit den fehlenden oder unvollständigen SysEx Dokumentationen finde ich auch ziemlich kacke.
Und Angst vor 3rd Party Editoren sollten die Hersteller eigentlich auch nicht haben müssen.
Im Gegenteil, solche 3rd Party Editoren erhöhen ja eher den Gebrauchswert der Geräte.
Da sollten die Hersteller eigentlich dran interessiert sein.

Ganz allgemein finde ich aber, daß eine ausführliche Bedienungsanleitung in gedruckter Form zum Lieferumfang einfach dazugehört - Kein wenn und kein aber.

Und online sollten die Bedienungsanleitungen als PDF zum Download bereitstehen.
Ich lade mir die Manuals der Geräte die ich besitze zusätzlich immer herunter
Wenn es von einem Manual unterschiedliche überarbeitete Versionen gibt (zB bei Firmware Updates), dann sollten weiterhin zusätzlich auch die alten Versionen entsprechend gekennzeichnet, verfügbar bleiben.
 
Gibts das wirklich? Kannst du mal ein Beispiel nennen?

dass die notwendigkeit besteht eine ordentliche dokumentation mitzuliefern ist bei software einer der gründe, warum tausende von sachen est gar nicht öffentlich verbreitet werden.

und du siehst ja, dass die leute schon meckern, wenn irgendeine kleinigkeit fehlt, falsch ist oder schelcht erklärt wird.

ich habe auch noch nie eine anleitung gelesen, ich finde so etwas wie waschmaschine, waldorf microwave oder photoshop eignetlich selbsterklärend. es ist aber schon gut, die handbücher im schrank zu haben udn sich darauf verlassen zu können, dass man notfalls mal schnell nachschlagen kann.

früher hast du dir einen AKAI S-900 gekauft und in der anleitung wurde dir erst mal erklärt, was das samplingtheorem ist und wie und warum die technik überhaupt funktioniert. das war echt toll.
heute verstecken sich hersteller hinter buzzwords und leiten ihre docs mit irgendeinem werbeblabla ein um dich davon zu überzeugen, wie toll das ist, was du da gekauft hast - und dann ist aber die übersicht über die parameter oder das midi unvollständig.
 
Du betreibst einen Satire-Account, richtig?

ich arbeite mit hunderten von geräten und programmen, da habe ich gar keine zeit anleitungen zu lesen.

ich bin ich 30 jahren musikmachen grob geschätzt 10 mal zum bücherschrank gelaufen weil ich irgendeine tastenkombination o.ä. vergessen hatte.

und wenn ich mich so umschaue, kenne ich auch sonst niemand, der sich vor der benutzung eines synthesizers oder bildbearbeitungsprogramms erst mal das handbuch durchlesen würde.

das normale "handbuch" ist das 32 zeichen diplay, der drehregler und die ohren.
 
Witzbold.
Ich könnte dir sofort jede Menge Dinge bei bestimmten Synthesizern nennen, auf die du ohne Dokumentation niemals kommen würdest.
Aber wenn du mit "hunderten" Tools arbeitest, reicht dir vermutlich ein sehr oberflächliches Wissen zu jedem einzelnen Tool.
 
das ist überhaupt nicht witzig, das ist ganz normal.

dinge, die auf die du ohne buch nicht kommst, auf die kommst du auch mit buch nicht.

um erfolgreich mit photoshop zu arbeiten musst du wissen wie man olivgrün mischt, welche third party filter sich für dich lohnen könnten, wie man klassische und gotische schrifttypen voneinander unterscheidet und wie bildkomposition und druckvorstufenverfahren funktionieren.

nichts davon steht im handbuch. im handbuch stehen solche dinge wie "um eine datei abzuspeichern, drücken sie sie tasten apfel und S gleichzeitig. es erscheint sodann ein sonderbarer dialog, in dem sie den namen für die datei eingeben können! ist das nicht toll? bei fragen rufen sie unseren support an, die wissen das auch nicht."

das findet man durch das durchprobieren aller menufunktionen schneller heraus als durch das auswendiglernen des handbuches.
 
Zuletzt bearbeitet:
Dass das firmenintern anders erstellt wird, ist bitte klar. Die "Bedienungs-Anleitung" unserer Software hatte im PDF-Format zuletzt 1200 Seiten. Sowas macht man nicht mehr im HTML-WYSIWYG-Editor. Nachdem wir festgestellt haben, dass niemand mehr das PDF runterlädt, stellen wir es nur noch online als HTML bereit, (auf Anfrage auch als Archiv).
Gut und schön...
Die Seiten "GUI Design and customization" und "System operation" kann ich schon mal im Android Firefox nicht bis nach unten durchscrollen...
Dann lieber pdf? Das hat mich bisher vor Seitenumbruchproblemchen weitgehend bewahrt.
 
Zuletzt bearbeitet:
PDF dient nur noch dazu, einen gewissen Informations-Stand offline verfügbar zu machen.
Das halte ich für den größten Vorteil an einem PDF. Das angehängte PDF in einer Mail kann ich Jahre später noch öffnen, was bei einer Verlinkung auf ein HTML sehr wahrscheinlich nicht mehr funktioniert.
Stimme dir aber zu, dass man mit einer guten Online Manual immer und einfach up to date ist.
 
Manche Anleitungen sind total für Einsteiger und sagen aber dem Pro nicht auf 1-2 Seiten, wo dies oder das sind, es gibt so 1-2 Seiter und es gibt Buchla (Keinseiter) und ich hätte gern, dass alles in einer verständlichen klaren Weise (d/engl. egal) suchbar in einem elektronischen Text da sind - Ideal so, dass man den mitnehmen kann, also nicht nur online.

Weil - manche haben ja eine komische Prozedur - Beispiel?
System 1m hat einen Editmodus, da sind bestimmte Taster ein bestimmter MIDI Modus - und das ist nicht klar, was genau was ist, wenn man das eben nicht weiss - für sowas braucht JEDER diese Anleitungen - weil das einfach nicht selbsterklärend sein kann - Sync=THRU MODE, Ringmod = ... sowas zB.
Es ist auch nicht sicher, dass jeder weiss, dass man am Rad drehen kann wenn man Sync und nochwas festhält um die OSCs gegeneinander im Halbtonschritt zu tunen - aber es geht halt.
Dann kann man den MIDI Port von hinten nach oben schalten, je nach Einbau.


Das ist also alles sinnvoll - aber nicht offensichtlich.

SOWAS hätt ich gern in einer suchbaren Liste und nicht in 30 Schriften und superwinzig sondern gleichberechtigt - ideal mit dem Schlagwort was jeder dazu sagen würde.
ZB ..

sie haben ein MONSTERFALTBLATT und in der Mitte rechts gibt es so eine Tabelle wo alles drin steht
- Bis Version 1.0 oder so, was dazu kam machen einige gern in ein weiteres PDF - das ist doof, man sollte eins machen mit allem und richtigen korrekten Seitenzahlen und Index - Apfel F und man findet es - mit guter Gliederung sogar noch schneller.

Und ich les sowas auch nicht oder selten - aber wenn ich teste tue ich es wenn ich eine bekomme - oft gibt's eh keine - oder sie ist unfertig oder enthält die Neuigkeiten nicht - das ist aber auch normal. Wenn das Ding offiziell ist- sollte es kommen und sich einer die Mühe machen das sinnvoll zusammen zu gießen.

Dann auch nicht mit komischen Halbdeusch arbeiten - dann les ich lieber das englische Ding, weil diese Begriffe führen schonmal irre.
Es gibt auch Anleitungen wo schlicht was fehlt oder was das einfach falsch beschrieben ist.


Das alles ist kein Beinbruch, wenn man es beseitigt, dieses moderne Internet..
Ich kenne auch von "guten" Firmen schwache Anleitungen. Manche sind auch etwas wortreich oder unnötig und so weiter, so wie meine Bestätigung hier.

Und nun..
macht was draus.

PS - bei Neuem ist es nicht doof wenn man weiss, WAS NEU ist aber es ist für NEUE User noch besser es ist integriert in einem Dokument und nicht als Anhang. Das macht manchmal auch wahnsinnig.
Sie wollen in den 38 Stock? Ja aber sie sind doch im und haben sie da schon in S12 geguckt? Da steht wie ...
 
Zuletzt bearbeitet:
Hehe, mit der Einstellung warst du als Schüler vermutlich der Albtraum deiner Lehrer. :D

das ist zweifesfrei der fall, das würden sie dir alle sofort bestätigen. :P

nur ich kann meine geräte bedienen, meine lehrer können das bis heute nicht.


um mal ein konkretes beispiel zu thema zu geben: als ich irgendwann das erste mal mit cubase audio angefangen habe, habe ich das aufnehmen von audio 3 tage lang nicht hinbekommen.
meine methode alles durch trial und error lernen zu wollen, scheitere hier also zunächst.
also habe ich beim fachhändler und/oder mir zur verfügung stehende ältere kollegen grfagt "du, wie geht denn das?" und habe nach 2 minuten die korrekte anwort bekommen.

jemand wie jörg hätte hingegen erst mal das 300-seitige manual durchgelesen bevor er überhaupt den rechner einschaltet. wozu er ja dann erst mal das apple handbuch komplett auswendig lernen muss. und das für die steckdose und das zum schuhe zubinden und das zum zähneputzen.

vielleicht steht es da auch irgendwo im hndbuch wie das geht, aber dann sicher sehr kryptisch und umständlich. die methode "frag deinen kollegen" ist halt einfach viel schneller als ins handbuch zu schauen, und schon alleine deswegen zu bevorzugen.

und während anleitungsleser zwischen 1990 und 2000 dann zehn lang bücher gelesen hätten, habe ich in der zeit 800 plug-ins, diverse hosts, und auch mein eigenes bildbearbeitungsprogramm programmiert - natürlich ohne irgendwas zu dokumentieren - und hatte viel spass dabei.


wer nicht ausprobiert, ob man mit methode B nicht viel weiter kommt wie mit methode A, wird irgendwann so ineffektiv lernen, dass er dann irgendwann dumm sterben muss.

[hier rant zum akademischen methodenzwang einfügen.]

unabhängig davon gebe ich ihm trotzdem uneingeschränkt recht, dass man insbesondere bei teureren produkten erwarten kann, dass alles auch irgendwo korrekt dokumentiert ist und dass handbücher, tutorials und jahrzehntelanger support für so technikzeug eigentlich dazugehören.
 
Zuletzt bearbeitet:
"Jemand wie Jörg" :lol:
Meine Herangehensweise ist normalerweise die: erst mal ransetzen und ausprobieren, schauen wie weit ich komme. (Beim Antesten im Geschäft oder bei Synth Meetings geht es ja auch gar nicht anders.)
Da ich auch schon über 30 Jahren dabei bin und viele, viele Synths besessen habe, komme ich meistens schon ziemlich weit.
Dann aber auch irgendwann die Dokus systematisch durchlesen. So stelle ich sicher, dass mir nichts entgeht, und Spaß macht mir das auch. Ist ja auch nicht so als würde das total lange dauern.
Zu behaupten, man könne ein Instrument wie z.B. den Montage einfach durch Rumprobieren vollständig kennenlernen, ist echt Unfug.
 


News

Zurück
Oben