Merge pull request #2344 from mercadopago/feature/style-guide-english

Criação dos arquivos em inglês do style guide

guides/additional-content/style-guide/abbreviations.en.md

@@ -0,0 +1,20 @@
+# Uso de abreviaciones
+
+Intentamos no usar abreviaciones para evitar posibles confusiones, salvo en los siguientes casos:
+
+* **Medidas** (GB, px., etc.)
+* **Monedas**
+    - MXN (Peso mexicano)
+    - CLP (Peso Chileno)
+    - ARS (Peso Argentino)
+    - BRL (Real Brasilero)
+    - PEN (Sol Peruano)
+    - COP (Peso Colombiano)
+    - UYU (Peso Uruguayo)
+    - VES (Bolivar Venezolano)
+    - USD (dólar estadounidense)
+
+* **Números**: priorizamos el uso de números (1, 2, 3) y no de sus transcripciones.
+* **Siglas/acrónimos extendidos**: SDK, js (javascript), App, API, JSON, YAML.
+* **Para el portugués**: las cuotas/mensualidades pueden ser señaladas como “x” (*parcelamento em até 12x*).
+

guides/additional-content/style-guide/bold-and-italics.en.md

@@ -0,0 +1,26 @@
+# Negritas y cursivas 
+
+Las **negritas** sirven para **resaltar una idea central** y deben poder leerse fuera de contexto. Procura usarlas poco y nunca en links ni botones.
+
+Adicionalmente, hacemos ciertos usos especiales de negritas:
+
+* Menciones de secciones dentro de una lista de pasos *(Accede a **Mis Apps>Configuración**)*.
+* Menciones de botones a ser activados dentro de una configuración *(Haz clic en **Guardar**)*. Además, estos botones deben ser escritos tal como se muestran en la pantalla.
+
+Las ***cursivas*** sirven para denotar que una palabra está siendo usada en un sentido especial. Si bien es preferible evitar palabras en lenguas que no sean las que estamos utilizando para documentar, solemos usar las cursivas cuando mencionamos un término en una lengua extranjera (“En el *header*, puedes incluir…”). Es aconsejable, igualmente, privilegiar siempre expresiones equivalentes en el idioma que corresponda a la documentación. 
+
+#### Tip
+
+En tecnología se utilizan muchos términos en inglés como parte del estándar. Es por esto que en algunos casos es preferible mencionar una palabra en inglés en medio de un texto de otro idioma, ya que así es como la gran mayoría de los lectores la reconocerán. Si quieres reemplazar algún término, puedes preguntar al equipo de DX para saber si es comúnmente utilizado.
+
+#### Recomendación
+
+No utilices más de un modo de resaltar o llamar la atención sobre un fragmento de texto. Si utilizas negritas, no uses cursivas o comillas. Excepcionalmente, puedes combinar negritas y cursivas cuando el nombre de una función o botón no sean traducibles.
+
+> WARNING
+>
+> Atención
+>
+> No utilizamos **subrayado** como elemento textual porque su uso no va en consonancia con las buenas prácticas para textos accesibles. Debemos considerar a quienes acceden al DevSite utilizando herramientas de lectura de pantalla, o incluso a personas con dificultades en la lectura.
+
+

guides/additional-content/style-guide/bullets.en.md

@@ -0,0 +1,15 @@
+# Bullets
+
+Los **bullets** son una lista punteada de diferentes elementos. Utiliza bullets para hacer listas que ayuden a leer más rápido la información. Un listado provoca menos esfuerzo cognitivo que un párrafo de texto. 
+
+✅ *Lee las siguientes documentaciones de cada producto para saber cómo incluir el Integrator ID en tus integraciones:*
+
+* *Checkout Pro*
+* *Integración de WooCommerce*
+* *Adobe Commerce (Magento)*
+* *Configuración de WooCommerce*
+
+❌ *Lee las documentaciones de Checkout Pro, Integración y Configuración de Woocommerce, y Adobe Commerce (Magento) para saber cómo incluir el Integrator ID en tus integraciones.*
+
+Usamos bullets cuando hay al menos dos opciones y menos de cinco. Las frases siempre empiezan con mayúsculas y terminan con punto (salvo que sean ítems de una o dos palabras, o números sueltos).
+

guides/additional-content/style-guide/clickstream.en.md

