Über example.com und das Schreiben von technischer Dokumentation

unter Online ▸ Stichwort Community / Best Practices / Unixeschreibt
Über example.com und das Schreiben von technischer Dokumentation

Diesen Beitrag schrieb ich 1 Jahr und 1 Monat zuvor; die nachfolgenden Ausführungen müssen heute weder genau so nach wie vor funktionieren, noch meiner heutigen Meinung entsprechen. Behalte das beim Lesen (und vor allem: beim Nachmachen!) bitte stets im Hinterkopf.

Definierte Platzhalter zur Verwendung in technischen Dokumentationen

Geschätzte Lesezeit: 5 Minuten

Ihr habt das vielleicht noch gar nicht so mitbekommen, aber: ich schreibe tatsächlich einiges an technischer Dokumentation 😇

Das mache ich nun schon seit vielen Jahren, hier im Blog, bei meinem jeweiligen Arbeitgeber, für meine eigenen Belange. Ich lese natürlich auch sehr häufig technische Dokumentation, und was mir dabei immer wieder auffällt: viele Menschen, die sowas schreiben, scheinen nicht zu wissen, dass es genau hierfür reservierte $DINGE gibt – die öffentlich nicht genutzt werden dürfen, deren Bedeutung einheitlich festgelegt ist, die nirgendwo versehentlich Schäden anrichten können (sollten!).

Für deren Nutzung fallen mir spontan mehrere gute Gründe ein, ergänzt die Liste gerne um eigene Punkte:

  • ich möchte meine Leserschaft vor allzu wilden Copy-Paste-Havarien bewahren
  • ich möchte mit meiner Dokumentation nicht versehentlich sensible Daten herausgeben
  • ich möchte unbedingt vermeiden, dass Kommandos oder Skripte gegen „echte“ Systeme gefahren werden
  • ich möchte meine Dokumentation möglichst generisch halten und arbeite deshalb mit Platzhaltern
  • ich möchte Logs anonymisieren
  • …

Requests for Comments stellen Leitplanken für unser digitales Dasein auf. Und was vielleicht gar nicht so bekannt ist – und mir ging es da lange Zeit nicht anders – ist, dass sie auch welche für technische Dokumentation vorgeben. Und weil ich das für total sinnvoll erachte, möchte ich euch nachfolgend die gängigsten vorstellen.

Top Level Domain Names

RFC2606 definiert mehrere Top-Level-Domains, die ausschließlich für Teststellungen und Dokumentationszwecke genutzt werden dürfen. Dabei handelt es sich um

  • .example für Dokumentationen,
  • .test für Tests im DNS-Bereich,
  • .invalid für Dinge, die auf den ersten Blick als ungültig erkennbar sein sollen und
  • .localhost, das in Host-DNS-Implementierungen einen A-Record auf Loopback darstellt

RFC6762, RFC7686, RFC9476 und ICANN definieren weitere – die würden uns hier aber zu weit vom Kernthema „Dokumentation“ wegführen.

Second Level Domain Names

Ebenfalls RFC2606 und auch RFC6761 geben uns drei Second-Level-Domains an die Hand, mit denen wir in unseren Dokumentationen arbeiten dürfen:

  • example.com
  • example.net
  • example.org

Darüber hinaus gibt es außerdem example.edu, die ebenfalls für diese Zwecke gedacht ist, ebenfalls auf die IANA verweist, allerdings in keinem der von mir durch-grep-ten RFCs Erwähnung findet.

Ich kann euch nur bitten: nutzt die. Macht es einfach. Das ist so viel besser als diese ausgedachten trulliwulli.xyz-Domains, die einen bestenfalls „nur“ beim Lesen stolpern lassen. Außerdem spart es euch das Ändern der Dokumentation, falls sich mal eine Domain ändert.

IP-Adressen

IPv6

RFC3849 gibt uns schon seit vielen Jahren den IPv6-Adressbereich 2001:db8::/32 für Dokumentationszwecke vor.

  • → von 2001:db8:: bis 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff

Im Jahr 2024 hat die IANA einen weiteren Bereich für diesen Zweck definiert. Dieser ist in RFC9637 als 3fff::/20 festgelegt.

  • → von 3fff:: bis 3fff:fff:ffff:ffff:ffff:ffff:ffff:ffff

IPv6 Multicast

RFC6676 definiert „IPv6 Multicast Documentation Addresses“:

  • IPv6 Any-Source Multicast (ASM): FF0X::DB8:0:0/96
  • IPv6 Source-Specific Multicast (SSM): die für Dokumentation verwendeten Quelladressen sollen in diesem Fall Unicast-Adressen sein. Wir erinnern uns: IPv6-Unicast-Präfix ist 2001:db8::/32 gemäß RFC3849 👆

IPv4

Kommen wir zu den IPv4-Netzen: obwohl eigentlich längst überholt, brauchen wir diese ja nach wie vor immer mal wieder. In diesem Sinne gibt uns RFC5737 drei „Test-Netze“ zur Verwendung in unseren „Tech Docs“ an die Hand:

  • TEST-NET-1 - 192.0.2.0/24 (192.0.2.0–192.0.2.255)
  • TEST-NET-2 - 198.51.100.0/24 (198.51.100.0–198.51.100.255)
  • TEST-NET-3 - 203.0.113.0/24 (203.0.113.0–203.0.113.255)

128.66.0.0/16 hingegen findet weder hier noch in RFC3330 Erwähnung und gehört somit nicht zu den definierten Test-Netzen. Auch wenn der Block in der Vergangenheit für Beispiele genutzt wurde, ist er nicht speziell dafür deklariert und kann, im Gegensatz zu den oben genannten, durchaus regulär genutzt werden – was eben doch zu Kollisionen führen könnte und deshalb nicht zu empfehlen ist. Sollte sich Dokumentation darauf beziehen, ist es empfehlenswert, diese entsprechend zu überarbeiten.

IPv4 Multicast

RFC6676 liefert uns Multicast-Adressen für Dokumentationszwecke:

  • IPv4 Any-Source Multicast (ASM): MCAST-TEST-NET – 233.252.0.0/24 (233.252.0.0 - 233.252.0.255, die Benamung ist RFC5771) entnommen
  • IPv4 Source-Specific Multicast (SSM): die für Dokumentation verwendeten Quelladressen sollen in diesem Fall Unicast-Adressen aus einem der in RFC5737 definierten Testnetze sein
  • Gemäß RFC6034:
    • TEST-NET-1 - 234.192.0.2
    • TEST-NET-2 - 234.198.51.100
    • TEST-NET-3 – 234.203.0.113

Ethernet MAC-Adressen

Auch für MAC-Adressen gibt es einen definierten Bereich, der Dokumentationszwecken vorbehalten ist. RFC7042 regelt das – und legt dabei für EUI-48 folgendes fest:

  • Unicast EUI-48 – 00-00-5E-00-53-00 bis 00-00-5E-00-53-FF
  • Multicast EUI-48 – 01-00-5E-90-10-00 bis 01-00-5E-90-10-FF

64-bit Extended Unique Identifier (EUI-64) sind vor allem im Zusammenhang mit beispielsweise Firewire, InfiniBand, stateless IPv6 oder Zigbee ein Ding, haben in meiner täglichen Arbeit aber (bislang zumindest) keine Relevanz. Da dieser Abschnitt recht umfangreich ist, verweise ich interessierte Menschen an dieser Stelle lediglich auf RFC7042.

Autonomous System Numbers

Da jedem autonomen System eine eindeutige Nummer (Autonomous System Number, kurz ASN) zugewiesen wird, ist es auch hier wichtig, zufällige Kollisionen mit bereits existierenden Nummern zu vermeiden. Deshalb hat die IANA zwei Blöcke aufeinanderfolgender Nummern für Dokumentationszwecke reserviert, welche wir in RFC5398 nachlesen können – vielen Dank an jo für diese wichtige Ergänzung.

  • 16bit: 64496 - 64511
  • 32bit: 65536 - 65551

