mikrocontroller.net

Forum: Offtopic Schlechte oder fehlende Dokus


Autor: Stefan Helmert (Firma: dm2sh) (stefan_helmert)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Hallo,

häufig fällt mir auf, dass zu vielen Dingen, eher bei Software als bei 
Hardware, aber auch da, keine oder nur sehr spärliche Dokumentationen 
vorhanden sind, die dann meist noch einige Fehler enthalten.
Woran liegt das?
Ich denke, wenn es keine Doku gibt, kann man das Produkt ja gar nicht 
verwenden. Am schlimmsten sieht das im Bereich Linux-Kernel aus. Viele 
quelloffene Komponenten sind überhaupt nicht dokumentiert - oder sind 
diese nur firmenintern dokumentiert und unter Verschluss gehalten? Evtl. 
um die Sicherheit zu erhöhen, dass ein potentieller Hacker die 
Sicherheitslücken und Schwachstellen nicht auf dem Silbertablett 
serviert bekommt? Oder soll möglichst die Funktionsweise der zugehörigen 
Hardware (bei Treibern) nicht erkennbar sein um so billigen 
China-Plagiaten vorzubeugen?
Kann es auch sein, dass der Programmierer glaubt, er müsse es nicht 
dokumentieren, da es ja so selbsterklärend und logisch aussieht?

Autor: Gast (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Wie kommst du darauf, das der Linux-Kernel nicht kommentiert ist?

Autor: Karl-heinz Strunk (cletus)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Stefan Helmert wrote:
> Am schlimmsten sieht das im Bereich Linux-Kernel aus. Viele
> quelloffene Komponenten sind überhaupt nicht dokumentiert

Schon mal dran gedacht, dass der Kernel seine Doku selber enthält?
Das ist aber nur die Doku, falls du tief einsteigen willst.

Informationen zu Boot-Parameter und Co findest du zur Genüge im 
doc-Verzeichnis.


Wenn du natürlich HTML (oder ein Format deine Wahl) erwartest, hast du 
Pech gehabt.


Achja: Und es wird dir keiner (außer gegen Bezahlung) ein Handbuch nach 
Hause schicken.

Aber was erwartest du?

Autor: Timo (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Sag mal, bist du nicht dazu in der Lage, dir mal über ein Thema 
eigenständig Gedanken zu machen? Möchtest du stets und ständig alles 
vorgekaut haben?

Autor: Karl-heinz Strunk (cletus)
Datum:

Bewertung
0 lesenswert
nicht lesenswert

Autor: Karl-heinz Strunk (cletus)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Timo wrote:
> Sag mal, bist du nicht dazu in der Lage, dir mal über ein Thema
> eigenständig Gedanken zu machen? Möchtest du stets und ständig alles
> vorgekaut haben?

Das stimmt, manchmal will man einfach was vorgekaut bekommen.

Z.B. wenn man nach Boot-Parametern des Sata-Moduls sucht, will ich nicht 
erraten müssen, was der Programmierer als Parameter genommen haben 
könnte.

Aber auch das steht alles im Kernel-Doc drinne.

Autor: Klaus (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Mag sein, dass der Linuxkernel nen schlechtes Beispiel war. Aber im 
wesentlichen hat der OP Recht, finde ich. Viele Bibliotheken sind 
grauenhaft schlecht dokumentiert.  Und das "Der Quellcode selber is die 
besste Dokumentation" is 1) Arrogant, 2) nicht Sinn einer Dokumentation 
sich erst Studenlang durch den Code wühlen zu müssen und 3) meinsten 
eine Ausrede für die Faulheit/Unmotiviertheit des Progammierers ne 
Dokumentation zu schreiben.

Autor: Uhu Uhuhu (uhu)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Guck dir mal die Doku für USBprog an...

Autor: Karl-heinz Strunk (cletus)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Klaus wrote:
> Viele Bibliotheken sind
> grauenhaft schlecht dokumentiert.

Ja, stimmt. Und?
Das aber an quelloffen oder nicht festzumachen, finde ich kurzsichtig.

> Und das "Der Quellcode selber is die
> besste Dokumentation" is 1) Arrogant, 2) nicht Sinn einer Dokumentation
> sich erst Studenlang durch den Code wühlen zu müssen und 3) meinsten
> eine Ausrede für die Faulheit/Unmotiviertheit des Progammierers ne
> Dokumentation zu schreiben.

man Doxygen

Damit kann man meines erachtens sehr gut dokumentieren.

Die Frage ist, worüber wir reden:

Reden wir hier über die Dokumentation z.B. einer API oder um ein 
Benutzerhandbuch eines Programms?

Wenn ich eine Klasse dokumentiere, auf die andere Programmierer 
zugreifen wollen, erwarte ich von denen, dass die in der Lage sind, mit 
Doxygen dokumentierten Code zu lesen bzw mit der Doxygenausgabe etwas 
anzufangen.

Autor: Karl-heinz Strunk (cletus)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Uhu Uhuhu wrote:
> Guck dir mal die Doku für USBprog an...

Soll das ein Positiv- oder ein Negativbeispiel sein?

Nachteil finde ich bei der Doku, dass Benedikt da zigtausend Unterseiten 
auf embedded-projects hat, die allesamt nicht wirklich miteinander 
verbunden sind...

Ich suche mich auf der Seite regelmäßig zu Tode, z.B. wenn ich nur die 
Belegung rausfinden will.

Autor: Uhu Uhuhu (uhu)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Karl-heinz Strunk wrote:

> Ich suche mich auf der Seite regelmäßig zu Tode, z.B. wenn ich nur die
> Belegung rausfinden will.

Du auch?

Autor: Läubi .. (laeubi) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Das Hauptproblem ist einfach das gutes Dokumentieren nicht gewürdigt 
wird. Schreibt man ne Doku sieht eh niemand rein, und in dem Falle das 
es doch mal jemand tut steht das was derjenige Wissen will garantiert 
nicht so drin wie gebraucht ;)

