Ich habe ein proprietäres Dateiformat analysiert und würde gerne meine Erkenntnisse dokumentieren. Ich denke ich habe das Dateiformat vollständig verstanden, zumindest lassen sich selbst generierte Daten problemlos einlesen. Ich habe jetzt mal gegoogelt, aber nicht wirklich was gefunden. Kennt ihr vielleicht ein paar öffentlich einsehbare Dokumentationen an denen ich mich orientieren könnte, so das auch andere Leute in der Lage wären kompatible Daten zu erzeugen?
Nimm das, was Du kennst. ASCII, Word, LaTeX, man Pages, Wiki... Die Info ist 1000x mehr wert als keine Info weil es nicht schön genug aussieht. Oder geht es darum, wie man was sinnvoll daratellt? Dann müsstest Du das "was" näher beschreiben.
Ich würde die Datei zuerst als Struktur darstellen und danach die einzelnen Elemente textuell beschreiben. Bsp.: fileformat { bla bla, bla xyz } bla: ist irgend etwas. xyz: noch etwas..
Oleksandr schrieb: > Kennt ihr vielleicht ein paar öffentlich einsehbare Dokumentationen https://github.com/pmachapman/helpdeco/blob/master/helpfile.txt
Oleksandr schrieb: > Ich habe jetzt mal gegoogelt, aber nicht wirklich was gefunden. Kennt > ihr vielleicht ein paar öffentlich einsehbare Dokumentationen an denen > ich mich orientieren könnte, so das auch andere Leute in der Lage wären > kompatible Daten zu erzeugen? Was EBNF-artiges + natürlichsprachliche Beschreibung der einzelnen Punkte finde ich am lesbarsten, das wird auch meistens in Datenblättern,... verwendet. Dann aber nicht nur ne halbgare Besschreibung sondern einmal die komplette Gramatik und dann jeweils die einzelnen Punkte nochmal einzeln mit Beschreibung. Nix nervt mehr wenn das unvollständig ist. Wenn du ganz fleissig sein willst, lieferst du eine Definition als XML-Schema (DTD reicht oft nicht aus) oder ähnlichem mit, aus dem man sich einen Parser generieren kann. kaitiai.io ist dafür auch ganz nett.
Kommt halt auf das Dateiformat an. Wenn das eine relativ straff organisierte Binärstruktur ist, kann schon Pseudocode mit einer C-Struktur-Beschreibung als Dokumentation hilfreich sein (natürlich mit Hinweisen auf Byteorder). Wenn es etwas wie ASN.1 ist, dann wird das ganze natürlich etwas komplizierter.
Oleksandr schrieb: > Ich habe ein proprietäres Dateiformat analysiert und würde gerne meine > Erkenntnisse dokumentieren. > Kennt ihr vielleicht ein paar öffentlich einsehbare Dokumentationen an denen > ich mich orientieren könnte, so das auch andere Leute in der Lage wären > kompatible Daten zu erzeugen? erst mal grundsätzlich: Für welche Leute soll die Doku denn sein? Wenn es für nur für die Kollegen in der Firma sein soll, frage die einfach, wie sie es gerne hätten. Wenn Du das Format für alle Welt dokumentieren willst, dann frage doch mal hier an: https://www.documentliberation.org/ Die können Dir vermutlich Mustervorlagen zeigen oder Dich weitervermitteln. Geht ja auch darum, wo die Doku hinterlegt wird. Und noch viel wichtiger: bei manchen proprietären Dateiformaten sehen die Hersteller es gar nicht gern, wenn "andere Leute in der Lage wären kompatible Daten zu erzeugen". Falls es mit diesem Dateiformat schon Ärger deswegen gab, wissen die liberation-Leute möglicherweise davon.
Ignoriere alles was Schleimfasten vorgeschlagen hat. EBNF, ABNF und co. sind nur für textformate einigermassen brauchbar. XML Schemas und DTDs sind auch nur nützlich um XML oder SGML zu beschreiben, aber nicht für Daten die nicht bereits strukturiert sind. Ich würde mal diverse RFCs anschauen. TCP, TLS, etc. Textformate wie z.B. text, markdown, latex, rst, sind immer schön, html ist auch ok. Versuche einfach genau und verständlich zu sein, und teile es Sinnvoll auf damit man schnell findet, was man sucht. Keiner liest sich die Dokumente von oben nach unten durch.
Ich würde es auch mit LaTex machen. Codelistings, auf die man genauso wie Bilder oder Tabellen verweisen kann, UML und dergleichen sind kein Problem. Es gibt Werkzeuge, die genau dafür gemacht sind. Word ginge auch, aber Code damit vernünftig zu formatieren wird nervig. Ansonsten ist das Wichtigste die PDF, die am Ende beim Dokuleser landet. Womit du sie gemacht hast, ist zweitrangig.
Such mal nach dem Buch "Dateiformate-Referenz" von Günter Born. Das müßte im Netz auch sehr schnell in einer PDF-Version zu finden sein. Da sind verschiedene Dateiformate sehr gut beschrieben. Taugt auf jeden Fall als Anregung, wie man Daten-Strukturen gut beschreibt.
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? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.