@@ -0,0 +1,8 @@
+# Secuencias de clics
+
+Siempre que haya una secuencia de clicks en menús, describe los pasos separados por **>**. No es necesario utilizar cursiva en estos casos.
+
+✅ *Para enviar mensajes, accede a Productos > Zenvia Message > Canales > WhatsApp.* <br>
+
+❌ *Para enviar mensajes, accede a Productos - Zenvia Message / Canales --> WhatsApp.*
+

guides/additional-content/style-guide/documentation-scannability.en.md

@@ -0,0 +1,9 @@
+# Escaneabilidad de la documentación
+
+La escaneabilidad ayuda a recorrer visualmente la pantalla y entender las diferentes secciones e instancias de la misma. Estos son los elementos que se utilizan en las documentaciones técnicas y que puedes aprovechar para generar distintos niveles de lectura:
+
+* [Títulos, subtítulos y textos explicativos](/developers/pt/docs/style-guide/documentation-scannability/titles)
+* [Enumeraciones](/developers/pt/docs/style-guide/documentation-scannability/enumerations)
+* [Secuencias de clics](/developers/pt/docs/style-guide/documentation-scannability/clickstream)
+* [Highlights](/developers/pt/docs/style-guide/documentation-scannability/highlights)
+

guides/additional-content/style-guide/enumerations.en.md

@@ -0,0 +1,12 @@
+# Enumeraciones
+
+Usamos enumeraciones exclusivamente en los paso a paso que se quieran indicar, ya que nos permitirán ordenarlos lógicamente. Al igual que las listas, las incorporamos cuando hay al menos dos pasos y menos de cinco. 
+
+Si hubiera más, evaluamos la posibilidad de quebrar ese proceso en más partes que nos permitan reiniciar la enumeración (incorporando subtítulos, nuevos apartados de menú,  etc.). Para evitar esto, también se puede aprovechar la inclusión de secuencias de clicks (ver abajo).
+
+> WARNING
+>
+> Importante
+>
+> En listas y enumeraciones, mismo dentro de un párrafo, evitamos usar “etc.” para señalar la diversidad de elementos. Para esto, puede servir usar “tales como…”,  “incluyendo…”, o “entre otros” (*El producto soporta todos los medios de pago, **incluyendo** tarjetas de débito y crédito*).
+

guides/additional-content/style-guide/guide-stucture.en.md

@@ -0,0 +1,37 @@
+# Estructura de las guías
+
+Nuestras guías independientes se estructuran de acuerdo a las siguientes secciones:
+
+## Landing
+
+Introducción que lleva un patrón específico. Sirve para presentar el producto/plataforma. Es el único archivo que no se realiza en Markdown.
+
+## Introducción
+
+Breve descripción de la herramienta o plugin a documentar. Es una buena práctica enumerar y vincular los pasos de integración aquí, indicando cuándo uno o más son opcionales pero recomendados.
+
+## Requisitos previos: 
+
+Lista de cosas que deben estar listas para comenzar la integración. Por lo general, se presentan como una tabla que contiene 3 columnas (requisito, descripción, especificaciones).
+
+## Pasos de integración
+
+Esta sección de la documentación generalmente comprende más de una entrada de menú y presenta los pasos que se deben seguir, de principio a fin, para realizar una integración. Es una buena práctica aquí usar descripciones de acción claras para cada título de paso.
+
+> En los casos en que distintas etapas de una integración compartan pasos idénticos y se encuentren en apartados de menú diferentes, es necesario que cada una cuente con la enumeración de esos pasos. Esto se debe a que el público puede haber ingresado a esa sección en específico, por lo que siempre debemos incluir la información completa de cómo realizar la acción que estamos documentando.
+
+## Flujo de prueba
+
+Si hay un flujo de prueba, debe incluirse aquí. Si se incluye este elemento, también debes crear una entrada de menú que explique cómo pasar a producción después de que se complete el flujo de prueba.
+
+## Solución de problemas
+
+Si hay problemas comunes que los desarrolladores pueden encontrar y que las partes interesadas han identificado, es una buena práctica incluirlos aquí. Separa esto del flujo de integración en el menú con una línea, y asegúrate de incluir solo la solución de problemas para la integración (no para el producto con el que se está integrando).
+
+## Preguntas frecuentes
+
+La mayoría de las documentaciones no requieren esta sección, pero sus partes interesadas pueden solicitarla. Si este es el caso, asegúrate de que las preguntas frecuentes solo contengan información que no se pueda incluir en ninguna otra sección de la documentación. De lo contrario, simplemente inclúyela en la sección correspondiente. Deben estar separadas del flujo normal de integración.
+
+## Contenido adicional
+
+Se puede solicitar que se incluya otra información que, si bien es importante, no forma parte del flujo de integración. Puedes agregar esta información, pero mantenla separada con una línea del flujo de integración, para evitar confundir a tus lectores. El nombre "contenido adicional" se entiende como un ejemplo. Deberás pensar en un nombre apropiado para cada sección que agregues como otra información.

