Principios generales

Diez principios gobiernan todo lo que el grupo publica en español. Accesibilidad, afirmaciones con respaldo, nada de anuncios anticipados, audiencia global, lenguaje inclusivo, jerga bajo control, documentación que recomienda un camino, respeto al contenido ajeno, texto que no envejece y una sola voz. Las reglas de gramática, puntuación y formato que estos principios invocan viven en las otras secciones de la guía. Las reglas de la casa que van más lejos que el original se citan por su id de core/prosa (P01 a P37) y ganan cuando hay conflicto.

La adaptación cambia tres cosas respecto del original. Primero, todo lo que es propio del inglés (artículos a/an, contracciones, Title Case, comillas inglesas, coma de Oxford) se reemplaza por la regla equivalente del español. Segundo, los ejemplos de Google Cloud y Android se reemplazan por los productos del grupo: cis-admin, cochid-datos, el manual de operación de vps-cis y el archivo societario. Tercero, las reglas de la casa que el original no tiene se dicen explícitas: cero raya (P05), nunca voseo (P06), tildes siempre, sin muletillas de IA (P01) y la cifra antes que la interpretación.

Accesibilidad

Toda la documentación del grupo se escribe pensando en accesibilidad. Esta sección no es una referencia exhaustiva: reúne pautas generales y ejemplos de buenas prácticas. La Organización Mundial de la Salud estima que el 15 % de la población mundial (más de 1.000 millones de personas) tiene alguna necesidad de accesibilidad. Cuando la documentación se escribe con eso en mente, mejora la experiencia de todos los lectores, no solo la de quienes usan tecnologías de apoyo.

Temas relacionados: audiencia global, lenguaje inclusivo y voz y tono.

Qué hacer y qué no, en general

• No uses lenguaje capacitista. Evita el sesgo y el daño al hablar de discapacidad y accesibilidad. Más detalle en Evita el sesgo al hablar de discapacidad.
• Asegúrate de que el lector puede llegar a todas las partes del documento (pestañas, botones de envío de formularios, elementos interactivos) usando solo el teclado, sin mouse ni trackpad.
• Prueba tu documentación con un lector de pantalla. Esa prueba revela problemas de accesibilidad en el contenido y es una buena forma de autoeditarse. En Linux, Orca viene instalado con GNOME; en Android, TalkBack; en iOS y macOS, VoiceOver.
• En HTML, usa etiquetado semántico. Por ejemplo, usa em solo para indicar énfasis, no para poner cursiva.
• En HTML, prefiere los elementos nativos a los estilos personalizados. El kit cis-style ya los cubre: un botón es <button>, no un <div> con onclick.
• Evita el formato de fuente innecesario. Los lectores de pantalla describen explícitamente cada cambio de formato.
• Si documentas un producto que incluye funciones de accesibilidad específicas, documéntalas de forma explícita. Por ejemplo, si una CLI del grupo ofrece barras de progreso en porcentaje o salida sin color, dilo y explica cómo se activan.
• No fuerces saltos de línea dentro de oraciones y párrafos. Los saltos forzados se comportan mal al redimensionar la ventana o al agrandar el texto.
• Evita cuando puedas el camelCase y las MAYÚSCULAS SOSTENIDAS. Algunos lectores de pantalla leen las mayúsculas letra por letra. Sigue las pautas de mayúsculas.
• Según el lector de pantalla y su configuración, no todos los signos de puntuación se leen. Asegúrate de que el sentido se conserva sin ellos. Por esa razón, evita cuando puedas los signos de exclamación, los de interrogación y el punto y coma (en modo estricto de la norma el punto y coma está prohibido: P31).
• No uses & en lugar de «y» en títulos, texto, navegación o índices. Está bien usarlo cuando citas un elemento de interfaz que lo contiene, o en encabezados de tabla y etiquetas de diagrama donde el espacio obliga a abreviar. En código, por supuesto, & se usa con su sentido técnico.

Facilidad de lectura

• Rompe los muros de texto para que el lector pueda escanear. Separa párrafos, crea encabezados y usa listas.
• Usa oraciones cortas. La norma fija el tope: 40 palabras por oración en prosa, 25 en modo estricto (P11). Google recomienda menos de 26; la casa llega al mismo número por otro camino.
• Define las siglas y abreviaturas la primera vez que aparecen y cada vez que aparecen con poca frecuencia. Más en abreviaturas.
• Usa estructuras paralelas para cosas parecidas. Por ejemplo, empieza cada elemento de una lista con el mismo formato.
• Pon la información distintiva e importante de cada párrafo en la primera oración (la norma lo llama «oración temática inicial»). Eso es también la regla data-forward de la casa: la cifra o el hecho van primero, la interpretación después.
• Usa lenguaje claro y directo. Evita las dobles negaciones y las excepciones a las excepciones.
  Recomendado Puedes continuar sin indicar una ruta.

  No recomendado Que falte la ruta no te impide continuar.
• Alinea el texto a la izquierda. No lo centres ni lo justifiques.

Encabezados y títulos

Usa encabezados y títulos descriptivos: ayudan al lector a moverse por el navegador y por la página. Saltar entre páginas y secciones es más fácil si los encabezados y títulos son únicos.

• Usa una jerarquía de encabezados.
• No te saltes niveles. Por ejemplo, pon un h3 solo después de un h2.
• Para cambiar el aspecto visual de un encabezado usa CSS, no un nivel de encabezado que no corresponde a la jerarquía.
• No dejes encabezados vacíos ni encabezados sin contenido asociado.
• Etiqueta los encabezados con elementos de encabezado. En HTML: h1, h2, etc. En Markdown: #, ##, etc.
• Usa un encabezado de nivel 1 para el título de la página o del contenido principal.
• Escribe los títulos en minúscula de oración: solo la primera palabra y los nombres propios llevan mayúscula (P37). El Title Case del inglés no existe en español.

Más información y ejemplos en títulos y encabezados.

Enlaces

• Usa texto de enlace con significado. Un enlace tiene que entenderse fuera de contexto.
• No uses «haz clic aquí» ni «lee este documento». Muchas personas que usan lector de pantalla saltan de enlace en enlace para escanear la página y necesitan saber qué contiene cada uno.
• Usa «ver» o «consulta» para referirte a enlaces y referencias cruzadas, nunca «mira». Ver la entrada correspondiente del glosario.
• Cuando un enlace hace algo que el lector no espera (descarga un archivo, abre otra pestaña, salta a otra sección de la misma página), explícalo al enlazar. Más en referencias cruzadas y enlaces.
• Evita cuando puedas los enlaces adyacentes. Sepáralos con un carácter intermedio; la casa usa el punto medio (·).

