Jump to content

Documentación/Guía de estilo

From mediawiki.org
This page is a translated version of the page Documentation/Style guide and the translation is 39% complete.

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 ayudarle a escribir documentos técnicos concisos y claros en palabras llanas. Además, le conecta con recursos adicionales sobre escritura técnica y edición en general.

Una buena documentación técnica facilita a las personas a contribuir a los proyectos de Wikimedia. Es importante seguir normas y directrices claras para escribir y editar documentación, sobre todo cuando las y los contribuidores y lectores tienen diferentes niveles de habilidad y experiencia. No importa si se considera redactor/a técnico/a o no. ¡Sus 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, tenga a bien considerar la audiencia de su labor:

  • ¿Quiénes leerán esta documentación técnica?
  • ¿De dónde provienen?
  • ¿Cuánto conocen los conceptos que habrá de presentar?
  • ¿Qué podrían necesitar saber para comprenderlo?

Once you have an understanding of your audience, you will have a better sense of what you need to communicate.

  • Si sabe que su audiencia es altamente técnica y familiarizada con los procesos que describe, no hará falta explicar los conceptos básicos.
  • Si sabe que su audiencia está aprendiendo o no es familiar con los procesos que describe, incluya explicaciones de conceptos básicos y enlaces a información adicional.

Redactar con propósito

¿Qué propósito tendrá su documentación técnica? Hay muchas razones para redactar documentación. It is helpful to know why you are writing and what your goal is before you begin.

  • Is it to teach someone, like a newcomer, about a process or concept?
  • Is it to show someone how to follow a process?
  • Is it meant to provide background and context for a concept or process?
  • Is it a reference intended to provide information?

Redactar en un contexto

When deciding what to write and how to frame it for your reader, it can help to define a context or occasion for your writing. Your communication takes place in the context of a bigger situation. 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. The occasion may be personal and arise from the situation that motivated you to create or improve a piece of documentation.

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. How could you best position your writing within the context of this community and its culture to create the most meaningful and useful technical documentation?

User testing and feedback

Create technical documentation to communicate ideas and concepts to a real audience of users. Naturally, this audience should play a critical role in how the documentation is shaped and reshaped. Think about ways you can gather information about your users' experiences. Tómese unos momentos para responder a estas preguntas:

  • Does your documentation include a mechanism for feedback?
  • Can you engage in timely conversations with the audience to make improvements?
  • Can you use forums like Stack Overflow or mailing lists to check if your document answers the most common questions people have about your specific topic?

Claridad y coherencia

La claridad y consistencia hace más fácil acceder, leer y crear documentación técnica en los proyectos MediaWiki/Wikimedia. Technical documentation is written for a wide audience and edited by a variety of contributors.

Voice, tone, grammar usage, style, and format should be consistent across technical documentation and similar content collections. This helps readers learn how to navigate information and makes it easier for contributors to understand how to edit and add new information.

Decidir el tipo de documento


Identify your main audience, purpose, and context first to decide on the type of document you will create.

Ejemplo de audiencia Propósito[1] Tipos de documentos en potencia Ejemplo
Newcomer interested in learning how to become a Toolforge user Para aprender Cursillo tutorial, preguntas frecuentes, guía de primeros pasos PP. FF. de Cloud VPS y Toolforge
Experienced technical contributor trying to work through a known problem Para lograr un fin Guía paso a paso, procedimiento Mi primera herramienta OAuth con Flask
Individual trying to understand the history of ORES and how it evolved Para comprender Explanatory article, blog post, "overview" El servicio de inteligencia artificial «ORES» le da a wikipedistas gafas de rayos X para ver a través de las ediciones problemáticas
A person looking for a definition of SSH keys Para informar Guía de referencia, glosario Glosario

Lenguaje


This section briefly mentions some topics worth exploring elsewhere in more detail. Always check your words and expressions against these criteria on Wiktionary: Wiktionary entries cover hundreds of languages, explicitly state the grammatical and lexical features of words and their declensions, provide detailed context labels (including about jargon, UK vs. USA English) and expose how translatable terms are in hundreds of other languages.

Inglés llano

No se olvide de que muchas de las personas que visitarán estas páginas no serán hablantes de inglés como primera lengua.