guides/additional-content/style-guide/highlights.en.md

@@ -0,0 +1,7 @@
+# Highlights
+
+Los **highlights** son textos destacados. Usa highlights para destacar palabras claves u oraciones importantes que sumen valor y permitir que la pantalla sea más fácil de escanear.
+
+✅ *Para **mobile**, elige pasos cortos que enfoquen la atención y sean fáciles de recorrer. En cambio, para **desktop**, puedes utilizar experiencias one step ya que el usuario tiene un control más extenso sobre sus acciones y es más fácil encontrar lo que busca.*
+
+

guides/additional-content/style-guide/images.en.md

@@ -0,0 +1,17 @@
+# Imágenes
+
+A excepción de las Landings, que tienen imágenes ilustrativas, las imágenes en las guías nos sirven para mostrar gráficamente los procesos que documentamos. Debemos tener en cuenta:
+
+* Que sean imágenes que complementen la información del texto. No están ahí para reemplazarlo, sino para brindar una experiencia visual y aportar mayor claridad.
+* No incluir imágenes que tengan información que no es mencionada en el texto. 
+* Siempre que sea posible, incluye una breve descripción de las imágenes utilizando el texto alternativo. Este se utiliza para proporcionar información relevante sobre una imagen, y se inserta en markdown de la siguiente manera: 
+
+```markdown
+![texto alternativo](path de la imagen dentro del repositorio) 
+```
+### Casos especiales
+* Si la imagen es meramente decorativa, no es necesario incluir el texto alternativo.
+* En los botones, la descripción debe referirse a la acción que se ejecutará.
+* No utilices imágenes de tablas, ya que los lectores de pantalla no pueden escanear el contenido.
+* No uses imágenes que contengan información sensible y, de ser posible, tómalas desde usuarios de test.
+

guides/additional-content/style-guide/landing.en.md

@@ -0,0 +1,11 @@
+# Guía de estilo y escritura
+
+El sitio de desarrolladores (DevSite) es el canal en el que se disponibilizan las documentaciones técnicas de los productos ofrecidos por Mercado Pago. Permite a los equipos técnicos editar y modificar toda la información necesaria para integrar estos productos, y es gestionado por el equipo de Developer Experience (DX) de Mercado Pago.
+
+---
+bullet_section_with_media: 
+ - title:
+ - type: normal
+ - message: El objetivo de esta guía es comunicar el estilo de documentación del DevSite para que todas los productos estén alineados en estructura y carga de contenidos técnicos. Esperamos que forme parte del armado de documentación técnica para las áreas y su posterior publicación en el sitio.
+ - image: /style-guide/melina-landing.png
+---

guides/additional-content/style-guide/links.en.md

@@ -0,0 +1,20 @@
+# Enlaces (links)
+
+Es muy importante que el texto que utilicemos para los enlaces describa a dónde irán las personas si hacen clic en ese enlace. Esto facilita la navegación para las personas con discapacidad visual.
+
+La mayoría de los lectores de pantalla generalmente reconocen que algo es un enlace debido a la estructura del HTML. Esto significa que lo leerán en voz alta para los usuarios de lectores de pantalla, indicando "Enlace:" antes de leer el texto real del enlace que has escrito.
+
+Todos los enlaces deben poder funcionar de forma independiente y transmitir su función y propósito sin el contexto del texto circundante. Por eso, "Haz clic aquí" o "más" son ejemplos de texto de enlace ineficiente y desorientador.
+
+✅ *Para más información, lee [la documentación de Checkout API](/developers/es/docs/style-guiles/link).* <br>
+✅ *Sigue los pasos descritos en la [documentación de OAuth](/developers/es/docs/style-guiles/link) para obtener cada access token.*
+
+❌ *Para más información, haz [clic aquí](/developers/es/docs/style-guiles/link).*
+
+A su vez, cuando definimos los paths que tendrán las documentaciones dentro del Devsite, lo hacemos en inglés. Debemos cuidar estar respetando el camino que recorre el usuario para llegar a esa documentación, y también que la referencia al contenido de la página sea clara.
+
+✅ */guides/checkout-api/integration-configuration/integration-via-cardform* <br>
+❌ */guides/checkout-api/cards*
+
+
+

