Datenformat dokumentieren

[Oleksandr (Gast)]

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?

[A. S. (Gast)]

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.

[Peter M. (Gast)]

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..

[Michael B. (laberkopp)]

Oleksandr schrieb:
> Kennt ihr vielleicht ein paar öffentlich einsehbare Dokumentationen

https://github.com/pmachapman/helpdeco/blob/master/helpfile.txt

[Schleimfasten (Gast)]

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.

[DerEinzigeBernd (Gast)]

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.

[keinLichtAufGing (Gast)]

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.

[DPA (Gast)]

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.

[Wühlhase (Gast)]

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.

[Hans im Glück (Gast)]

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.