For documentation written in English, Plain English (also called plain language) works best. Una redacción clara será la más entendible para audiencias diversas, y también será la más fácil de traducir. There are a number of good tools for checking your writing, at Tech News' Writing Guidelines on Meta-Wiki.

  • Avoid ambiguity, jargon, and vague or complex wording.
  • Use words your audience will understand, and enough words to convey your message.
  • Defina los términos que podrían no resultar obvios a las personas que estén comenzando en el tema sobre el que está redactando.
  • Mantenga los párrafos y las oraciones breves y al grano.
  • Use contracciones o no las use, pero mantenga el mismo estilo en todo el documento.

Voz y tono

En MediaWiki cualquiera puede editar. Thus, it can be difficult to maintain a consistent voice and tone in the documentation.

Consider using these elements in your writing:

Voz y tono Lo que significa En vez de esto Pruebe con esto
Amistosa La documentación técnica no necesita sonar académica o seca. Escriba a su audiencia como si la estuviese viendo en persona. Before beginning, the user must create an account. Start by creating an account.
Profesional Technical documentation can be friendly, but should remain professional. Use Lenguaje inclusivo . Don't make a bazillion changes. Try to make minimum changes.
Positiva Avoid using negative sentence constructions. Explain things in terms of what to do. It is harder to mentally parse a complex negative sentence! N won't happen, if you don't XYZ. To make N happen, do XYZ.
Activa Try to use active voice, except when diplomacy calls for passive voice. The extension must be registered. You must register the extension.
Sin marcación de género Adopt gender-inclusive language. Assume your audience comprises all gender identities. Cuando el usuario pulse en Guardar Cuando se pulse en Guardar
Inclusiva Utilice alternativas a palabras o frases habituales que pueden reafirmar estereotipos inapropiados sin proponérselo. Esta interfaz está de locos. Esta interfaz podría mejorarse.
Sin frustraciones Avoid terms like "easy" and "simple" which can be frustrating for less tech-savvy users. Simplemente cree una cuenta de usuario. Cree una cuenta de usuario.
Sin coloquialismos It can be confusing to use colloquialisms, jokes, puns, or turns of phrase that non-native English speakers or individuals from other regions might not easily understand. Creating a user account is a piece of cake. Creating a user account requires two steps.
This is not meant to be an exhaustive list or a strict set of rules.

Punto de vista

The following guidance overrides the general Wikipedia style guidelines for pronouns, but only for technical documentation.
  • Use second person ("You" or assumed "You") when addressing your audience.
  • Avoid first person ("I" or "we"), unless you are writing a FAQ with questions asked from the first person perspective.
  • Sírvase del modo imperativo en la mayor parte de los documentos focalizados en metas o procesos.

