LINKs in Dokumentationen

[Siro]

Hallo,
heut mal etwas ganz spezielles:

Auf der Suche nach einem (mehreren) LINKs

Im Jahr 2016 habe ich mich SEHR intensiv mit dem NXP Controller LPC1347 und seinem eingebauten EEPROM beschäftigt.
Der Zugriff auf das interne EEPROM erfolgt normalerweise mittels spezieller Treibersopftware die im Chip selbst verankert ist.
Dieser ROM Code ist aber nicht sonderlich gut programmiert. Es müssen zudem Interrupts gesperrt werden.
Für mein Medizinprodukt war dies aber nicht akzeptabel.
NXP hat aufgrund der Interrupt Problematik eine spezielle Library für die Chips der LPC11er und LPC13er Reihe zur Verfügung gestellt.
Mit dieser LIB konnte man nun ohne Sperren von Interrupts auf das EEPROM zugreifen.

Lange Rede, kurzer Sinn:
In meiner Softwaredokumentation verweise ich auf die Datei
libeeprom-v3.zip
zu finden hier:
https://www.lpcware.com/content/blog/lpc1100lpc1300-eeprom-library

und geanu da liegt das Problem:
Dieser und etliche andere LINKS aus meiner Doku sind nun alle nicht mehr gültig.

Ich habe die Datei natürlich als Sicherheitskopie auf meinem Rechner und Backup
aber irgendwie stelle ich fest, dass es keinen Sinn mehr macht in Dokumentationen LINKs zu setzen

Deshalb mal die Frage in die Runde
Setzt ihr auch LINKs in eure Dokumentation ?
Die haben ja dann leider eine unbekannt, begrenzte Gültigkeit.

Zudem, wenn jemand eine Link hat, wo ich meine Datei libeeprom-v3.zip wieder finden könnte wäre ich sehr dankbar.
Bei NXP hab ich das schon ins Forum gestellt. Vielleicht kommt da ja noch was.

Siro

[Moppi]

Hallo Siro,

dokumentieren!

Die ursprünglichen Links drin stehen lassen. Da die Dateien mal von dort geladen wurden.
Ich würde die aber im Anhang rein packen. Weiß ja nicht, wo Deine stehen. Vermutlich irgendwo bei Quellenangaben.
Die nicht mehr Funktionierenden aber kennzeichnen. Falls es neue funkt. Links gibt, die alten Links damit ersetzen, logisch irgendwie und weiß auch keiner weiter, dass Du das gemacht hast.
Wenn es die Quellen später nicht mehr gibt, kann man das nun schlecht ändern. Trotzdem waren es Deine Quellen.
Willst Du einen Projektverlauf dokumentieren, würde ich das so machen.
In einer Projektdoku, wo es auch um den Verlauf des Projektes geht, kann man es sowieso nie allen richtig genug machen. Der eine sagt: braucht keine toten Links, der andere meint dann: doch, ich möchte schon wissen woher das und das kam ...


Ist es eine Doku, wo man was nachmachen soll, also mehr ein Handbuch, müssten die Links funktionieren oder auf andere Weise die Dateien bereitgestellt werden.
Bei Veröffentlichung Links/Quellen mitzugeben, die nun keine mehr sind, ist hier eine schlechte Idee.

Man kann auch den Urheber dieser Dateien fragen, ob Du die zum Zwecke der Dokumentation weitergeben darfst. Damit man später beispielsweise irgendwas wiederherstellen kann.
Wäre dann wie eine Sicherheitskopie, würde ich meinen. Könntest dann die Dateien selber auf einem Server zur Verfügung stellen. Besser mit Genehmigung. Gemehmigung in der Doku erwähnen / aufführen.






MfG

[Siro]

Moin Moppi,
ersteinmal vielen Dank für deine Ausführungen.

Nach IEC62304 muss ich ja "ALLES" dokumentieren.

Ich muss ja auch die Dokumente selbst mit Revisonen archivieren,
somit erstelle ich dann also ein neues Dokument und werde, sofern möglich, die neuen LINKs dort eintragen.
Tausend Punkte (Riesen Papierkrieg) was das Produkt jedoch nicht besser macht...;)

Ich hab die LINKs eigentlich immer direkt in den Dokutext reingeschrieben, daher wimmelt es natürlich
mal hier und da von den Dingern.

Beispiele:
------------------------------
Für das Verständnis der Software ist eine Einarbeitung in die Architektur des ARM CORTEX M3
und den integrierten Peripheriebausteinen des LPC1768 unausweichlich.
Dazu verweise ich auf die Datenblätter des Hersteller NXP.
In erster Linie auf das LPC17xx User Maunal UM10360.pdf

http://www.nxp.com/products/microcontrollers/
geht nicht mehr.....
------------------------------------
Risikobewertung CPU
Auch für den eigentlichen Kern des Prozessors „Cortex M3“ gibt es Errata-Sheets, welche auf Problematiken hinweisen.
http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.eat0420d/index.html
geht nicht mehr....
-----------------------------------------
Das Flashmagic Tool ist eine kostenfreie Software für den PC, speziell zum Programmieren der NXP Microcontroller.
Version Version 7.40 ist zur Zeit aktuell (Stand 04.04.2013)
http://www.flashmagictool.com/
hier geht es sogar noch
-------------------------------------

Naja und so zieht sich das natürlich durch eine Vielzahl von Dokumenten.

