Was sind Standardtechniken, die dem Leser der Dokumentation anzeigen, dass er seinen eigenen geeigneten Text (z. B. Benutzername, Domäne) ersetzen soll?

Meiner Erfahrung nach macht diese Kombination von Punkten den Job gut:

• Geben Sie am Anfang Ihres Handbuchs eine Anweisung, wie Sie auf Befehle, benutzerdefinierten Text/Optionen usw. verweisen. Kursivschrift ist hierfür üblich. Zum Beispiel: Text gibt Text an, den Sie angeben müssen und der eigentliche Daten wie Ihre E-Mail-Adresse, Ihren Benutzernamen, Ihr Passwort usw. darstellen sollte.
• Verwenden Sie konsistente Formatierungsoptionen, Großschreibung und Syntax in Ihren Dokumenten.
• Verwenden Sie ein gängiges Sonderzeichen, um Benutzereingaben einzuschließen, z. B. die bereits vorgeschlagenen Klammern %, <> oder [] (obwohl ich diese als optionale Eingaben gesehen habe). Machen Sie explizit deutlich, ob die Sonderzeichen in die Eingabe einbezogen werden sollen oder nicht.
• Verwenden Sie eine konsistente Methode, um auf allgemeine Benutzereingaben (Platzhalter) wie „mein-Benutzername“, „mein-Kennwort“, „meine-e-Mail@domain.com“ oder „“ zu verweisen. Stellen Sie sicher, dass diese mit Beispielen am Anfang Ihres Leitfadens definiert sind.

Hier ist auch, was das Microsoft Manual of Style zum Thema Formatierung für Benutzereingaben sagt:

Benutzereingabe Üblicherweise Kleinbuchstaben, es sei denn, es wird zwischen Groß- und Kleinschreibung unterschieden. Je nach Element fett oder kursiv. Wenn die Benutzereingabezeichenfolge Platzhaltertext enthält, verwenden Sie Kursivschrift für diesen Text.

Eine Überlegung zur Barrierefreiheit :

Einfache Formatierung oder Farbe reicht für sehbehinderte Benutzer nicht aus. Dies erfordert die Verwendung von gutem Platzhaltertext, um den Zweck der Benutzereingabe anzuzeigen, zusammen mit einigen Sonderzeichen. Es erfordert auch einen guten Einführungstext vor dem Codeblock oder der Referenz auf die Benutzeroberfläche. Beispiel: "Geben Sie in der Befehlszeile Folgendes ein und ersetzen Sie "mein-Benutzername" durch Ihren tatsächlichen Benutzernamen."

Ich bevorzuge eckige Klammern <>und Text mit Bindestrich im Inneren. Zum Beispiel:

URL-Format:http://<your-host-name>:<your-port-number>.com/

Der Text sollte etwas sein, das dem Benutzer klar macht, dass er durch den tatsächlichen Wert ersetzt werden muss. Dies gilt auch für etwaige Überlegungen zur Barrierefreiheit.

Wie die anderen Antworten zeigen, haben sich für verschiedene Systeme unterschiedliche Praktiken etabliert .

Es ist wichtig, zwischen Texten zu unterscheiden, die sich hauptsächlich an Personen richten, die sich dieser technischen Zusammenhänge bewusst sind, und Texten, die sich an Personen richten, die sich dessen nicht bewusst sind.

Menschen, die in die erste Gruppe passen, werden normalerweise diese Art der Substitution erwarten, weil sie daran gewöhnt sind. Die in den anderen Antworten angegebenen Methoden reichen aus: Diese Standards wurden aus einem bestimmten Grund festgelegt.

Benutzer, die nicht an technisches Schreiben und den entsprechenden Dokumentationsstil gewöhnt sind, können mit solchen Anweisungen Schwierigkeiten haben. Neben der optischen Hervorhebung des zu ersetzenden Begriffs kann es diesen Benutzern helfen , Bemerkungen zur Verdeutlichung hinzuzufügen, wie zum Beispiel:

Ersetzen Sie im folgenden Codeausschnitt die Partition durch den Namen des Geräts, auf dem Sie das ext4-Dateisystem erstellen möchten:

# mkfs.ext4 /dev/ -Partition

Abhängig von verschiedenen Betriebssystemen/Plattformen ist der Benutzer auf die Verwendung von Sonderzeichen beschränkt.

Beispielsweise beschränkt Windows die Verwendung von Sonderzeichen beim Erstellen eines Ordners/einer Datei, aber Linux erlaubt die Verwendung von Sonderzeichen zum Benennen eines Ordners/einer Datei.

Dokumentation/Handbuch für eine Software/Plattform wird unter Berücksichtigung all dessen erstellt.

Während ich recherchierte, um dies zu beantworten, stieß ich auf dieses schöne Software-Dokumentationsdokument , das erwähnt wird

Dokumentationsformate für vom Benutzer eingegebene Befehle oder Codes müssen klar zwischen Literalen (genau wie gezeigt einzugeben) und Variablen (vom Benutzer auszuwählen) unterscheiden.

Robert Lauriston hat Recht. <> ist die richtige Methode zum Dokumentieren von Benutzereingaben im Code in der Microsoft-Dokumentation.

Viele Leute schlagen vor, %-Zeichen zu verwenden, um Benutzereingaben in der Dokumentation zu dokumentieren. Das wäre in der Microsoft-Dokumentation falsch.

%-Zeichen werden in Microsoft als Systemumgebungsvariablen verwendet. dh %SystemRoot%bezieht sich auf das Installationsverzeichnis von Windows. (normalerweise: C:\Windows)

Microsoft erklärt "Umgebungsvariablen"

Ich mag die Art und Weise, wie die GitHub-Dokumentation dies handhabt, indem sie eine andere Farbe und einen anderen Stil verwendet:

Es reicht nicht aus, nur eine andere Farbe zu verwenden, da es sehbehinderte Leser gibt.

Ich hatte Probleme damit, die richtige Ausgabe für verschiedene Kombinationen von Monospace, Kursiv und Fett in der sich ständig ändernden Auswahl an Ausgaben zu erhalten, die ich aus dem Single-Source-System generierte, das ich damals verwendete, also verwende ich einfache ASCII-Interpunktion:

< > : vom Benutzer bereitzustellen, z. B.MON <application name>

{ } : Wählen Sie eines aus einer Reihe von Elementen aus, die durch | getrennt sind, z. B.LIST { ROLES | USERS }

[ ] : optional, z. B. MON [application name>]( MONkann allein verwendet werden oder gefolgt vom Namen einer Anwendung)

Diese Konvention wird in einem Abschnitt "Über diese Dokumentation" erläutert. Wenn der Befehl kompliziert ist, folge ich der Befehlssyntax mit einem Beispiel.

Sie möchten wahrscheinlich eine andere Zeichensetzung verwenden, wenn Sie etwas wie XML dokumentieren, wo der Code voller spitzer Klammern ist.

Das Microsoft Manual of Style hat eine gute Reihe von Konventionen, wenn die Textformatierung für Sie funktioniert (siehe "Befehlssyntax").

%Prozentzeichen% fallen mir sofort ein, wie in "Willkommen, %Benutzername%!"