Listas

• En un procedimiento, cada instrucción es un elemento de lista.
• Usa listas para que el lector pueda seguir los pasos con facilidad.

Imágenes

• Dale un atributo alt a cada imagen. Cuando el alt lleva texto alternativo, ese texto resume la intención de la imagen. Si la imagen es puramente decorativa, usa alt="".
• No presentes información nueva en imágenes. Acompaña siempre la imagen con una explicación equivalente en texto.
• No repitas imágenes salvo que sea imprescindible.
• No uses imágenes de texto, de muestras de código ni de salida de terminal. Usa texto real. Una captura de journalctl no se puede copiar, buscar ni leer con lector de pantalla.
• Prefiere SVG a PNG cuando exista. El SVG se mantiene nítido al hacer zoom.

Más información en figuras e imágenes.

Videos, grabaciones y GIF

• Entrega subtítulos, transcripciones o descripciones del contenido de audio y video. Los subtítulos automáticos de YouTube sirven como punto de partida, no como versión final.
• Asegúrate de que los subtítulos se puedan traducir a los idiomas principales.
• No uses elementos que parpadean o destellan. Provocan desde mareo hasta convulsiones.

Botones e íconos

• Para los botones de envío de formularios usa el elemento nativo button de HTML.
• Un ícono es un símbolo o imagen que representa un objeto o una función. Cómo nombrarlos en el texto se explica en la sección de botones e íconos de elementos de UI e interacción.

Navegación por la interfaz

Cuando documentes una ruta de menú con el signo mayor que (>), agrega un atributo aria-label para que el lector de pantalla lo interprete como «y luego» en vez de «mayor que» o «flecha derecha». Ejemplo: <span aria-label="y luego">></span>. Más ejemplos en elementos de UI e interacción.

Tablas

• Presenta la tabla en el texto que la precede: no todos los lectores de pantalla anuncian las tablas.
• Usa encabezados de tabla solo en la primera columna y en la primera fila. Usa el elemento th.
• Si la tabla tiene encabezados de fila y de columna, marca las celdas de encabezado con el atributo scope.
• Si la tabla tiene más de una fila de encabezados de columna, usa el atributo headers y asegúrate de que los encabezados tienen id únicos.
• Evita cuando puedas las tablas en medio de un procedimiento numerado.
• No combines celdas. No uses los atributos colspan ni rowspan.
• No uses tablas salvo que sean la mejor forma de presentar la información. Las tablas son difíciles para los lectores de pantalla. Más en listas (lista o tabla).
• No presentes información nueva en tablas solo con imágenes o símbolos; entrega siempre un atributo alt descriptivo para la imagen o el símbolo. Un estado indicado solo con ● verde o ● rojo en un panel de cis-mando no le dice nada a quien no ve el color.

Más información en tablas.

Elementos interactivos

Presenta el elemento interactivo (por ejemplo, un botón que expande y contrae) en el texto que lo precede.

También es aceptable, si la interfaz lo pide: «Para ver la lista de requisitos, haz clic en la flecha de expansión ▸».

Formularios

• Etiqueta cada campo de entrada con un elemento label.
• Pon las etiquetas fuera de los campos, no como placeholder dentro de ellos.
• Cuando redactes un mensaje de error de validación, di con claridad qué falló y cómo se corrige. Por ejemplo: «El RUT es obligatorio» o «El RUT 12.345.678-9 no tiene un dígito verificador válido». Los mensajes de error van en modo estricto de la norma.

CSS y JavaScript propios

Usa los estilos y el JavaScript estándar del sitio tanto como puedas: en el grupo, eso es el kit cis-style (tokens, componentes, chrome). Si de todos modos escribes estilos o código propios, sigue estas pautas:

• Elige colores que respeten las razones de contraste accesible (4,5:1 para texto). Los tokens del kit ya lo cumplen en tema claro y oscuro; si inventas un color, pierdes esa garantía.
• No uses visibility:hidden ni display:none para contenido que el lector necesita. Ambos lo ocultan también al lector de pantalla.
• Evita cuando puedas los eventos mouseover. Si los usas, agrega eventos focus y blur equivalentes para quienes navegan con teclado.
• Asegúrate de que el orden y la posición definidos en los estilos reflejan el DOM y el orden de lectura de la página (de izquierda a derecha y de arriba abajo). Un order de flexbox que reordena visualmente no reordena la lectura.

Cómo se renderiza el documento

Asegúrate de que el documento transmite toda la información que querías transmitir cuando lo ves en estos contextos:

• Sin sonido
• Solo con sonido
• Sin imágenes, incluidas las animaciones
• Sin color
• Solo con teclado
• Con ampliación de pantalla
• Sin puntuación

No uses el color, el tamaño, la posición u otras pistas visuales como forma principal de comunicar información.

• Si usas color, un ícono o el grosor de un contorno para indicar estado, entrega además una segunda pista, como un cambio en la etiqueta de texto. En cis-mando, «● activo» y «● caído» llevan la palabra, no solo el punto.
• Nombra los botones y demás elementos por su etiqueta. Para elementos visuales sin texto, no intentes describir el dibujo: usa el atributo aria-label del elemento si existe.
  Recomendado Haz clic en Guardar. · Haz clic en Notificaciones.

  No recomendado Haz clic en el ícono de la campanita.
• No uses lenguaje direccional para orientar al lector, como «arriba», «abajo» o «a la derecha». Funciona mal por accesibilidad y por localización: lo que está a la derecha en un idioma que se lee de izquierda a derecha queda a la izquierda en uno que se lee de derecha a izquierda.
• No uses lenguaje direccional para señalar una posición en el documento. Para quien escucha el texto con un lector de pantalla nada está «abajo». Usa «anterior», «precedente» o «siguiente».
  Recomendado En el diagrama anterior, el poller recibe los DTE y los entrega a cis-admin.

  No recomendado En el diagrama de arriba, el poller recibe los DTE y los entrega a cis-admin.
• Si un elemento de interfaz es difícil de encontrar, incluye una captura de pantalla.
  Recomendado Haz clic en Menú.

  No recomendado En el panel de la izquierda, haz clic en el botón de las tres rayitas.

Más recursos

• Pautas de accesibilidad para el contenido web (WCAG) 2.1
• Iniciativa de accesibilidad web (WAI)
• Prácticas de autoría ARIA
• Tutoriales de accesibilidad web del W3C

Afirmaciones excesivas

En la documentación no hagas afirmaciones excesivas. Una afirmación excesiva es cualquier aseveración que haga una de estas cosas:

• Afirma algo sobre rendimiento o costo que el lector no puede verificar con facilidad con datos a su alcance.
• Afirma algo sobre seguridad que un incidente de seguridad invalidaría.
• Afirma algo que puede leerse como subjetivo o incluso despectivo, en especial sobre productos de terceros.

Al evaluar si un texto hace una afirmación excesiva, considera no solo lo que es cierto hoy sobre el rendimiento, el costo, la seguridad o la funcionalidad del producto, sino lo que puede ser cierto en el futuro.

Ten en cuenta estas pautas:

• Al describir productos, evita los superlativos: «el mejor», «el más simple», «el más rápido», «nunca», «siempre». Ten el mismo cuidado con «asegura» y «garantiza»: úsalos solo cuando algo se puede asegurar o garantizar de verdad. La norma de la casa va más lejos y bloquea los adjetivos de marketing («de vanguardia», «de clase mundial», «de última generación», «revolucionario», «disruptivo», «sin fricciones», seamless): P04. Muestra el dato (cifra, fecha, latencia) o elimina el adjetivo.
• Si haces afirmaciones concretas de rendimiento (qué tan rápido es un producto, cuánto almacenamiento requiere, etc.), cita la fuente de la información: la consulta, el comando, la fecha de la medición. La regla de frescura del grupo aplica también a la documentación: un dato lleva marca de tiempo y origen.
• Si la documentación afirma que un producto es seguro, queda invalidada (y pierde credibilidad) el día en que alguien logra comprometerlo. Es más seguro decir que una función «ayuda a la seguridad» o «está diseñada para la seguridad»: esas frases siguen siendo ciertas aunque ocurra un incidente.
• Una afirmación sobre un producto de la competencia puede ser falsa si interpretaste mal cómo funciona, o volverse falsa después, cuando la otra empresa publique una versión nueva.
• No atribuyas la afirmación a una autoridad fantasma («los expertos señalan», «estudios demuestran», «es ampliamente considerado»). Cita la fuente o elimina la autoridad: P17.

Lo más seguro es escribir siempre de forma factual y objetiva, y limitar lo que dices a información verificable que siga siendo cierta durante toda la vida del documento.

Funciones futuras

Evita documentar funciones o productos futuros, incluso de manera inocua. No anuncies nada por adelantado en la documentación salvo que tenga aprobación expresa de quien responde por el producto (en el grupo, la persona a cargo del repo; para compromisos con clientes o con el SII, la gerencia de CIS).

La razón es la misma que en documentación atemporal: una frase como «la próxima versión permitirá exportar a Excel» convierte el documento en una promesa, fija una fecha implícita y queda falsa si el plan cambia. Los planes viven en otro lado: en el grupo, en cis/docs/plans/, en el backlog del catastro o en todo.md del repo, nunca en la página que describe lo que el producto hace hoy.

A veces una función está en desarrollo y el lector necesita saberlo, por ejemplo porque un campo aparece en la interfaz pero no opera. Descríbela por su estado actual y verificable: «El botón Exportar a Excel está deshabilitado; la función no está disponible». Ver también presente y documentación atemporal.

Audiencia global

El grupo escribe su documentación en español de Chile (es-CL). Pero parte de ella la leen personas de otros países de habla hispana, personas para quienes el español no es su primera lengua, y sistemas de traducción automática que la llevan a otros idiomas. El resumen ejecutivo CIF, por ejemplo, existe en inglés.

Escribe pensando en localización, traducción e internacionalización. Estos términos significan cosas distintas:

• Localización: adaptar un producto y su documentación a un país concreto. Es más que traducir: por ejemplo, usar la moneda o las unidades de medida locales.
• Traducción: pasar un texto de un idioma a otro. Puede incluir localización, pero no son sinónimos.
• Internacionalización: diseñar el producto y su documentación para minimizar el esfuerzo de localización. Por ejemplo, poner todas las cadenas de la interfaz en un archivo aparte para simplificar la traducción.

Temas relacionados: accesibilidad, lenguaje inclusivo y voz y tono.

Usa un lenguaje claro, conciso y sin ambigüedad

Piensa en la audiencia global y en la traducción, y escribe de forma clara, concisa y sin ambigüedades.

Usa palabras simples y oraciones cortas

• Usa la palabra simple. No escribas «dar inicio» cuando quieres decir «empezar», ni «consecuentemente» cuando quieres decir «así que», ni «utilizar» o «apalancar» cuando quieres decir «usar». (Está bien usar la palabra larga cuando transmite un sentido especial: «Postgres utiliza hasta el 100 % de la CPU disponible durante el VACUUM».) Es el segundo principio de Orwell y el diccionario de la norma.
• Usa una sola palabra cuando transmite la misma idea que una frase. No escribas «una serie de» cuando puedes escribir «varios» o «muchos». No escribas «realizar un análisis» cuando puedes escribir «analizar»: la nominalización está bloqueada (P03).
• Escribe oraciones cortas. Cuanto más corta la oración, más fácil de traducir. Una oración de largo promedio en español puede dar una oración larga al traducirla. Las oraciones largas dificultan la comprensión, rompen el diseño de la página o de la interfaz, alargan la traducción y encarecen la revisión. El tope de la casa es 40 palabras (25 en modo estricto): P11.

Evita los verbos de apoyo

• El inglés tiene verbos frasales (make use of, set up); el español tiene verbos de apoyo: «hacer uso de», «llevar a cabo», «proceder a», «dar inicio a», «tomar la decisión de», «tener la capacidad de». Busca primero el verbo simple. A veces no existe uno mejor («iniciar sesión», «dar de alta» son excepciones legítimas).
  Recomendado Este documento usa los siguientes términos:

  No recomendado Este documento hace uso de los siguientes términos:

Usa los modificadores con cuidado

• No acumules modificadores. En español la cadena de sustantivos del inglés se vuelve una cadena de «de»: más de dos seguidos y el lector se pierde.
  Recomendado Un pipeline de recepción de DTE para el entorno de certificación

  No recomendado Un pipeline de recepción de documentos de intercambio de facturación del entorno de certificación del SII
• No descoloques los modificadores. Pon palabras como «solo» inmediatamente antes de la palabra o frase a la que se refieren. Si el sentido sigue siendo ambiguo, reformula la oración.
  Recomendado Solicita solo un token. · Solicita como máximo un token.

  No recomendado Solo solicita un token.

Usa voz activa y presente

• Usa el presente y evita las formas verbales complejas o poco comunes. Ver presente.
• Usa la voz activa. El sujeto de la oración es la persona o cosa que ejecuta la acción. Con la pasiva, el lector a menudo no sabe quién tiene que hacer qué. La pasiva con agente («fue elaborado por X») se marca como P23; en procedimientos, la activa es la única forma admitida (P30). Ver voz activa.

