Instrucciones de voz y tono

Una amplia variedad de personas, incluidos profesionales de TI y desarrolladores, leen la documentación de .NET para aprender .NET y usarlo en su trabajo diario. Su objetivo es crear documentación de calidad que ayude al lector en su viaje. Nuestras instrucciones sirven de ayuda para eso. En nuestra guía de estilo se incluyen las recomendaciones siguientes:

Uso de un tono de conversación

El siguiente párrafo está escrito con un estilo coloquial. El que le sigue tiene un estilo más académico.

Estilo apropiado

Queremos que nuestra documentación tenga un tono coloquial. Cuando lea cualquiera de nuestros tutoriales o explicaciones, debería tener la sensación de estar hablando con el autor. Como lector, su experiencia debería ser informal, coloquial e informativa. Los lectores deben tener la sensación de estar escuchando cómo el autor les explica los conceptos.

Estilo inapropiado

Se podría ver el contraste entre un estilo coloquial y el que aplica un tratamiento más académico a los temas técnicos. Esos recursos son muy útiles, pero los autores han escrito los artículos en un estilo muy diferente al de nuestra documentación. Cuando se lee una revista científica, se aprecia un tono muy distinto y un estilo de escritura muy diferente. La sensación es estar leyendo una narración árida sobre un tema muy árido.

Escribir en segunda persona

En el párrafo siguiente, se usa la segunda persona. En el que le sigue, se usa la tercera persona. Escriba en segunda persona.

Estilo apropiado

Escriba los artículos como si hablara directamente con el lector. Use la segunda persona con frecuencia (como en estas dos frases). La segunda persona no siempre significa que se use la palabra "tú" (o "usted"). Escriba directamente al lector. Escriba frases imperativas. Dígale al lector lo que quiere que aprenda.

Estilo inapropiado

Un autor también podría optar por escribir en tercera persona. En ese modelo, el autor debe elegir un pronombre o nombre, y usarlo cuando haga referencia al lector. Es posible que para un lector el estilo en tercera persona sea menos atractivo y entretenido de leer.

Uso de la voz activa

Escriba los artículos en voz activa. La voz activa significa que el sujeto de la frase realiza la acción (el verbo) de esa frase. Contrasta con la voz pasiva, en la que la frase se organiza de forma que se actúa sobre el sujeto de la frase. Compare estos dos ejemplos:

El compilador transformó el código fuente en un archivo ejecutable.

El código fuente fue transformado en un archivo ejecutable por el compilador.

La primera frase usa la voz activa. La segunda frase se ha escrito en voz pasiva. En estas dos frases se proporciona otro ejemplo de cada estilo.

Se recomienda la voz activa porque es más legible. La voz pasiva puede ser más difícil de leer.

Escriba para lectores que pueden tener un vocabulario limitado

Los artículos se destinan a un público internacional. Muchos lectores no son hablantes nativos de español, por lo que pueden no tener el mismo nivel de vocabulario que el autor en dicho idioma.

Pero sigue escribiendo para profesionales técnicos. Puede asumir que los lectores tienen conocimientos de programación y el vocabulario específico para los términos de programación. Programación orientada a objetos, Clase y Objeto, Función y Método son términos familiares. Pero no todos los lectores de los artículos tienen una titulación en Informática. Probablemente haya que definir términos como "idempotente", si lo usa, por ejemplo:

El método Close() es idempotente, lo que significa que se puede llamar varias veces y el efecto es el mismo que se si llamara una vez.

Evitar el tiempo futuro

En algunos idiomas, el concepto de tiempo futuro es distinto al del inglés. El uso del tiempo futuro puede dificultar la lectura de los documentos. Además, si se usa, la pregunta evidente es cuándo hacerlo. Por tanto, si dice "Aprender PowerShell será bueno para usted", la pregunta evidente para el lector es cuándo será bueno. En su lugar, diga simplemente "Aprender PowerShell es bueno para usted".

Qué es qué

Siempre que introduzca un concepto nuevo para el lector, defínalo y después explique su utilidad. Es importante que el lector comprenda qué es algo antes de que pueda entender sus ventajas (si las tiene).