guides/additional-content/style-guide/menu-style.en.md

@@ -0,0 +1,14 @@
+# Estilo en menú
+
+Nuestros menúes se estructuran por niveles. En el **nivel 0**, tenemos los títulos principales de cada sección. Estos deberán corresponderse con el título principal nominalizado que usaremos como encabezado de cada documentación. 
+
+Para los **subniveles**, como ya mencionamos el verbo en el nivel 0, no será necesario volver a incluirlo. 
+
+![ejemplo-menu](/images/style-guide/ejemplo-menu-es.png)
+
+> WARNING
+>
+> Atención
+>
+> Debemos prestar particular atención a las **descripciones** de cada apartado de menú. Como esa descripción orienta al usuario respecto al contenido con el que se encontrará, partiremos de un **verbo conjugado en imperativo** y buscaremos describir la sección en cuestión, siempre siendo concisos y breves (*Aprende a configurar los medios de pago*).
+

guides/additional-content/style-guide/notes.en.md

@@ -0,0 +1,35 @@
+# Notas
+En nuestra documentación podemos incluir tres tipos de notas:
+
+1. **Nota simple:** Sirve para sumar un tip o recomendación que se quiera destacar en un nivel levemente superior a la documentación. 
+
+![nota-simple](/images/style-guide/nota-simple.png)
+
+```markdown
+> Esto es un ejemplo de nota.
+```
+
+2. **Nota de aclaración**: Sirve para brindar aclaraciones sobre algún paso del proceso que estamos documentando. Pueden incluirse para redirigir al lector a algún otro paso o documentación, brindar una vía de contacto para resolución de problemas, mencionar alternativas que puedan ser útiles en esa parte del proceso, entre otros.
+
+![nota-de-aclaracion](/images/style-guide/nota-aclaracion.png)
+
+```markdown
+> NOTE
+>
+> Título
+>
+> Cuerpo de la nota.
+```
+
+3. **Nota de prevención:** Sirve para llamar la atención del lector en algún paso del proceso. Puede incluirse para señalar la necesidad de cumplir con algún paso previo, mencionar limitaciones que pudieran surgir, indicar un deprecado de versiones/medio de pago, entre otros.
+
+![nota-de-prevencion](/images/style-guide/warning-note.png)
+
+```markdown
+> WARNING
+>
+> Título
+>
+> Cuerpo de la nota.
+```
+

guides/additional-content/style-guide/paragraphs-sentences-titles.en.md

@@ -0,0 +1,19 @@
+# Párrafos, oraciones y titulación
+
+La documentación técnica debe ser precisa, clara y concisa. Es por esto que priorizamos la escritura de **oraciones simples y breves**. Una buena práctica cuando nos enfrentamos a oraciones complejas es intentar separarlas en dos distintas.
+
+✅ *La integración no es compleja. Puede ser hecha de dos maneras distintas* <br>
+❌ *La integración, que puede ser hecha de dos maneras distintas, no es compleja*
+
+Los **párrafos** también deben ser breves, preferentemente de no más de 5 oraciones simples. Cuanto más largos sean, más complejo se vuelve para el lector ubicar la información necesaria y concentrarse en lo específico.
+
+En el caso de los **títulos**, como se explicó previamente, deben reflejar el contenido de cada sección de manera concisa y sencilla. Para aquellas secciones que involucren pasos para integración o configuración, es preferible usar verbos nominalizados (**Configuración** *de integración*).
+
+Para los subtítulos dentro de una sección con título nominalizado, privilegiamos los verbos en infinitivo (**Crear** *preferencias*, **Enviar** *un pago*).
+
+> WARNING
+> 
+> Atención
+>
+> Para las documentaciones “How to”, siempre debemos comenzar la titulación  con el interrogativo “cómo” (*Cómo mejorar la aprobación de pagos, Cómo medir la calidad de la integración*).
+

guides/additional-content/style-guide/passive-active-voice.en.md