Usa las palabras en su sentido primario

• No uses la misma palabra con dos significados. En particular, evita usar la misma palabra como sustantivo y como verbo cerca una de otra («el archivo se archiva en el archivo»). Ver las entradas del glosario para «una vez», «mientras», «como» y «desde».
• Evita el lenguaje direccional («arriba», «abajo») en documentación de procedimientos. Ver elementos de UI e interacción.

Usa palabras de apoyo y palabras opcionales

• Acompaña las palabras clave técnicas con un sustantivo calificador. Cuando hables del archivo example.yaml, di «el archivo example.yaml», no example.yaml a secas. Más en código en el texto.
• Repite una palabra si la redundancia mejora la comprensión.
  Recomendado Si la VM arrancó y si puedes conectarte...

  No recomendado Si la VM arrancó y puedes conectarte...
  Recomendado El diseño de jerarquía de recursos crea segmentación de permisos y segmentación de red por defecto.

  No recomendado El diseño de jerarquía de recursos crea segmentación de permisos y de red por defecto.
  Recomendado Una regla de salida cuya acción es allow, cuyo destino es 0.0.0.0/0 y cuya prioridad es la más baja posible (65535).

  No recomendado Una regla de salida cuya acción es allow, destino es 0.0.0.0/0 y prioridad es la más baja posible (65535).
• Usa palabras de apoyo. El español conversacional se come «entonces», «de» y «que». Úsalas para evitar ambigüedad.
  Recomendado Si no se encuentra la clave del atributo, entonces se devuelve el valor por defecto.

  No recomendado Si no se encuentra la clave del atributo, se devuelve el valor por defecto.
  Recomendado Identifica todos los conjuntos de datos.

  No recomendado Identifica los conjuntos de datos.
  Recomendado Inicia el perfilador y luego ejecuta la aplicación.

  No recomendado Inicia el perfilador, ejecuta la aplicación.
  Ver también pronombres.
• No omitas los pronombres relativos. En inglés that se puede omitir; en español «que» no se omite nunca, pero sí se pierde a veces el antecedente. Para dar claridad, repite el sustantivo en vez de dejar un «que» colgando.
  Recomendado Puedes actualizar por API las reglas que definiste antes.

  No recomendado Puedes actualizar por API las definidas antes.

Aclara abreviaturas y pronombres

• Define las siglas. Fuera de contexto confunden y se traducen mal. Escribe el nombre completo siempre que puedas, al menos la primera vez que usas el término en cada página: «Servicio de Impuestos Internos (SII)», «documento tributario electrónico (DTE)». Ver abreviaturas.
• Aclara los antecedentes. Los pronombres se complican cuando quien traduce trabaja con cadenas cortas y sueltas. Si un pronombre es ambiguo, reemplázalo por el sustantivo.
  Recomendado Si usas el término «día hábil» en un contrato, asegúrate de que el contrato lo define.

  No recomendado Si usas el término «día hábil» en un contrato, asegúrate de que lo define.

Plurales y posesivos sin apóstrofo

