¿Cuáles son las técnicas estándar que indican al lector de documentación que debe sustituir su propio texto apropiado (por ejemplo, nombre de usuario, dominio)?

En mi experiencia , esta combinación de puntos funciona muy bien:

• Al comienzo de su guía, proporcione una instrucción sobre cómo hará referencia a los comandos, texto/opciones especificados por el usuario, etc. La cursiva es común para esto. Por ejemplo: texto indica texto que debe proporcionar y debe representar datos reales, como su dirección de correo electrónico, nombre de usuario, contraseña, etc.
• Use opciones de formato, uso de mayúsculas y sintaxis coherentes en todos sus documentos.
• Use un carácter especial común para rodear la entrada del usuario, como las llaves %, <> o [] ya sugeridas (aunque he visto que marcan una entrada opcional). Deje explícitamente claro si los caracteres especiales deben incluirse en la entrada o no.
• Use una forma coherente de hacer referencia a las entradas comunes de los usuarios (marcadores de posición) como "mi-nombre-de-usuario", "mi-contraseña", "mi-correo-electrónico@dominio.com" o "". Asegúrese de que estén definidos con ejemplos al comienzo de su guía.

Esto también es lo que dice el Manual de estilo de Microsoft sobre el tema del formato para la entrada del usuario:

Entrada del usuario Normalmente en minúsculas, a menos que se distinga entre mayúsculas y minúsculas. Negrita o cursiva, según el elemento. Si la cadena de entrada del usuario contiene texto de marcador de posición, use cursiva para ese texto.

Una consideración de accesibilidad :

El formato simple o el color no funcionarán para los usuarios con discapacidades visuales. Esto requiere el uso de un buen texto de marcador de posición para indicar el propósito de la entrada del usuario, junto con algunos caracteres especiales. También requiere un buen texto introductorio antes del bloque de código o la referencia de la interfaz de usuario. Por ejemplo: "En la línea de comando, escriba lo siguiente y reemplace "mi-nombre-de-usuario" con su nombre de usuario real".

Prefiero los corchetes angulares <>y el texto con guión dentro. Por ejemplo:

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

El texto debe ser algo que haga que sea obvio para el usuario entender que debe reemplazarse con el valor real. Esto también tiene en cuenta cualquier consideración de accesibilidad.

Como muestran las otras respuestas, se han establecido diferentes prácticas para varios sistemas .

Es importante diferenciar entre textos que se dirigen principalmente a personas que son conscientes de tales tecnicismos y textos que se dirigen a personas que no los conocen .

Las personas que encajan en el primer grupo normalmente esperarán este tipo de sustitución porque están acostumbradas. Los métodos dados en las otras respuestas serán suficientes: estos estándares se han establecido por una razón.

Los usuarios que no están acostumbrados a la redacción técnica y al estilo de documentación correspondiente pueden tener dificultades con dichas instrucciones. Además de enfatizar ópticamente el término que se va a reemplazar, puede ayudar a estos usuarios agregar comentarios para aclarar, como:

En el siguiente fragmento de código, reemplace la partición con el nombre del dispositivo en el que desea crear el sistema de archivos ext4:

# mkfs.ext4 /dev/ partición

Dependiendo de los diferentes sistemas operativos/plataformas, el usuario está restringido a usar caracteres especiales.

Por ejemplo, Windows restringe el uso de caracteres especiales al crear una carpeta/archivo, pero Linux permite usar caracteres especiales para nombrar una carpeta/archivo.

La documentación/manual para un software/plataforma se prepara teniendo todo eso en cuenta.

Mientras investigaba para responder a esto, encontré este hermoso documento de documentación de software , menciona

Los formatos de documentación para los comandos o códigos ingresados ​​por el usuario deben distinguir claramente entre literales (para ingresar exactamente como se muestra) y variables (para ser seleccionadas por el usuario).

Robert Lauriston tiene razón. <> es la forma correcta de documentar la entrada del usuario en código en la documentación de Microsoft.

Mucha gente sugiere usar signos de % para documentar la entrada del usuario en la documentación. Eso sería incorrecto en la documentación de Microsoft.

Los signos % se utilizan como variables de entorno del sistema en Microsoft. es decir %SystemRoot%, hace referencia al directorio de instalación de Windows. (normalmente: C:\Windows)

Microsoft explica "Variables de entorno"

Me gusta la forma en que la documentación de GitHub maneja esto usando un color y estilo diferente:

Usar un color diferente no es suficiente, ya que hay lectores con problemas de visión.

Tuve problemas para obtener la salida correcta para varias combinaciones de monoespaciado, cursiva y negrita en la variedad de salidas en constante cambio que generaba a partir del sistema de fuente única que estaba usando en ese momento, así que uso la puntuación ASCII básica:

< > : a proporcionar por el usuario, por ejemplo,MON <application name>

{ } : elija uno de un conjunto de elementos separados por |, por ejemplo,LIST { ROLES | USERS }

[ ] : opcional, por ejemplo, MON [application name>]( MONse puede usar solo o seguido del nombre de una aplicación)

Esta convención se explica en la sección "Acerca de esta documentación". Si el comando es complicado, sigo la sintaxis del comando con un ejemplo.

Probablemente querrá usar un conjunto diferente de puntuación si documenta algo como XML, donde el código está lleno de corchetes angulares.

El Manual de estilo de Microsoft tiene un buen conjunto de convenciones si el formato de texto funciona para usted (consulte "Sintaxis de comandos").

Inmediatamente me vienen a la mente %signos de porcentaje%, como "¡Bienvenido, %nombre de usuario%!"