@@ -0,0 +1,17 @@
+# Voz activa y voz pasiva
+
+Recomendamos utilizar la voz activa siempre que sea posible, ya que el mensaje se vuelve más directo y requiere de menos palabras.
+
+✅ *Configura tu integración* <br>
+❌ *La integración es configurada*
+
+
+Cuando sea necesario evitar poner el foco en el agente que realiza la acción, evalúa la posibilidad de usar una construcción sustantiva, utilizando **sustantivo+adjetivo**, y no sustantivo+verbo auxiliar+verbo principal en participio. 
+
+✅ *Pago rechazado* <br>
+❌ *Tu pago fue rechazado*
+
+Otra opción, en español, es el uso de construcciones impersonales, que nos permiten elidir el agente de la acción reemplazándolo con un “se” impersonal. 
+
+✅ *Se rechazó el pago* - se muestra un mensaje de alerta. <br>
+❌ *El pago fue rechazado* - Un mensaje de alerta será mostrado.

guides/additional-content/style-guide/pronouns.en.md

@@ -0,0 +1,31 @@
+# Pronombres y lenguaje no sexista
+
+### Para hablar de Mercado Pago
+Cuando hablamos con nuestro público, usamos preferentemente la 1era persona del plural (nosotros) para crear proximidad con el usuario.  También consideramos el uso de “a gente” (en portugués) en contextos con mayor apertura para el tono conversacional (un ejemplo de este uso puede ser la redacción de noticias para la página de novedades).
+
+### Para referirse a los usuarios
+
+Para evitar perpetuar estereotipos de género, procuramos usar voces y nombres neutros.
+Evita siempre usar el universal masculino. Para ello, elige opciones dentro de la lengua española que incluyan a todos los géneros y no alteren la lengua. Para eso puedes usar distintos recursos de escritura inclusiva: 
+
+- **Privilegiar el uso de pronombres personales en segunda persona**, por sobre expresiones o sustantivos con marcación de género. <br>
+
+✅ *Si estás desarrollando esta feature...* <br>
+❌ *Si eres desarrollador...*
+
+- **Paráfrasis**: se trata de decir lo mismo, pero parafraseando la idea original. <br>
+
+✅ **Las personas que desarrollan** *- Quienes realicen compras/quienes accedan a la tienda* <br>
+❌ **Los desarrolladores**  *- Los clientes*
+
+- **Usar sustantivos colectivos sin marca de género**. <br>
+
+✅ *El equipo de Mercado Pago.* <br>
+❌ *Los integrantes de Mercado Pago.*
+
+> WARNING
+>
+> Importante
+>
+> Presta atención a que, aunque nuestro público principal es de devs, también hay sellers que acceden a nuestra documentación. Por esto, evita usar posesivos a la hora de hablar, por ejemplo, de las tiendas  (tu tienda —> **la** tienda). Sí puedes usarlos cuando hables de integraciones.
+

guides/additional-content/style-guide/punctuation.en.md

@@ -0,0 +1,20 @@
+# Uso de puntuación
+
+Respetamos el uso normativo de los signos de puntuación. Algunas consideraciones especiales son:
+
+* **No** utilizamos comas al finalizar listas si estas están compuestas por pocas palabras, oraciones simples, o números. En cambio, si están compuestas por varias oraciones, utilizamos un punto aparte al finalizar cada bullet. 
+
+✅ **Puedes integrar de dos formas: <br> • Manual,<br> • Automática.** <br> <br>
+❌ Puedes integrar de dos formas <br> • Manual. <br> • Automática.
+
+* Preferentemente, **evitamos el uso de paréntesis**. 
+    * Si los usas, que sea para esclarecer información breve y de baja prioridad.
+    * Si un paréntesis es largo, resulta difícil de leer. En ese caso, reformula la frase o coloca la aclaración en un párrafo aparte. Si la información es importante, no la coloques entre paréntesis. En su lugar, puedes usar comas o redactar otra oración. 
+    * Sin embargo, **sí** utilizamos paréntesis en casos en los que sea necesario aclarar una abreviatura, como en el siguiente ejemplo: *Mercado Pago permite integrarse con STP (Sistema de Transferencias de Pago)*.
+<br>
+
+* Los títulos no deben llevar punto final.
+<br>
+
+* Como nuestro registro es instruccional, evitamos el uso de signos exclamativos para que nuestros textos no parezcan órdenes. Los signos de interrogación, por su parte, son bienvenidos en títulos y subtítulos de How-tos y documentación *problem solving*, ya que nos permiten presentar en el texto las preguntas que se hace el lector, y dar respuesta.
+