El apóstrofo del inglés no existe en español: ni para plurales ni para posesivos. Las siglas no llevan «s» de plural («las API», «los DTE», nunca «las API's» ni «los DTEs»); el plural lo marca el artículo. Las marcas y nombres de producto no se pluralizan ni se declinan («dos instancias de cis-admin», no «dos cis-admins»). Ver plurales, posesivos y contracciones y apócopes.

Háblale al lector y a lo que necesita

Dirígete al lector y a sus necesidades de forma directa, y evita la información que no necesita.

• Háblale de tú. Usa «tú» en vez de «el usuario» o «ellos», salvo que hables de alguien que usa el software que el lector está desarrollando. Español neutro, nunca voseo: «puedes», «imprime», «vuelve» (P06). Ver segunda persona.
• Da contexto. No des por hecho que el lector ya sabe de qué hablas.
• Evita las construcciones negativas cuando puedas. Pregúntate si hace falta decirle al lector lo que no puede hacer en vez de lo que puede.

Sé consistente

Usa estructuras de oración estándar, terminología consistente y puntuación adecuada para no crear barreras de comprensión, ambigüedad ni traducciones erradas.

Usa terminología consistente

Si usas un término para un concepto en un lugar, usa exactamente el mismo término en todos los demás, con las mismas mayúsculas. Si le das nombres distintos a la misma cosa, quien traduce puede pensar que son conceptos distintos y traducirlos distinto. La inconsistencia terminológica encarece la traducción, sobre todo cuando la memoria de traducción y la traducción automática son el primer paso. La norma lo fija como regla bloqueante: un significante, un significado (P07); las variantes prohibidas de cada repo viven en su .prosa.json. La rotación de sinónimos es el hábito número uno del texto generado.

Usa estructuras de oración y formatos estándar

• Usa frases estandarizadas para las oraciones frecuentes, las frases de introducción y las tareas comunes. Ejemplos en cómo introducir un enlace, cómo introducir una muestra de código y cómo introducir la salida de un comando.
• Usa el orden estándar del español: sujeto, verbo, complemento.
• Mantén el sujeto y el verbo principales lo más cerca posible del inicio de la oración.
• Pon la condición primero. Si quieres que el lector haga algo en una circunstancia concreta, menciona la circunstancia antes de la instrucción. Ver estructura de la oración.
• Haz los elementos de lista consistentes. Estructura paralela, mismas mayúsculas, misma puntuación. Ver listas.

Usa formato de texto consistente

• Usa formatos tipográficos consistentes. Negrita y cursiva con el mismo criterio en todo el documento. No pases de cursiva para énfasis a subrayado. Ver el resumen de formato de texto.
• Usa mayúsculas de forma consistente. Ver mayúsculas.
• Usa los formatos numéricos de es-CL en todo el grupo. Miles con punto y decimales con coma (1.215.716; 0,46 %); fechas como 20-08-2026 o «20 de agosto de 2026»; horas en formato de 24 h (14:30). Ver números y fechas y horas.

Sé inclusivo

No escribes para tu cultura. Escribe con inclusión en mente. Más en lenguaje inclusivo.

• Escribe fechas y horas sin ambigüedad. «03-04-2026» se lee distinto en Chile y en Estados Unidos; si hay duda, escribe el mes con letras.
• No seas demasiado específico culturalmente. En particular, no te refieras a feriados, prácticas culturales ni deportes salvo que estés seguro de que se conocen en todo el mundo. «Antes de Fiestas Patrias» no significa nada en Lima.
• Usa un conjunto diverso de nombres de ejemplo. Si necesitas nombres de personas (por ejemplo, en direcciones de correo), varíalos. Ver dominios y nombres de ejemplo.
• Evita coloquialismos, modismos y jerga local. «A ojo de buen cubero», «dejar en veremos» o «al tiro» confunden y se traducen mal.
• Evita el humor. La mayor parte del humor es difícil de traducir y mucho es culturalmente específico.
• Evita las referencias geográficamente específicas, como las estaciones del año. Recuerda que agosto es invierno en Santiago y verano en Madrid. Escribe el mes o el trimestre.

Considera la accesibilidad de las imágenes

Usa capturas de pantalla y texto dentro de figuras con moderación. Las imágenes no se traducen. Cualquier información nueva va en el texto, no en una figura. Ver figuras e imágenes.

Lenguaje inclusivo

Nota: esta sección menciona términos que pueden resultar irrespetuosos u ofensivos. Están aquí para dar pautas de uso y ofrecer alternativas.

Cuando escribes con inclusión y diversidad en mente, el contenido queda más preciso y claro para todos los lectores. Evita cualquier lenguaje idiomático o figurado que pueda malinterpretarse o distraer.

Esta sección no es una referencia exhaustiva: reúne pautas generales y ejemplos de buenas prácticas para escribir documentación inclusiva.

Temas relacionados: audiencia global, accesibilidad y voz y tono.

Evita el lenguaje innecesariamente marcado por género

Cuida los pronombres que usas en los ejemplos narrativos y presta atención a otras fuentes de lenguaje marcado por género.

La convención del grupo para el género gramatical en documentación técnica: reformula alrededor del género en vez de marcarlo. Usa sustantivos colectivos o epicenos («el equipo», «la persona», «quien administra», «la gerencia»), la segunda persona («tú») o el infinitivo. No uses formas dobladas («los usuarios y las usuarias»), ni la arroba, la equis o la «e» como marca de género («usuari@s», «usuarixs», «usuaries»): rompen los lectores de pantalla, la búsqueda y la traducción automática. Cuando el colectivo no existe, el masculino genérico del español es aceptable.

Evita el lenguaje figurado

Usa lenguaje simple y terminología precisa y clara para todas tus audiencias:

• Evita el lenguaje idiomático o figurado que pueda malentenderse, distraer o dificultar la traducción.
• Evita la jerga.
• Usa términos que sean estándar en la industria y que la audiencia objetivo entienda.

Al buscar un tono cercano y conversacional, es fácil caer sin querer en lenguaje figurado: figuras retóricas y giros de frase. Presta atención a la elección de palabras, sobre todo cuando apuntas a un tono informal.

No uses metáforas ni uses un término en sentido metafórico (usa las palabras en su sentido primario). Por ejemplo, evita la metáfora de «mascotas contra ganado» para comparar sistemas con estado y sistemas sin estado. La norma marca además las metáforas gastadas («la punta del iceberg», «tormenta perfecta», «marcó un antes y un después», «sentó las bases») como P22.

Para términos concretos, consulta el glosario.

Evita el lenguaje capacitista

El lenguaje capacitista incluye palabras y frases como «loco», «demente», «ciego a», «hacerse el ciego», «cojo», «mudo», «tonto» y otras. Elige una palabra más precisa o una alternativa según el contexto.

Evita el lenguaje gráfico o metafórico

Evita el lenguaje innecesariamente gráfico o metafórico cuando existe un término más preciso.

Por ejemplo, en vez de STONITH (shoot the other node in the head), usa términos concretos que describan el proceso con que se detiene un nodo errante. Si tienes que mencionar un término así, menciónalo una vez al explicar la función por primera vez, y formula la frase de modo que el término quede en segundo plano.

Aceptable a veces, si el lector va a encontrar el término en otra parte: «Este enfoque puede exigirte aislar los nodos que fallan (lo que a veces se llama STONITH)».

Usa siempre los términos más precisos y mejor entendidos para tu contexto. En algunos contextos un término establecido en la industria tiene un significado técnico específico sin sinónimo exacto. Ver las entradas del glosario para «terminar» y «ejecutar».

Para términos concretos, consulta el glosario.

Escribe ejemplos diversos e inclusivos

Escribe para una audiencia global. Usa nombres, géneros, edades y lugares diversos en los ejemplos. Ten presente lo siguiente:

• Sigue la pauta de pronombres y la convención de género gramatical descrita antes en esta sección.
• Evita ser demasiado específico de Chile. Cuidado al referirte a feriados (ver la entrada «feriados» del glosario), prácticas culturales, deportes y figuras retóricas.
• En los ejemplos, elige un conjunto diverso de nombres para reflejar la audiencia global. Las pautas para personas ficticias están en dominios y nombres de ejemplo.
• Al escribir sobre adultos mayores, evita términos y giros como «los ancianos», «los viejos», «la tercera edad» o «80 años jóvenes». Usa «adultos mayores» o «población que envejece», o menciona la edad relativa o la relación de la persona con las demás del ejemplo cuando ese dato sea pertinente.

Escribe sobre funciones y usuarios de forma inclusiva

Evita referirte a las personas de forma divisiva. Por ejemplo, en vez de hablar de «hablantes nativos» y «no nativos» de español, pregúntate si el documento necesita tratar eso, y reescríbelo para describir la función en términos pertinentes para cualquiera, sepa los idiomas que sepa.

Evita cuando puedas los términos con carga social para conceptos técnicos. Por ejemplo, evita blacklist, whitelist, «función nativa» y «ciudadano de primera clase», aunque sigan siendo de uso extendido.

Reemplaza los términos no inclusivos o escribe alrededor de ellos

Esta parte explica cómo reemplazar un término no inclusivo o cómo rodearlo. Si un término está asentado en la industria y reemplazarlo confundiría al lector, ver Reemplaza términos establecidos. Si el término aparece en muestras de código o palabras clave, ver Escribe alrededor de términos no inclusivos en código. Sobre la jerga no inclusiva, ver jerga.

Reemplaza términos establecidos

Muchos términos no inclusivos tienen uso masivo en la industria, como whitelist. Si reemplazar un término establecido puede confundir al lector, menciona el término no inclusivo en el primer uso, entre paréntesis, y usa el término inclusivo de reemplazo en el resto del documento.

En muchos casos, en vez de reemplazar una palabra por otra, puedes reescribir para mejorar la claridad de la oración. Por ejemplo, en vez de cambiar el verbo «whitelistear» por «permitir», reescribe la oración entera.

Escribe alrededor de términos no inclusivos en código

A veces los términos no inclusivos están incrustados en código (o similar) como nombres o palabras clave, y no puedes ignorarlos y usar otra terminología. Lo que sí puedes hacer es minimizar el uso del término (y así evitar propagarlo como término técnico) sin dejar de documentar con claridad. No uses un nombre o palabra clave no inclusiva salvo en fuente de código.

Estos son los escenarios típicos. El primero: documentas un sistema existente en el que una entidad ya tiene un nombre no inclusivo. Por ejemplo, un archivo de configuración con este nombre de clúster:

apiVersion: v1
kind: Config
preferences: {}

clusters:
- cluster:
  name: master
- cluster:
  name: replica-1

El segundo: la documentación incluye un término no inclusivo que es palabra clave establecida, como SLAVE en dialectos de SQL:

START SLAVE UNTIL SQL_AFTER_MTS_GAPS;

La primera vez que te refieres a un elemento de código que usa un término no inclusivo, puedes nombrarlo directamente, pero en fuente de código y, si se puede, entre paréntesis.

En las menciones siguientes usa el término preferido («nodo principal», «réplica»). Si hace falta volver a citar el nombre de la entidad o la palabra clave, hazlo solo en fuente de código. En el grupo, la rama principal de todos los repos se llama main; si heredas un repo con master, renómbrala antes de documentarla.

Evita el sesgo y el daño al hablar de discapacidad y accesibilidad

Muchos desarrolladores crean productos pensando en accesibilidad y discapacidad. Al documentar esas funciones, y al escribir sobre personas con discapacidad o sobre accesibilidad, trabaja para eliminar el sesgo y el daño involuntarios. Tómate el tiempo de aprender cómo prefieren identificarse y ser descritas las comunidades sobre las que escribes antes de escribir sobre ellas.

Algunas pautas generales:

• No describas a las personas sin discapacidad como «normales» o «sanas». Eso margina a las personas con discapacidad al implicar que son anormales o que están enfermas. Usa «persona sin discapacidad», «persona vidente», «persona oyente» o «persona neurotípica».
• Investiga cómo prefieren identificarse las personas de las comunidades sobre las que escribes y usa los términos que ellas prefieren. En muchos casos, evita los términos que borran a la persona o que la definen por su discapacidad: evita «los discapacitados» o «un tetrapléjico» y usa «personas con discapacidad» o «una persona tetrapléjica». Sin embargo, muchas personas de algunas comunidades prefieren el lenguaje que pone la identidad primero; esa preferencia es común en las comunidades autista, ciega y Sorda. La mayúscula de las identidades también varía. Siempre que puedas, investiga y elige los términos que respetan cómo se identifica cada comunidad.
• Usa «ver» o «consulta» para referirte a enlaces y referencias cruzadas. Ver la entrada correspondiente del glosario.
• Evita los términos que reflejan o proyectan sentimientos y juicios sobre la discapacidad de una persona, como «víctima de», «sufre de», «padece» o «postrado en silla de ruedas». Usa términos neutros: «tiene», «vive con», «usa silla de ruedas».
• Evita los eufemismos y los términos condescendientes como «con capacidades diferentes», «especial» o «angelito».

Jerga

La jerga es la terminología especializada y a menudo figurada de un grupo específico para representar un concepto mayor: camel case, «carril» (swim lane), «procedimiento rompe-vidrios» (break-glass), «listo para usar» (out-of-the-box). La jerga también incluye términos vagos o sobrecargados como «solución», «soporte» o «carga de trabajo».

Por lo general, el significado de la jerga solo lo entiende el grupo que la usa. Por eso la jerga estorba al objetivo de publicar contenido claro, que llegue a una audiencia global en varios idiomas, que sirva a lectores con distintos niveles de conocimiento del producto y que sea inclusivo de distintos grupos y culturas.

Sin embargo, parte de la jerga es de uso amplio y aceptada por la industria o por la audiencia del documento. Puede valer la pena incluirla cuando sabes que los lectores buscan esos términos. Si vas a usar jerga, hazte estas preguntas:

• ¿Puedes escribir alrededor del término? Si no lo necesitas para posicionamiento en buscadores (SEO), intenta rodearlo. Por ejemplo, en vez de «Haz un post-mortem», escribe «Cuando el incidente termine, revisa qué procesos funcionaron y cuáles no». En vez de «Haz un diseño en una servilleta», escribe «Usa un proceso de diseño informal».
• ¿Puedes reemplazar el término por otro más específico? El glosario de esta guía ofrece varios reemplazos: «área afectada» o «alcance» (para blast radius), «importar» o «cargar» (para ingest), «prefabricado» o «listo» (para off-the-shelf). Cuando un término del glosario está marcado como «no se usa» (parte de la jerga es ofensiva, violenta o no inclusiva), reemplázalo o escribe alrededor de él. El quinto principio de Orwell y la norma dicen lo mismo: ni extranjerismo ni jerga cuando existe el equivalente común.
• ¿Usas el término solo una vez en el documento? Si es así, describe el concepto en lenguaje llano y menciona el término entre paréntesis, o enlaza a una definición confiable.
  Recomendado Luego mueves la tarea a una etapa más temprana del proceso (lo que se conoce como shift left).

  No recomendado Luego haces shift left de la tarea.
  Recomendado Puede producirse una situación de cerebro dividido (split-brain).

  No recomendado Puede producirse un split-brain.
• ¿Usas el término a lo largo de todo el documento? Si es así, descríbelo brevemente entre paréntesis en la primera mención, o enlaza a una definición confiable.
  Recomendado La aplicación queda en el mismo estado que un respaldo en frío (un sistema de reserva idéntico al principal que no recibe tráfico).

  No recomendado La aplicación queda en el mismo estado que un cold standby.
  Recomendado Un mejor enfoque es usar un patrón llamado cola de mensajes muertos (dead letter queue).

  No recomendado Un mejor enfoque es usar una DLQ.
• ¿El término aparece en un comando o una muestra de código? Si es así, usa la palabra solo en referencia directa al elemento de código (en fuente de código) y deja claro a qué te refieres.
  Recomendado Agrega un usuario a la lista de permitidos (whitelist) con el siguiente comando: whitelist adduser CORREO.

  No recomendado Agrega un usuario a la whitelist con el siguiente comando: whitelist adduser CORREO.

Jerga propia del grupo que el lector externo no tiene por qué conocer: «el lake» (el data lake de cochid-datos), «el canal» (CHANNEL.md), «palena» (el ambiente de certificación del SII), «el gate» (la revisión previa a publicar). Dentro del manual de operación se usan sin explicar porque el glosario del manual las define; en cualquier documento hacia afuera, la primera mención lleva la explicación entre paréntesis.

Documentación prescriptiva

Escribe documentación prescriptiva.

La documentación prescriptiva (o con opinión) recomienda una manera de hacer las tareas y de cumplir los objetivos. Le dice al lector qué hacer en vez de darle una lista de opciones para que elija. Cuando un objetivo o tarea es complejo e involucra varios enfoques o productos, la documentación prescriptiva recomienda un camino.

La escritura prescriptiva afecta varios aspectos del documento:

• El propósito y la estructura. Un documento prescriptivo declara un propósito claro y específico. Los encabezados y el contenido se escriben con ese propósito en mente.
• Los escenarios de ejemplo y los procedimientos. Reflejan los casos de uso más probables para los lectores.
• Los comandos de ejemplo. La documentación prescriptiva entrega los comandos y argumentos que resuelven la tarea para el caso más común. Para las opciones de línea de comandos, ver sintaxis de línea de comandos.

Los documentos de buenas prácticas son, por naturaleza, prescriptivos. En el grupo, el manual de operación de vps-cis (/srv/projects/a) es el ejemplo: dice «despliega con deploy-cis», no «existen varias formas de desplegar».

Elección de palabras para recomendaciones y requisitos

Para indicar acciones obligatorias u opcionales, o los resultados de un proceso, elige el verbo auxiliar adecuado: «debe», «puede» o «podría». En general evita «debería». Esa palabra crea ambigüedad e incertidumbre y por eso es problemática en documentación prescriptiva. Si le estás diciendo al lector qué hacer, «debería» implica que la acción es recomendada pero opcional, y el lector no sabe qué hacer.

Para aclarar lo que quieres decir, determina si una acción es obligatoria u opcional, si un resultado es esperado o posible, y si un estado es real o recomendado.

• Si la acción es obligatoria: usa «debe», o reformula la oración como una instrucción imperativa clara: «Haz lo siguiente antes de continuar».
• Si la acción es recomendada: usa «Recomendamos...» o «CIS recomienda...». Puedes usar «deberías» si la acción recomendada es de reconocimiento general: «Deberías usar una contraseña fuerte», «Deberías seguir el principio de mínimo privilegio».
• Si la acción es opcional: usa «puedes». Por ejemplo: «También puedes usar el enfoque B para resolver el mismo problema».
• Si el resultado es esperado: describe el resultado en términos de lo que se espera. Por ejemplo: «El proceso devuelve 10 elementos».
• Si el resultado es posible: usa «puede» o «podría». Por ejemplo: «El proceso puede tardar unos 30 minutos».
• Si el estado es real: cuando describes el estado de algo, como el valor de una variable, evita escribir «El valor debería ser true». Aclara cuál de estas cosas quieres decir:
  • «Debes poner el valor en true.»
  • «El servidor pone el valor en true.»
  • «Si el valor es false, sigue estos pasos para cambiarlo a true.»
  Para aclarar quién ejecuta la acción, ver voz activa.

En modo estricto de la norma (procedimientos, runbooks, mensajes de error, texto de interfaz) el régimen verbal se cierra más. Solo se admiten las perífrasis «puede + infinitivo» y «debe + infinitivo»; «tiene que», «va a», «debe de» y «podrá» están fuera (P28), y el condicional («debería», «podría») también (P32). Ahí la tabla queda en dos palabras: «debe» para lo obligatorio, «puede» para lo opcional o posible.

Más recursos

• Ver también las entradas «puede», «podría», «debe», «debería» y «es posible que» en el glosario.

Contenido de terceros

No copies contenido de otra fuente: puede violar derechos de autor. En su lugar, parafrasea y enlaza al original.

«Contenido» incluye texto, imágenes, código, logos y voz.

Evita el contenido de terceros

Salvo que estés seguro de que el grupo es dueño del material, evita copiar de estas fuentes:

• Fuentes de terceros: documentación, sitios web, libros, blogs, videos, imágenes, pódcast y más.
• Obras de referencia: no copies de diccionarios, enciclopedias ni Wikipedia.
• Documentación de productos de código abierto: el software libre tiene licencias distintas, desde «ninguna reutilización sin atribución» hasta libertad total. No es seguro asumir que puedes reutilizar ese contenido. En caso de duda, no lo uses.
• Contenido de GitHub: cada usuario de GitHub puede elegir una licencia distinta para su contenido. No es seguro asumir que puedes reutilizarlo. En caso de duda, no lo uses.

Lo que sí se puede, y cómo

Esta guía es un ejemplo de la vía correcta. El original de Google se publica bajo CC BY 4.0, que permite adaptar y redistribuir con atribución; la atribución está al pie de cada página y dice qué se cambió. Si reutilizas material con licencia permisiva, cumple sus condiciones al pie de la letra: nombre del autor, licencia, enlace al original y aviso de los cambios.

Tres casos frecuentes en el grupo:

• Datos públicos. cochid-datos replica conjuntos de DIPRES, SII, ChileCompra y otros organismos. Cada conjunto lleva en su ficha la fuente, la fecha de descarga y la licencia o norma que autoriza su reutilización (Ley 20.285 y las condiciones de cada portal). Un número citado en un informe lleva su fuente al lado, no en una bibliografía al final.
• Logos y marcas ajenas. El logo del SII, del Banco de Chile o de una municipalidad pertenece a su dueño. Úsalo solo para identificar al organismo en un contexto factual y sin alterarlo; nunca como parte del diseño de un producto del grupo. Los logos propios canónicos viven en marcas.
• Código. Copiar una función desde Stack Overflow o desde un repo ajeno sin revisar la licencia contamina el repo. Si la licencia lo permite, deja el comentario de atribución con el enlace y la licencia en la misma función.

Documentación atemporal

La documentación atemporal evita las palabras y frases que la anclan a un momento o que asumen conocimiento de productos y funciones anteriores o futuras. En general, documenta la versión actual del producto o función.

La atemporalidad importa sobre todo en documentos técnicos que pueden leerse mucho después de escritos. Palabras como «ahora», «nuevo» y «actualmente» vuelven el documento impreciso, obsoleto o sin sentido. La documentación atemporal se concentra en cómo funciona el producto en este momento: no en cómo cambió respecto de versiones anteriores ni en cómo podría cambiar en el futuro.

Si escribes contenido con fecha, como comunicados, entradas de blog, el CHANNEL.md entre agentes o notas de versión, las palabras y frases temporales están bien. Por ejemplo, «nuevo» es correcto en una entrada que anuncia cambios: «cis-admin incluye varias funciones nuevas». O «pronto» sirve en un procedimiento para subrayar un cambio de estado tras un paso: «La VM se apaga poco después de que envías el comando». Pero esas mismas palabras envejecen o se vuelven falsas cuando describen las capacidades del producto en la documentación de producto, así que ahí se evitan.

Escribir documentación de producto atemporal tiene este valor:

• Reduce el mantenimiento necesario para tenerla al día.
• Evita asumir que el lector conoce versiones anteriores del producto.

Un documento atemporal no es un documento sin fecha. Cuando el contenido depende de un estado medido (saldos, conteos, latencias), lleva la marca de tiempo y la fuente del dato, igual que cualquier reporte del grupo: «a las 09:14 del 19-08-2026, según free -h». Lo que no lleva es la palabra «actualmente» en vez de esa marca.

Palabras y frases que evitar

Estas palabras y frases socavan la atemporalidad:

• Las que prometen o proyectan planes y estrategias. Al describir capacidades de un producto o función, palabras y frases como «por ahora», «al momento de escribir esto» o «con el tiempo» pueden revelar planes antes de tiempo, o insinuar indebidamente que el producto va a cambiar. En esos casos, no las uses. Ver funciones futuras.
• Las que están implícitas. En el grupo asumimos que la documentación está al día salvo que se indique una versión concreta. Así, «actualmente» y «al momento de escribir esto» ya las implica la existencia misma del documento.
• Las que envejecen apenas se publican. «Pronto» y «el más reciente» pierden sentido enseguida.
• Las que asumen conocimiento previo del producto. Si tienes que usar «nuevo», da un punto de referencia, como una fecha o un número de versión: «La versión del 14-01-2026 de cochid-datos incluye un panel de recursos nuevo».

Al describir capacidades de producto o función en documentación de producto y de referencia, evita estas palabras y frases:

• actualmente, en la actualidad
• ahora, hoy, hoy en día
• al momento de escribir esto, a la fecha
• aún no, todavía no
• con el tiempo, eventualmente
• existente
• futuro, en el futuro, a futuro
• el más reciente, el último
• nuevo, más nuevo
• antiguo, viejo, más antiguo
• por ahora, por el momento, de momento
• pronto, próximamente

Dos de esas frases ya están prohibidas en toda la prosa del grupo por otra razón: «hoy en día» y «en la era digital» son muletillas de IA bloqueantes (P01), y «en la actualidad» es muletilla leve (P18). La atemporalidad y el anti-slop apuntan a la misma lista.

Voz y tono

En tus documentos busca una voz y un tono conversacionales, cercanos y respetuosos, sin jerga callejera ni exceso de coloquialismo o frivolidad. Usa una voz natural y accesible, no pedante ni insistente. Intenta sonar como un colega que sabe del tema y entiende lo que el lector quiere hacer.

No intentes escribir exactamente como hablas; probablemente hablas con más coloquialismos y más palabras de las que conviene escribir, al menos en documentación técnica. Pero apunta a un tono conversacional antes que a uno formal.

No intentes ser súper entretenido, pero tampoco apuntes a lo súper seco. Sé humano, deja que se note algo de personalidad y sé memorable. Recuerda que el propósito principal del documento es entregar información a alguien que la busca y que puede tener prisa.

Considera que los lectores vienen de muchas culturas y pueden tener distintos niveles de lectura en español. En lo posible, evita las referencias culturalmente específicas. Escribir de forma simple y consistente también facilita traducir el documento a otros idiomas. Más en audiencia global.

La voz de la casa se resume en cuatro rasgos: español neutro de tú (P06), cero raya (P05), la cifra antes que la interpretación, y ninguna muletilla que anuncie lo que viene (P01, P15). La página Escritura del hub los desarrolla.

Temas relacionados: accesibilidad y lenguaje inclusivo.

Cosas que evitar cuando se pueda

• Palabras de moda o jerga técnica.
• Ser demasiado tierno o gracioso.
• El lenguaje figurado, que incluye las metáforas y el lenguaje capacitista (ver lenguaje inclusivo).
• Frases de relleno como «cabe destacar», «es importante señalar», «ten en cuenta que» y «en este momento». En la casa, las dos primeras bloquean el guardado (P01): si es importante, dilo primero; no lo anuncies.
• Oraciones entrecortadas o interminables.
• Empezar todas las oraciones con la misma frase («Puedes...», «Para hacer...»).
• Referencias a la cultura pop del momento.
• Signos de exclamación. En general, evítalos. Ver la entrada correspondiente del glosario.
• Payasadas, excentricidades y chistes forzados.
• Formulaciones que denigran o insultan a cualquier grupo de personas.
• Formular las cosas como «vamos a hacer tal cosa». En modo estricto, además, «va a + infinitivo» es una perífrasis no admitida (P28).
• Usar «simplemente», «es así de simple», «es fácil» o «rápidamente» en un procedimiento. Si el paso falla, el lector que leyó «simplemente» se siente tonto.
• Jerga de internet y abreviaturas como «tl;dr» o «ymmv».
• Los emoji en prosa formal (P19) y la regla de tres decorativa («rápido, seguro y confiable»): dos adjetivos precisos valen más que tres genéricos.
• Los residuos de chat (P35): «espero que te sirva», «¿quieres que profundice?», «excelente pregunta». Son texto pegado desde una conversación, no escrito para el documento.

Técnicas y enfoques que considerar

• Si te cuesta expresar algo, da un paso atrás y pregúntate: «¿Qué estoy tratando de decir?». A menudo la respuesta que te das revela lo que deberías escribir en el documento.
• Si dudas de una formulación o del tono, pídele a alguien del equipo que lo mire.
• Prueba leer partes del documento en voz alta, o al menos moviendo los labios. ¿Suena natural? No todas las oraciones tienen que sonar bien al decirlas en voz alta: son documentos escritos. Pero si una oración suena torpe o confusa al hablarla, considera si puedes hacerla más conversacional.
• Usa transiciones entre oraciones. Frases como «aunque» o «así» hacen los párrafos menos rígidos. (Y al revés: a veces «sin embargo» o «no obstante» los vuelven más rígidos. La norma mide la densidad de conectores de relleno y avisa cuando pasa de 1,5 por cada 100 palabras: P16.)
• Pásale prosa-lint al borrador. No mide el tono, pero detecta la forma del slop, y un texto sin muletillas ya suena más cercano.
• Aunque te cueste dar con el tono justo, asegúrate de comunicar información útil de forma clara y directa; eso es lo más importante.

Cortesía y uso de «por favor»

Está bien ser cortés, pero usar «por favor» en una secuencia de instrucciones es pasarse de cortés.

Ejemplos

Cada fila muestra el punto justo y los dos extremos: demasiado informal y demasiado formal.

Adaptación al español y a las convenciones del grupo de la Google developer documentation style guide, publicada bajo CC BY 4.0. Donde esta guía y la norma de prosa de la casa difieren, manda la norma (core/prosa/NORMA.md).