Autor: A. F. (artur-f) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Ich musste auch schon mehrmals über die Doku mancher IC's kotzen. Ab und 
zu hat man das Gefühl, die Anleitungen werden von Studenten des Lehramts 
geschrieben, die Sport und bildende Kunst studieren :/

Man wird bei einem 300 Seiten langen Programmer-Manual hin und her durch 
die Register geschickt und muss bei einem Satz 3 weitere Seiten 
gleichzeitig im Auge behalten. Dazu wird man mit Abkürzungen zugebombt 
und den ganzen "wenn und aber"'s. Während der Programmierung stellt man 
dann fest, dass manche Sachen unvollständig oder gar nicht beschrieben 
wurden. Solche Datenblätter machen echt Spass ;) Aber Monopolisten wie N 
I  können sich sowas ja erlauben ^^

Autor: Thilo M. (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Bei uns (Reparaturabteilung) gilt die Devise:
'keine Doku - keine Reparatur'.

Alles Andere ist Bastelei oder Pfusch.

Autor: Erstaunter (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
"Bei uns (Reparaturabteilung) gilt die Devise:
'keine Doku - keine Reparatur'.

Alles Andere ist Bastelei oder Pfusch."



Dann seit ihr im falschen Gewerbe tätig.

Ohne Schaltplan reparieren zu können ist kein Pfusch.
Nur mit Schaltplan reparieren zu können ist Bastelei.

Autor: Thilo M. (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Erstaunter wrote:
> "Bei uns (Reparaturabteilung) gilt die Devise:
> 'keine Doku - keine Reparatur'.
>
> Alles Andere ist Bastelei oder Pfusch."
>
>
>
> Dann seit ihr im falschen Gewerbe tätig.
>
> Ohne Schaltplan reparieren zu können ist kein Pfusch.
> Nur mit Schaltplan reparieren zu können ist Bastelei.

Naja, sportlich und im privaten Bereich sehe ich das auch so.
Nur, wie sieht das mit Nachweisen im kerntechnischen Bereich aus?

Wenn ich nicht jeden kleinen Handgriff ordnungsgemäß nachweisen kann, 
wird mir (uns) seitens des Umweltministeriums der Ar... aufgerissen.

Darum die Devise! ;)

Autor: Erstaunter (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Dann laß den Satz mit Bastelei und Pfusch weg.

Es gibt noch genügend Geräte zu reparieren, die keinen eigenen 
Kernreaktor zur Stromversorgung benötigen.  :-)

Autor: Thilo M. (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
>Es gibt noch genügend Geräte zu reparieren, die keinen eigenen
>Kernreaktor zur Stromversorgung benötigen.  :-)

Für uns leider nicht. :)

Autor: Karl-heinz Strunk (cletus)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Thilo M. wrote:

> Naja, sportlich und im privaten Bereich sehe ich das auch so.
> Nur, wie sieht das mit Nachweisen im kerntechnischen Bereich aus?

Und der Preis für das am meisten aus der Luft gegriffene geht an ...
...*TUSCH* ...

Thilo!

SCNR , nimms mir nicht übel ;-)


Ich kann mich an eine Zeit erinnern, in der in den Fernsehchassis die 
Schaltpläne von innen befestigt wurden....Bei jedem....

Autor: Erstaunter (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Strahlende Gesichter in der ganzen Abteilung - da gibt es Firmen, wo der 
Chef misstrauisch werden würde. :)

Autor: Thilo M. (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
>SCNR , nimms mir nicht übel ;-)

Tu' ich nicht.

Wenn du's mit 20++ Jahren alten Baugruppen zu tun kriegst, bist du froh, 
überhaupt was zu kriegen.
Und dann noch eine qualifizierte Reparatur nachzuweisen ist oft nicht 
einfach.
Versuche mal z.B. einen CMOS-IC, z.B. 4011 im Keramikgehäuse zu kriegen, 
möglichst vom gleichen Hersteller wie das Original.

Die Doku für das alte Zeugs zu beschaffen und erhalten setzt eine 
bundesweite Kooperation der Reparaturwerkstätten in unserem Bereich 
voraus, was auch prima funktioniert.

Autor: Karl-heinz Strunk (cletus)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
;-)


Ich habe ein HP TC1100 (ist ein Business Tablet)

Ich habe gegoogled: Weils außerhalb des Supports ist, hat HP die 
Servicemanuals komplett freigegeben.

Vorbildlich und supergeil!

Autor: Erstaunter (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Es sollte zur Pflicht für die Hersteller gemacht werden, 
Schaltungsunterlagen für Geräte, die jeder kaufen kann, zum Download zur 
Verfügung zu stellen (einige Hersteller machen das, auch für aktuelle 
Geräte). Wenn man ein Gerät dadurch länger erhalten kann, empfiehlt man 
sie gern auch anderen. Ist also ein positiver Effekt für den Hersteller.

Bitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail, Yahoo oder Facebook? Keine Anmeldung erforderlich!
Mit Google-Account einloggen | Mit Facebook-Account einloggen
Noch kein Account? Hier anmelden.