Media Types

Ist es im Rahmen von Dokumentation nicht relevant, um welche konkreten Medientypen es gerade geht, lässt sich auch an dieser Stelle mit Platzhaltern arbeiten: RFC4735 legt in diesem Sinne folgende fest:

  • Media Type: example
  • Media Subtypes:
    • application/example
    • audio/example
    • image/example
    • message/example
    • model/example
    • multipart/example
    • text/example
    • video/example

Passwörter in Dokumentationen

Häufig beinhaltet solcherart technische Dokumentation ja auch, dass Passwörter eingegeben oder in Konfigfiles hinterlegt werden müssen. Und ich habe tatsächlich kein RFC entdeckt, das einheitlich regeln würde, wie man damit idealerweise umgehen sollte. Deshalb ist dieser Abschnitt eher ein wohlmeinender Hinweis, ein Erfahrungswert von meiner Seite:

Die „stackoverflow“-Mentalität ist real, und mit zunehmendem KI-Einsatz wird sich daran ganz sicher nichts zum Positiven hin ändern. Will sagen: die Leserschaft kopiert, und dann fügt sie ein. Ihr müsst zu jeder Zeit davon ausgehen, dass die Aufrufe und Konfigschnipsel, die ihr dokumentiert, 1:1 so übernommen werden. Daher ist meine Empfehlung, für Passwörter immer etwas (zum Beispiel mit pwgen) Generiertes zu nehmen (und nicht changeMe, nicht meinSupergeheimesPasswort oder ähnliches) – sozusagen also mit gutem Beispiel vorauszugehen.

Telefonnummern

trusty falxter warf eine wertvolle, wenn auch für Deutschland spezifische Ergänzung zum Thema in den Ring: die Bundesnetzagentur stellt für Filme, Bücher und andere Medien sogenannte „Drama Numbers“ zur Verfügung – und eben auch für „Lehrmaterialien“, wozu ich unsere technische Dokumentation doch eindeutig zähle. Also Rufnummern, denen dauerhaft keine Teilnehmer zugeteilt sind, die beliebig angerufen und genehmigungsfrei „in Medien gezeigt, abgedruckt und gesprochen verwendet werden können“.

Dabei handelt es sich aktuell (Mitteilung 148/2021) um jeweils 1000 Rufnummern aus fünf Ortsnetzbereichen (Berlin, Frankfurt am Main, Hamburg, Köln und München) sowie um mehrere Rufnummern aus den Netzen der Mobilfunkbetreiber. Greift euch bei Bedarf (muss hier jemand Telefonanlagen dokumentieren?) am besten das PDF mit den Einzelheiten.

Abschließend

Damit sollten viele in unserem Job alltägliche Anforderungen hinreichend abgedeckt sein. Randfälle gibt es natürlich immer und wird es immer geben. Aber an das, was einheitlich geregelt ist, sollten wir uns alle halten – denn am Ende macht’s das für uns alle einfacher 🙂

Hintergrundbild © Marianne Spiller · Alle Rechte vorbehalten
Habe ich etwas missverständlich formuliert, ganz ausgelassen oder mich vertippt?
Möchtest du hilfreiche Inhalte beisteuern?
Artikel in diesem Bereich kannst du überarbeiten und ergänzen!
→ Hier geht es zum öffentlichen Repository... ←

5 Kommentare

Hinterlasse einen Kommentar

Ich freue mich über jeden Kommentar, es sei denn, er ist blöd.
Deshalb sind die Kommentare auf dieser Seite auch generell moderiert.

(Nick)Name: (erforderlich)
E-Mail: (erforderlich, wird nicht veröffentlicht)
Website: (optional)

Reaktionen aus dem Fediverse

Sofern du selbst einen ActivityPub-Account (wie beispielsweise Mastodon) nutzt, erscheinen auch deine Antworten auf mein Artikel-Announcement automatisch hier.