Inicio rápido sobre estilo y voz de DocsDocs style and voice quick start

Este inicio rápido es una breve guía para escribir contenido técnico para su publicación en docs.microsoft.com.This quick start is a brief guide to writing technical content for publication on docs.microsoft.com. Estas instrucciones se aplican para crear documentos o actualizar los existentes.These guidelines apply whether you are creating new documentation or updating existing documentation.

Procedimientos recomendados:Best practices:

  • Compruebe la ortografía y la gramática de los artículos, aunque tenga que copiar y pegar el texto en Microsoft Word para hacerlo.Check the spelling and grammar in your articles, even if you have to copy and paste into Microsoft Word to check.
  • Use un tono informal y amable, como si estuviera hablando con otra persona cara a cara.Use a casual and friendly voice—like you're talking to another person one-on-one.
  • Use oraciones sencillas.Use simple sentences. Oraciones fáciles de leer significa que el lector puede usar rápidamente la guía que usted comparte.Easy-to-read sentences mean the reader can quickly use the guidance you share.

Use los principios sobre el tono de MicrosoftUse the Microsoft voice principles

Aspiramos a seguir estos principios cuando escribimos contenido técnico para docs.microsoft.com.We aspire to follow these principles when we write technical content for docs.microsoft.com. No siempre lo conseguimos, pero tenemos que seguir intentándolo.We might not always get there, but we need to keep trying!

  • Céntrese en la intención: los clientes tienen un objetivo específico en mente cuando consultan nuestra documentación.Focus on the intent: Customers have a specific purpose in mind when they consult our documentation. Antes de empezar a escribir, determine con claridad quién es el cliente y qué tarea pretende llevar a cabo.Before you begin writing, clearly determine who the customer is and what task he or she is trying to do. Después, escriba el artículo para ayudar a ese cliente específico a realizar esa tarea concreta.Then, write your article to help that specific customer do that specific task.
  • Use un lenguaje cotidiano: trate de usar un lenguaje natural, es decir, las palabras que utilizan los clientes.Use everyday words: Try to use natural language, the words your customers use. Sea menos formal, pero no menos técnico.Be less formal but not less technical. Proporcione ejemplos que expliquen los nuevos conceptos.Provide examples that explain new concepts.
  • Escriba de forma concisa: no malgaste palabras.Write concisely: Don't waste words. Use oraciones afirmativas y no utilice palabras adicionales ni multitud de calificadores.Be affirmative and don't use extra words or lots of qualifiers. Escriba oraciones cortas y concisas.Keep sentences short and concise. Centre el artículo en el asunto tratado.Keep your article focused. Si una tarea tiene un calificador, colóquelo al principio de la oración o del párrafo.If a task has a qualifier, put it at the beginning of the sentence or paragraph. Además, utilice el menor número de notas posible.Also, keep the number of notes to a minimum. Use una captura de pantalla cuando se pueda ahorrar palabras.Use a screenshot when it can save words.
  • Facilite la lectura en diagonal de los artículos: coloque primero los elementos más importantes.Make your article easy to scan: Put the most important things first. Use secciones para fragmentar procedimientos largos en grupos de pasos que se puedan administrar con más facilidad.Use sections to chunk long procedures into more manageable groups of steps. (Los procedimientos con más de doce pasos posiblemente resulten demasiado largos). Use una captura de pantalla cuando aporte claridad.(Procedures with more than 12 steps are probably too long.) Use a screenshot when it adds clarity.
  • Muestre empatía: use un tono servicial en el artículo y reduzca al mínimo los avisos de exención de responsabilidad.Show empathy: Use a supportive tone in the article, and keep disclaimers to a minimum. Destaque con franqueza las áreas que causarán frustración a los clientes.Honestly call out areas that will be frustrating to customers. Asegúrese de que el artículo se centra en lo que importa al cliente, no se limite exclusivamente a una presentación técnica.Make sure the article focuses on what matters to customers; don't just give a technical lecture.

Consideraciones sobre localización y traducción automáticaConsider localization and machine translation