Ich habe auch in der Verfahrensanweisung drauf aufmerksam gemacht, dass bestimmte Dokumente
regelmäßig vom Hersteller downgeloaded werden müssen und neu erkannte Fehler entsprechend bewertet werden müssen.
Die VA wurde aber ursprünglich von einer externen Firma erstellt, wobei ich mit den Vorgaben nicht immer übereinstimme...
Das betrifft hier hauptsächlich die Errata Scheets der Controller.
Oft werden ja Fehler erst Jahre später in einem Chip (Controller) erkannt, dann muss natürlich sichergestellt werden,
dass die ausgelieferten Geräte keinen Schaden durch den zuvor nicht erkannten Fehler anrichten können.

So kommt es dann dazu, dass die originalen LINKs im Dokument halt nicht mehr funktionieren/existieren.

aber jetzt ist erstmal Wochenende und ein "schönes" WE wünsche ich euch allen.

Siro

[HaWe]

hallo,
ich bin kein Jurist, aber vermutlich wirst du im Rahmen der Dokumentationspflicht sicherstellen müssen, dass deine Referenzen verfügbar sind.
Nachdem du aber nicht die Quelle zur dauerhaften Verfügbarkeit verpflichten kannst, kannst du IMO zwar weiterhin per Weblink darauf verweisen, musst aber dann für den Fall der nachträglichen Nichtverfügbarkeit eine eigene Kopie als Download oder Ausdruck zurückhalten, auf die du dann auf Verlangen zurückgreifen und dann weitergeben kannst.

[Thomas$]

als zwischenschritt würde ich mal auf die Wayback Machine verweisen
https://web.archive.org/
z.B.
https://web.archive.org/web/20131016034605/https://www.lpcware.com/content/blog/lpc1100lpc1300-eeprom-library

[HaWe]

als zwischenschritt würde ich mal auf die Wayback Machine verweisen
https://web.archive.org/
z.B.
https://web.archive.org/web/20131016034605/https://www.lpcware.com/content/blog/lpc1100lpc1300-eeprom-library
wie kommt man nun mit der Wayback machine auf LPC17xx User Manual UM10360.pdf von
http://www.nxp.com/products/microcontrollers/
:?:

[Siro]

Hallo HaWe,
da muss ich Dir wohl voll zustimmen.

Alle Dokumente bzw. die Quellen worauf ich verweise muss ich wohl oder Übel zum Projekt mit archivieren.
Der Aufwand wird immer aufwändiger...

Ich komme schon lange nicht mehr dazu meine Software zu pflegen, denn ich bin nur noch mit Papierkrieg beschäftigt.
Leider fehlt mir dadurch die Zeit meine Software auf Herz und Nieren zu testen.
Damit macht der Papierkrieg das Gerät eigentlich schlechter, so würde ich das mal ausdrücken wollen.
Aber wir leben nunmal in der Zeit der Bürokratie.

Ich finde die Entwicklung leider grausam.
Das liegt wohl nicht zuletzt an unserer "kleinen" Firma.
Früher hat man die Konkurenz aufgekauft, heute wird man kaputt zertifiziert.
Kleine Unternehmen können das garnicht mehr stemmen und das ist meiner Meinung nach auch gewollt.

Aber mit den LINKs werde ich ab jetzt dann anders handhaben.
Einen Verweis auf einen Anhang xxx und dort sind dann alle LINKs aufgeführt.
Das macht es glaube ich etwas übersichtlicher/einfacher.
Zumal brauch ich dann nicht überall im Dokument Änderungne vornehmen.

Siro

@Thomas$:

WOOOW, ich bin begeistert. Einen "RIESEN" Dank erstmal an Dich, da iist die Seite wieder,

Leider kann ich aber die LIB nicht laden, weil der Link auf der Seite auch nicht geht. Schade...

[HaWe]

Kleine Unternehmen können das garnicht mehr stemmen und das ist meiner Meinung nach auch gewollt.
ich würde nicht so weit gehen, zu behaupten, dass es "gewollt" sei -
ich denke, man nimmt einfach keine Rücksicht auf Kleinstbetriebe, um das "hohe Niveau" z.B. von ISO-Standards allgemeinverpflichtend europaweit durchzusetzen.

[Moppi]

@Siro


Dann kannst Du die Fremdsoftware / PDFs auf CD brennen oder andres Medium. Wenn es so eine Doku ist, wo Du was als Nachweis brauchst. Meine Meinung.
Müsste man dann so machen, dass man das einwandfrei benennt, so dass es id....sicher wiederzufinden ist. Gehört dann nat. direkt zur Doku und wäre am besten gemeinsam aufzubewaren.
Ich habe bei Softwareprojekten früher sowas auf Diskette gespeichert, doppelte Kopie, dann zum Quelltext, der alle Ausführungen enthält, in den Ordner. Da gabs so Klarsichteinlagen für Ordner
für 5.25 Zoll Disketten und für kleinere. Allerdings kenne ich die Anforderungen an Dich nicht genau, muss nat. den Vorschriften entsprechen.

Sehe gerade ... habt ihr schon drüber gesprochen :)



MfG

[Holomino]

Ich hab das in meiner aktiven Zeit als Dokumentöse versucht, zu vermeiden.
So sehr es verlockt, externe Referenzen (die es teilweise sogar besser erklären, als man es selber vermag) hinzuzuziehen, es senkt die Verwendungsfähigkeit einer Doku, weil das Gehopse im Text den Lesefaden unterbricht. Sprich: gut für den Schreiber, schlecht für den Leser.

In den Prerequisites oder bei den Quellangaben ist es durchaus erlaubt. So eine Liste kann man automatisiert erstellen, einbinden und auch prüfen, aber im Text, wie gesagt, ist's der Gau.

[Siro]

Hallo Holomino,
ja, es ist ein Gau, das habe ich aber erst zu spät bemerkt.
Die Pflege der LINKs "innerhalb, verteilt im Dokument" macht wirklich später sehr viel Arbeit.

Siro