Documentación/Guía de estilo
Generalidades
Esta guía de estilo brinda asistencia para la escritura y la edición de documentos técnicos para MediaWiki y otros espacios técnicos. Ofrece sugerencias para ayudarte a escribir documentos técnicos concisos y claros en lenguaje llano. Además, te conecta con recursos adicionales sobre escritura técnica y edición en general.
Una buena documentación técnica hace que a la gente le sea más sencillo contribuir a los proyectos de Wikimedia. Es importante seguir normas y directrices claras para escribir y editar documentación, sobre todo cuando las personas colaboradoras y lectoras tienen diferentes niveles de habilidad y experiencia. No importa si te consideras redactor técnico. ¡Tus contribuciones son necesarias y apreciadas!
Manual de estilo de Wikipedia en inglés
The English Wikipedia's Manual of style covers general writing topics (like punctuation) in detail, and summarises the key points of other style guides. It can be a useful reference for anyone writing or editing technical documentation in English across Wikimedia projects, especially if the local wiki doesn't have more specific guidelines.
This page provides basic guidelines and tips to help get you started with technical documentation. It includes some information specific to technical documentation that is not covered in the Wikipedia Manual of Style.
Audiencia y contenido
Redactar para audiencias técnicas
Antes de comenzar a redactar, ten en cuenta al público que te va a leer:
- ¿Quiénes leerán esta documentación técnica?
- ¿De dónde provienen?
- ¿Hasta qué nivel conocen los conceptos que vas a presentar?
- ¿Qué podrían necesitar saber para comprenderlo?
Una vez que tengas conocimiento de tu público, tendrás una mejor idea de qué necesitas comunicar.
- Si sabes que tu público es muy técnico y está altamente familiarizado con los procesos que vas a describir, no hará falta explicar los conceptos básicos.
- Si sabes que tu público está en proceso de aprendizaje o que no está familiarizado con los procesos que vas a describir, incluye explicaciones de conceptos básicos y enlaces a información adicional.
Redactar con propósito
¿Qué propósito tendrá tu documentación técnica? Hay muchas razones para escribir documentación. Es útil saber por qué escribes y cuál es tu objetivo antes de empezar.
- ¿Se trata de formar a alguien, como por ejemplo un novato, acerca de un proceso o un concepto?
- ¿Se trata de enseñar a alguien a seguir un proceso?
- ¿Se trata de proporcionar un trasfondo y un contexto para explicar un concepto o proceso?
- ¿Se trata de una referencia con la intención de proporcionar información?
Redactar en un contexto
A la hora de decir qué escribir y cómo enmarcárselo a tus lectores, puede ser útil definir un contexto y ocasión para tu escritura. Tu comunicación se produce en el contexto de una situación más amplia. El contexto puede estar delimitado por la época en la que estás escribiendo, el tipo de tecnología disponible, tu ubicación geográfica y tu cultura, o la cultura actual y los estilos de comunicación de tus lectores. Puede que la ocasión sea personal y surja de la situación que te motivó a crear o mejorar una obra de documentación.
Por ejemplo, si estás escribiendo documentación técnica para proyectos Wikimedia, ten en consideración la cultura generada por los individuos que participan en esos proyectos. ¿Cómo podrías posicionar mejor tu redacción en el contexto de esta comunidad y su cultura para crear la documentación técnica más significativa y útil?
Pruebas con los usuarios y retroalimentación
Crea documentación técnica para comunicar ideas y conceptos a un público real de usuarios. Naturalmente, este público debe desempeñar un papel crítico en la manera en que toma forma y se remodela la documentación. Piensa en formas en que puedes recopilar información sobre las experiencias de tus usuarios. Tómate unos momentos para responder a estas preguntas:
- ¿Tu documentación incluye algún mecanismo para obtener retroalimentación?
- ¿Puedes participar en conversaciones puntuales con el público para hacer mejoras?
- ¿Puedes recurrir a foros como Stack Overflow o listas de correo para comprobar si tu documento resuelve las dudas más habituales de la gente sobre tu tema particular?
Claridad y consistencia
La claridad y consistencia hace que sea más fácil acceder, leer y crear documentación técnica en los proyectos MediaWiki/Wikimedia. La documentación técnica está escrita por una gran variedad de colaboradores para un público amplio.
La voz, el tono, el uso de la gramática, el estilo y el formato deben ser consistentes en la documentación técnica en su conjunto y en colecciones similares de contenido. Esto ayuda a los lectores a aprender a navegar por la información y a los colaboradores a entiender con mayor facilidad cómo editar y añadir nueva información.
Decidir el tipo de documento
Identifica en primer lugar tu público principal, el objetivo y el contexto para decidir el tipo de documento que vas a crear.
| Ejemplo de audiencia | Propósito[1] | Tipos de documentos en potencia | Ejemplo |
|---|---|---|---|
| Usuario novato con interés en aprender a utilizar Toolforge | Para aprender | Cursillo tutorial, preguntas frecuentes, guía de primeros pasos | Preguntas frecuentes de Cloud VPS y Toolforge |
| Colaborador técnico experimentado que trata de analizar un problema conocido | Para lograr un fin | Guía paso a paso, procedimiento | Mi primera herramienta OAuth con Flask |
| Individuo que trata de entender la historia de ORES y cómo evolucionó | Para comprender | Artículo explicativo, publicación de post, «visión general» | El servicio de inteligencia artificial «ORES» le da a wikipedistas gafas de rayos X para ver a través de las ediciones problemáticas |
| Una persona que busca una definición de claves SSH | Para informar | Guía de referencia, glosario | Glosario |
Lenguaje
Esta sección menciona brevemente algunos temas que merece la pena explorar con mayor detalle en otros sitios.
Coteja siempre tus palabras y expresiones contra estos criterios en el Wikcionario:
las entradas del Wikcionario cubren cientos de idiomas, declaran explícitamente las características gramaticales y léxicas de las palabras y sus declinaciones, proporcionan indicaciones detalladas de contexto (por ejemplo, jerga, inglés británico o estadounidense) y exponen cómo se traducen los términos en cientos de idiomas.
Inglés llano
Recuerda que muchas de las personas que visitan estas páginas no son hablantes de inglés como primera lengua.
Para la documentación escrita en inglés, lo que mejor funciona es el inglés llano (o lenguaje claro). Una redacción clara es la más comprensible para un público diverso, y también es la más fácil de traducir. Hay numerosas herramientas de calidad a tu disposición para evaluar tu redacción en las Pautas de escritura de las Noticias Técnicas en Meta-Wiki.
- Evita las ambigüedades, la jerga y las expresiones vagas o complejas.
- Emplea palabras que tu público vaya a entender, y suficientes palabras para transmitir el mensaje.
- Define los términos que puedan no ser obvios para aquellas personas que estén empezando con el tema que quieres transmitir.
- Mantén los párrafos y las oraciones breves y al grano.
- Utiliza contracciones o no las utilices. Sé consistente.
Voz y tono
En MediaWiki cualquiera puede editar. Debido a ello, puede ser difícil mantener la consistencia en la voz y el tono en la documentación.
Considera utilizar estos elementos en tu redacción:
| Voz y tono | Lo que significa | En vez de esto | Prueba con esto |
|---|---|---|---|
| Amigable | La documentación técnica no tiene por qué sonar académica o seca. Escribe a tu público como si estuviese contigo en persona. | Antes de empezar, el usuario debe crear una cuenta. | Empieza creando una cuenta. |
| Profesional | La documentación técnica puede ser amigable, pero debe seguir siendo profesional. Utiliza Lenguaje inclusivo. | No te líes a hacer un montón de cambios. | Trata de hacer cambios mínimos. |
| Positiva | Evita usar construcciones de frases en negativo. Explica las cosas en función de qué hacer. ¡Procesar mentalmente una frase negativa compleja puede ser difícil! | N no ocurrirá si no haces XYZ. | Para que ocurra N, haz XYZ. |
| Activa | Trata de recurrir a la voz activa, excepto en los casos en que la diplomacia exige usar la voz pasiva. | La extensión tiene que ser registrada. | Tienes que registrar la extensión. |
| Sin marca de género | Adopta el lenguaje inclusivo de género. Asume que tu público incluye todas las identidades de género. | Cuando el usuario pulse en Guardar | Cuando se pulse en Guardar |
| Inclusiva | Utiliza alternativas a palabras o frases habituales que pueden reafirmar involuntariamente estereotipos inapropiados. | Esta interfaz está de locos. | Esta interfaz podría mejorarse. |
| Sin frustraciones | Evita usar términos como «fácil» y «simple», que pueden ser frustrantes para usuarios menos avezados en las tecnologías. | Simplemente crea una cuenta de usuario. | Crea una cuenta de usuario. |
| Sin coloquialismos | Puede resultar confuso recurrir a expresiones coloquiales, chistes, juegos de palabras y giros lingüísticos que los hablantes no nativos o de otras regiones pueden no entender con facilidad. | Crear una cuenta de usuario es coser y cantar. | Crear una cuenta de usuario requiere de dos pasos. |
Punto de vista
- Utiliza la segunda persona («tú» o «usted», ya sea de forma explícita o implícita) al dirigirte a tu público.
- Evita la primera persona («yo» o «nosotros») a menos que estés redactando un compendio de preguntas frecuentes desde la perspectiva de la primera persona.
- Sírvete del modo imperativo en la mayor parte de la documentación centrada en metas o procesos.
Fechas
- Utiliza siempre el año completo, con las cuatro cifras.
- Emplea fechas absolutas («en mayo de 2037») en lugar de fechas relativas («el año que viene en mayo»).
- Evita añadir fechas que haya que actualizar regularmente a mano. Por ejemplo, escribe
{{#time: Y }}en ligar de 2025 para referirte al año actual sin importar qué año sea en este momento.
Estructuración de las páginas
Visión general
Todas las páginas deberían incluir una sección de visión general (también denominada sección introductoria o entradilla) que explique:
- Propósito de la página
- Público de la página
- Prerrequisitos que deberá cumplir la persona lectora antes de continuar (p. ej., un conocimiento funcional de Python)
- Programas o herramientas que la persona lectora necesitará para completar los procesos o las tareas descritas en la página (p. ej., Java instalado)
- Caso de uso, estudio de casos, un entendimiento práctico del producto, servicio o herramienta en acción. (opcional)
Tabla de contenidos
- Todas las páginas deben incluir una tabla de contenidos para acceder a la información de forma más sencilla.
Títulos y encabezados
- Utiliza la capitalización de oración en los encabezados.
- Mantén la consistencia en las fuentes tipográficas de los encabezados en toda la documentación.
- El uso de anclas para enlazar a secciones o subsecciones de la misma página es facultativo.
- Añade una línea en blanco después de los encabezados de sección. Esto impacta la manera en que se empaqueta el contenido para la traducción.
- No pongas un encabezado antes de tu sección de visión general o entradilla.
- Do not put links inside section headings: it impacts mobile usability.
Flujo de la información
Las páginas de documentación técnica deben seguir un patrón consistente entre las distintas colecciones de contenido.
Un esquema ideal para cada página podría ser:
- Título de la página
- Introducción/Visión general
- Encabezado
- Contenido
- Subtítulo, si es necesario
- Contenido
- Subtítulo, si es necesario
- Contenido
Formato del texto
Ejemplos de código para dar formato y otros elementos técnicos
El formato distingue el código y otros elementos técnicos del texto regular.
| Propósito | Marcado wiki | Resultado | Situación |
|---|---|---|---|
| Code | <code>code</code>
|
code
|
Para cadenas cortas de código, incluido el marcado de wikitexto.
Dentro de |
| Syntax highlight |
<syntaxhighlight lang="css">
.citation {
margin: 0;
}
</syntaxhighlight>
Texto anterior a |
.citation {
margin: 0;
}
Texto anterior a |
Utiliza la etiqueta <syntaxhighlight lang="...">...</syntaxhighlight> para documentar unas pocas líneas de código preservando los espacios en blanco y los saltos de línea. El atributo inline permite utilizarlo dentro de un párrafo existente.
Ten en cuenta que no puedes poner cursiva en medio de un bloque Consulta Extensión:SyntaxHighlight para más información. |
| Preformatted | <pre>preformatted text
|
preformatted text
with indent
|
Igual que lo anterior (preserva los espacios en blanco y los saltos de línea), pero sin colorer. |
| Keyboard input | <kbd>keyboard 123</kbd> (vs keyboard 123)
|
keyboard 123 (vs keyboard 123) | Utiliza <kbd>...</kbd> para la entrada por teclado, es decir, el texto que el usuario teclea en un campo de entrada de texto o en una terminal de línea de comandos. Se muestra de forma plana y monoespaciada.
|
| Variables | <var>variable</var>
''italics''
|
variable
italics |
Utiliza la cursiva para variables como clave-de-mensaje y nombres de muestra como Título de mi página.
No utilices signos de puntuación tales como <YOURPASSWORD>, ya que los lectores no sabrán que los corchetes angulares son ruido y los teclearán. |
| Bold | '''bold'''
|
bold | Generalmente solo se usa la primera vez que se pone el título de la página, y en raros casos para dar énfasis a las palabras clave para facilitar la exploración rápida de listas o párrafos.
A veces se abusa de la negrita para dar énfasis. Puedes considerar la alternativa de utilizar una plantilla, por ejemplo, {{Caution}}, {{Note}} o {{Warning/core}}.
|
| Quotations | "quotation marks"
Texto anterior
Texto posterior |
"quotation marks"
Text beforeText after |
Utiliza comillas para citar fragmentos breves de contenido de otras fuentes.
Utiliza la cita en bloque (blockquote) para fragmentos más largos de contenido. |
| Abbreviations | JavaScript (JS)
|
JavaScript (JS)
JS |
Es recomendable definir las abreviaturas la primera vez que se usan. Puedes utilizar texto plano entre paréntesis o bien la etiqueta HTML abbr.
|
| Keypress | {{Key press}}
|
Ctrl+⇧ Shift+I | Mostrar pulsaciones o combinaciones de pulsaciones específicas de teclado. Ejemplos más detallados en Editor visual/Portal/Atajos de teclado.
Nota: Esta plantilla puede no existir en otros wikis. |
| Button | {{Button}}
|
Mostrar previsualización | Mostrar botones de la interfaz de usuario que hay que pulsar.
Nota: Esta plantilla puede no existir en otros wikis. |
Enlaces
| Tipo | Propósito | Implementación | Ejemplo |
|---|---|---|---|
| Local | Enlace a otras páginas de MediaWiki |
|
MediaWiki |
| Destino traducido | Enlace a otras páginas de MediaWiki traducidas | [[Special:MyLanguage/Foo|Foo]]
|
Cómo contribuir |
| Interwiki | Enlace a páginas pertenecientes a otro proyecto de Wikimedia |
|
Página «Documentación» en Wikipedia en inglés |
| Externo | Enlace a páginas externas | [https://www.example.org Example.org]
|
Example |
Plantillas
Las plantillas se utilizan habitualmente en las páginas de MediaWiki.org.
Las plantillas pueden ayudar a mantener la consistencia y pueden facilitar la traducción de contenido.
A continuación se enumeran algunas plantillas comunes.
Plantillas para formatear una página
- {{Caution}}, {{Fixtext}}, {{Note}}, {{Tip}}, {{Todo}}, {{Warning/core}} - para estilos de cuadros resaltados en línea
- {{Arréglame}}, {{Historical}}, {{Notice}}, {{Outdated}}, {{Actualizar}} - para cuadros de mensajes de página/sección
- {{Principal}}, {{See also}} - para notas de cabecera de página/sección (notas cortas situadas en la parte superior de un artículo)
Plantillas para el núcleo de MediaWiki y las fuentes de Git
- {{Class doclink}}, {{File doclink}}, {{Js doclink}} - para enlazar a la documentación generada del núcleo de MediaWiki
- {{Archivo de MW}} - para un cuadro con información y enlaces acerca de un archivo del núcleo de MediaWiki
- {{Git file}} - para enlazar al código fuente
Plantillas para Phabricator
- {{Ptag}} - para la etiqueta de proyecto Phabricator en la esquina superior derecha de la página
- {{Seguido}} - para la tarea asociada de Phabricator
Otras plantillas útiles
- {{irc|wikimedia-tech}} - para enlazar a IRC
- {{Key press}} - para, por ejemplo, Ctrl+⇧ Shift+I, y {{Button}} para, por ejemplo, Mostrar previsualización
- {{ApiEx}} - para las URL de petición de api.php
- {{Ayuda de la API}} - para transcluir documentación generada de la API
- {{Wg}} - para variables globales
- {{Tag}} - como forma rápida de mencionar una etiqueta de estilo XML de forma preformateada
Dispositivos móviles
En Recommendations for mobile friendly articles on Wikimedia wikis y Mobile Gateway/Mobile homepage formatting están disponibles unas recomendaciones generales para páginas wiki adaptadas a dispositivos móviles. Esta sección proporciona consejos útiles en el contexto de la documentación, desarrollados como parte de T383117.
- Prueba tu documentación en un dispositivo móvil. Puedes hacerlo también en tu navegador de sobremesa utilizando el modo de diseño adaptable en Firefox y Safari o la barra de herramientas de dispositivo en Chrome. Prepárate para hacer cambios en la página si notas algún problema. Los incidentes más comunes son: márgenes o sangrados innecesarios, ajuste de texto incorrecto y elementos de bloque que no encajan en sus contenedores.
- Aquellas páginas que solo incluyan encabezados, párrafos normales y listas se representarán correctamente con casi total seguridad en dispositivos móviles. Estas páginas no deberían necesitar ningún estilo personalizado, pero aun así merece la pena hacer pruebas.
- A la hora de diseñar un elemento de página o una plantilla desde cero con HTML y CSS:
- Utiliza Extensión:TemplateStyles para acceder a las funcionalidades CSS que no puedes añadir directamente a la propiedad de estilo de una etiqueta HTML.
- Prepárate para crear reglas CSS separadas para dispositivos de escritorio y móviles (ejemplo).
- Utiliza funcionalidades de CSS tales como media queries, flexbox y diseño en cuadrícula (grid layout) para asegurarte de que tu elemento personalizado se vea correctamente en todo tipo de dispositivos.
- Utiliza tablas solo para presentar datos. No utilices tablas para maquetar contenido o diseñar menús.
- Si vas a incluir un fragmento de código en la página, asegúrate de que sea legible en pantallas estrechas. Algunos fragmentos de código se ven bien con ajuste de texto, pero otros no. En este último caso, fija el estilo a
overflow-x: auto; white-space: pre;para preservar la maquetación del código.
Traducciones
Todas las páginas de mediawiki.org son candidatas para la traducción a varios idiomas. MediaWiki.org es un wiki multilingüe; utiliza la extensión Translate para presentar traducciones alternativas y gestionar la traducción de páginas.
- Si una página está traducida, haz clic en 'Editar fuente' para editar toda la página.
<languages>, <translate>, <tvar>
- No copies y pegues marcado existente. En caso de duda, céntrate en redactar un buen texto y deja que otra persona se encargue del marcado de Translate.
Véase también
- Otras guías sobre documentación técnica:
- Wikiversity:Technical writing
- Otros recursos relacionados con el idioma