Los artículos técnicos están traducidos en varios idiomas, y algunos se modifican para mercados o regiones geográficas concretos.Our technical articles are translated into several languages, and some are modified for particular markets or geographies. Los usuarios pueden recurrir también a la traducción automática en la Web para leer los artículos técnicos.People might also use machine translation on the web to read the technical articles. Por tanto, debe tener en cuenta las siguientes pautas cuando escriba:So, keep the following guidelines in mind when you're writing:

  • Asegúrese de que el artículo no contiene errores de gramática, ortografía o puntuación: se trata de un procedimiento que se debería aplicar por norma general.Make sure the article contains no grammar, spelling, or punctuation errors: This is something we should do in general. Algunos editores Markdown, como Markdown Pad 2.0, incorporan un corrector ortográfico básico, pero es conveniente pegar el contenido HTML representado del artículo en Word, ya que este procesador incorpora un corrector ortográfico y gramatical más eficaz.Some Markdown editors (such as MarkdownPad 2.0) have a basic spell checker, but it's a good practice to paste the rendered HTML content from the article into Word, which has a more robust spell and grammar checker.
  • Escriba oraciones lo más cortas posibles: las oraciones compuestas o las cadenas de cláusulas dificultan la traducción.Make your sentences as short as possible: Compound sentences or chains of clauses make translation difficult. Divida las oraciones si es posible, sin que sean demasiado redundantes o de tal forma que no suenen raras.Split up sentences if you can do it without being too redundant or sounding weird. No queremos artículos escritos en un lenguaje que no sea natural.We don't want articles written in unnatural language either.
  • Use construcciones gramaticales sencillas y coherentes: la coherencia es mejor para la traducción.Use simple and consistent sentence construction: Consistency is better for translation. Evite los paréntesis y las acotaciones y coloque el sujeto lo más cerca posible del principio de la oración.Avoid parentheticals and asides, and have the subject as near the beginning of the sentence as possible. Consulte algunos artículos publicados.Check out a few published articles. Si algún tema tiene un estilo agradable y fácil de leer, úselo como modelo.If an article has a friendly, easy-to-read style, use it as a model.
  • Use una redacción y las mayúsculas y minúsculas de forma coherente: una vez más, la coherencia es la clave.Use consistent wording and capitalization: Again, consistency is key. No escriba con inicial mayúscula una palabra si no está al principio de una oración o si no se trata de un nombre propio.Do not capitalize a word if it isn't at the start of a sentence or it isn't a proper noun.
  • Incluya las "palabras cortas" : las palabras que se consideran cortas y sin importancia en español porque se entienden por el contexto (como "un", "la", "esa" y "es") son fundamentales para la traducción automática.Include the "small words": Words that we consider small and unimportant in English because they are understood for context (such as "a," "the," "that," and "is") are crucial for machine translation. Por esta razón, debe asegurarse de incluirlas.Be sure to include them.

Otras cuestiones que hay que tener en cuenta sobre el estilo y el tonoOther style and voice issues to watch for

  • No interrumpa pasos con comentarios o acotaciones.Don't break up steps with commentary or asides.
  • Para los pasos que incluyen fragmentos de código, inserte información adicional sobre el paso en el código como comentario.For steps that include code snippets, put additional information about the step into the code as comments. De esta forma, se reduce la cantidad de texto que hay que leer.This reduces the amount of text that people have to read through. La información clave se copia en el proyecto de código para recordar a los lectores lo que hace el código cuando hacen referencia a él más adelante.The key information gets copied into the code project to remind people of what the code is doing when they refer to it later.
  • Escriba todos los títulos y los encabezados con la primera letra en mayúscula.Use sentence case for all titles and headings.
  • Use "iniciar sesión" en lugar de "registrarse".Use "sign in" and not "log in."
  • Para obtener más instrucciones, vea la Guía de estilo de escritura de Microsoft.For more guidelines, see the Microsoft Writing Style Guide.

Documentación localizadaLocalized documentation