Fechas

  • Siempre use el año completo, con los cuatro dígitos.
  • Emplee fechas absolutas («en mayo de 2037») en lugar de fechas relativas («el año que viene en mayo»).
  • Avoid adding dates that will require regular manual updates. Example: Write {{#time: Y }} instead of 2024 when referring to the current year, no matter what year it is currently.

Estructuración de las páginas

Overview

All pages should include an overview section (also called the Lead section) that explains:

  1. Propósito de la página
  2. Audiencia de la página
  3. Prerrequisitos que deberá cumplir la persona lectora antes de continuar (p. ej., un conocimiento funcional de Python)
  4. Programas o herramientas que la persona lectora necesitará para completar los procesos o las tareas descritas en la página (p. ej., Java instalado)
  5. Use case, case study, a practical understanding of the product, service or tool in action. (optional)

Sumario

  • Todas las páginas deben incluir un sumario para acceder a la información de forma más sencilla.

Títulos

Flujo de la información

Technical documentation pages should follow a consistent pattern across content collections.

An ideal pattern for each page might be:

  • Título general de la página
  • Introduction/Overview
  • Título
    • Contenido
      • Subtítulo, si es necesario
        • Contenido

Formatting text

Página principal: Help:Formatting

Formatting code examples and other technical elements

Formatting distinguishes code and other technical elements from regular text.

Purpose Wiki-Markup Result Situation
Code ‎<code>code‎</code> code Use for short strings of code, including wikitext markup.

Within ‎<code>...‎</code>, use ''italics'' to indicate variables and sample names so users know what to replace.

Syntax highlight
<syntaxhighlight lang="css">
.citation {
    margin: 0;
}
</syntaxhighlight>

Text before <syntaxhighlight lang="css" inline>.foo {margin: 0;}</syntaxhighlight> text after.

.citation {
    margin: 0;
}

Text before .foo {margin: 0;} text after.

Use the ‎<syntaxhighlight lang="...">...‎</syntaxhighlight> tag to document a few lines of code, and preserve whitespace and linebreaks. The inline attribute allows using it within an existing paragraph.

Note you cannot use italic in the middle of a <syntaxhighlight lang="foo">...</syntaxhighlight> block, so you have to fall back to YOURPASSWORD or The_page_title to indicate variables.

See Extensión:SyntaxHighlight for more details.

Preformatted ‎<pre>preformatted text
      with indent‎</pre>
preformatted text
      with indent
Same as above (preserve whitespace and linebreaks), but without coloring.
Keyboard input ‎<kbd>keyboard 123‎</kbd> (vs keyboard 123) keyboard 123 (vs keyboard 123) Use ‎<kbd>...‎</kbd> for actual keyboard input - the text a user types into an input field or at a terminal command line. It displays in plain monospace.
Variables ‎<var>variable‎</var>
''italics''
variable

italics

Use italics for variables like message-key-name and sample names like My page title.

Do not use punctuation such as <YOURPASSWORD>, because readers don't know the angle brackets are noise and will type them.

Bold
'''bold'''
bold Generally only used for the first instance of the page-title, and for rare emphasis of keywords to enable easier skimming of lists or paragraphs.
Sometimes bold is overused for emphasis. You may consider using a template instead, e.g. {{Caution }}, {{Note }}, or {{Warning/core }}.
Quotations "quotation marks"

Text before

‎<blockquote>blockquote‎</blockquote>

Text after

"quotation marks" Text before

blockquote

Text after
Use quotation marks for brief pieces of content quoted from other sources.

Use blockquote for longer pieces of content.

Abbreviations JavaScript (JS)

<abbr title="JavaScript">JS</abbr>

JavaScript (JS)

JS

You should define abbreviations the first time they are used. Use either plain text and parentheses, or the HTML abbr tag.
Keypress {{Key press }} Ctrl+⇧ Shift+I Showing specific keyboard presses or combinations. Extensive examples in Editor visual/Portal/Atajos de teclado .

Note: This template might not exist on other wikis.

Button {{Button }} Mostrar previsualización Showing UI buttons that need to be clicked on.

Note: This template might not exist on other wikis.


Enlaces

Página principal: Help:Links
Tipo Propósito How to implement Ejemplo
Local Link to other MediaWiki pages
  • [[Foo]]
  • [[Foo|Bar]]
MediaWiki
Destino traducido Link to other translated MediaWiki pages [[Special:MyLanguage/Foo|Foo]] Cómo contribuir
Interwiki Link to page belonging to a different Wikimedia project
  • [[phab:T2001]] for tasks and project tags
  • [[mail:wikitech-l]] for mailing lists
  • [[w:en:foobar]] to English Wikipedia articles
  • [[wikitech:foobar]] for details about the WMF cluster
  • [[gerrit:604435]] for change requests in Gerrit
Documentation page on Wikipedia
External Link to external pages [https://www.example.org Example.org] Example

Plantillas


Templates are often used on MediaWiki.org pages. Templates can help to maintain consistency and can make it easier to translate information.

Below are some common templates.

Templates for page formatting

Templates for MediaWiki core and Git source

Plantillas para Phabricator

  • {{Ptag }} - for the top-right-of-page Phabricator project tag
  • {{Seguido }} - for the related Phabricator task

Otras plantillas útiles

  • {{irc|wikimedia-tech}} - for IRC link
  • {{Key press }} - for, e.g. Ctrl+⇧ Shift+I, and {{Button }} for, e.g. Mostrar previsualización
  • {{ApiEx }} - for api.php request URLs
  • {{Ayuda de la API }} - to transclude generated API documentation
  • {{Wg }} - for global variables
  • {{Tag }} - for a quick way to mention an XML-style tag in a preformatted way

Translations

All pages on mediawiki.org are candidates for translation into multiple languages. MediaWiki.org is a multilingual wiki, it uses the Translate extension to present alternative translations and manage the translation of pages.

  • If a page has been translated, then click 'Edit source' to edit the entire page.
Wrongly placed translation tag markers around section headings can confuse section editing, and as of July 2015 VisualEditor does not understand the following tags: ‎<languages>, ‎<translate>, ‎<tvar>
  • Do not copy and paste existing markup.
If in doubt, focus on writing a good text and let someone else handle the Translate markup.

See also

Notas al pie