Cómo mejorar mis habilidades de escritura técnica

Solución al problema 1:
Conoce a tu audiencia. ¿Quién va a usar esta documentación? ¿Por qué lo están usando? ¿Qué necesitan saber y con qué detalle? Solo escriba lo que necesita saber para lo que quiere hacer. No les importa nada más, incluso si tú lo haces. No se interponga en su camino siendo demasiado detallado. Además, no dejes que lo perfecto sea enemigo de lo bueno. Si su documento hizo su trabajo para el 95% de su audiencia, entonces es un éxito.

Puede escribir algo que explique todo sobre su tema en perfecto detalle, hasta el último caso de la esquina. Para ti es perfecto. Sin embargo, si nadie lo lee precisamente porque es demasiado detallado para usar, el documento es un error. No ayudaste a nadie. Recuerda que estás escribiendo para ellos, no para ti.

Solución al problema 2:
Esto está relacionado con el problema 1. Cada oración tiene un propósito. No debería necesitar una declaración entre paréntesis si está haciendo su trabajo. Si tiene demasiadas comas, mire la oración y vea si puede dividirse en varias oraciones. Puede estar tratando de hacer muchas cosas en una sola oración. Cada oración debe tener un solo propósito.

Si no está seguro del uso de su coma, puede buscar las reglas de coma en línea para asegurarse de que las esté utilizando correctamente.

Practicando la autoedición

1. Escribe una descripción o explicación de algo.
2. Determine el recuento de palabras de la pieza.
3. Vuelva a escribir la pieza para que use la mitad de la cantidad de palabras que el original.
4. Continúe los pasos 2 y 3 hasta que la pieza ya no tenga sentido.

Este ejercicio le ayuda a editarse para eliminar información extraña. Hacer este ejercicio regularmente establecerá el hábito de escribir de manera concisa.

Escribe dos versiones.

Versión 1: Imagine que su usuario es un niño, tres pisos debajo de usted, desarmando una bomba nuclear temporizada. Explique exactamente lo que el usuario tiene que hacer, en el mínimo tiempo posible, para obtener el resultado deseado.

1. Use puntos, no comas.

2. Use listas de verificación y números tanto como pueda.

3. Nada es demasiado simple.

4. Evitar /. ¿Lunes / martes significa “lunes y martes” o “lunes o martes”? No hay forma de saberlo. Entonces no lo hagas.

Versión 2: una versión que contiene todo lo que crees que es necesario.

Esta versión larga, está disponible como un pequeño enlace URL al final de la versión corta.

Use un contador de algún tipo para ver cuántos usuarios realmente usan el enlace. Si te preocupa, usa el contador para ver cuántos lo usa.

– Si el número siempre es cero, felicidades, puede seguir con la versión número uno a partir de ese momento.

– Si es más que cero, felicidades, tu aburrida versión larga valió la pena.

Entiendo tu problema. Yo también lo tengo, pero probablemente no severamente.
Para tomar su ejemplo de hablar sobre puntos de código inválidos en utf8, parece que sabe que es excesivo, pero siente que es necesario ayudar al lector a manejar todos los casos. Intenta recordar el propósito de tu texto: ayudar a las personas. Si no ayuda porque nubla el mensaje, entonces no ayuda, punto. Cuando edito texto, leo una parte y me digo “¿Eso realmente ayuda?” Si no, lo elimino o lo muevo.

Para moverlo, inserte una declaración breve como “Para problemas de puntos de código utf8, consulte la nota a continuación”. y mueva los detalles a un apéndice, subsección o donde sea apropiado. Esto le da al lector la opción de profundizar en los detalles (el lector siempre sabe mejor que usted si necesita detalles), aclara el texto y le asegura que no ha olvidado nada.

La redacción técnica tiene 3 componentes: contenido, estructura y formato. Ya eres bueno en el contenido. Encuentre mejores formas de estructurar su texto para facilitar el acceso al contenido. No hay tiempo para discutir el formato aquí.

Una cosa más, trata de conocer a tu audiencia. No le explicaría a un programador la diferencia entre int y string, así que asegúrese de no agregar información a la que ya deberían tener acceso.
Espero que esto ayude.

Considera a tu audiencia. ¿Quién leerá esta documentación, este correo electrónico?

El personal junior necesita información accesible para manejar los problemas de rutina. No podrán usar todo lo que alguna vez supiste. Si pudieran, estarían haciendo el trabajo, no tú.

Los expertos y compañeros ya saben al menos tanto como usted. Si desea dejar un recordatorio sobre una peculiaridad potencial que pueden encontrar en ciertos escenarios, refiéralos a un apéndice o manual técnico donde proporcione ejemplos y soluciones.

Su jefe necesita una vista de 50,000 pies de lo que está haciendo, cuándo terminará, una breve descripción de cualquier problema, cuándo se resolverán, si necesita más recursos y quién / qué cree que debería ser . “Si necesita más detalles, avíseme si deberíamos hablar o si quiere que lo escriba”.

Use un formato de esquema con viñetas o elementos numerados. Siempre puedes editar eso en texto en prosa una vez que hayas establecido lo que hay que decir.

Menos es más. La documentación ha de ser útil para el usuario. No es tu tesis o disertación. La moderación y la elegancia es lo que busca, adaptado a la audiencia.

Con la escritura, algo así como en la codificación, escribir las palabras es la parte fácil. La parte difícil es saber qué decir.

Por ejemplo, si encuentra la necesidad de muchos comentarios entre paréntesis, retroceda y reconsidere el mensaje que está tratando de comunicar. ¿Puedes estructurarlo de una manera que no necesite paréntesis?

Si eres prolijo, puede deberse a que no has pensado en el punto que quieres destacar, por lo que intentas un enfoque de escopeta con la esperanza de que algunas de las palabras lleguen al objetivo. Si es así, deténgase y reconsidere el objetivo. ¿Qué necesita saber realmente el lector? Si todavía siente que necesita escribir todo (y podría hacerlo), solicite la información para el lector que no lo hace para que pueda encontrar lo que necesita fácilmente.

Sobre todo, comience a escribir y editar. Lo que usted describe no es nada que alguna práctica no pueda ayudar.

Me gusta leer contenido detallado, poder cubrir todos los casos posibles, no importa cuán improbable sea, es una habilidad que me encantaría tener. En su caso, podría tener dos tipos de documentos, uno podría ser una versión menos detallada que consista en los escenarios más frecuentes, mientras que el otro puede tener todos los casos límite posibles que se le ocurran. ¡Solo conecte estos dos documentos entre sí y listo!

En cuanto a la puntuación, realmente no lo sé, a veces termino usando más comas de las que puedo contar. Supongo que ese bit requiere que aprendas más sobre la puntuación, etc.

No necesitas tutoriales ni clases ni nada de eso. Simplemente se despiadado con tu escritura. Obtenga el punto principal por adelantado y temprano . Eso casi siempre corta las cosas extrañas. Si quieren saber más, probablemente preguntarán. Los requisitos de documentación técnica pueden ser inevitables, pero limítese inicialmente a un máximo de 100 palabras (hasta que sea imposible). Y no, no está utilizando demasiados corchetes (son muy útiles para la comprensión y la legibilidad), pero las comas necesitan un poco de recorte. [85 palabras]

¡Lea sobre habilidades técnicas de escritura en mi blog!

Una técnica que comencé a usar es hacer la mayor parte de mi escritura en Atom con el linter para la biblioteca de escritura buena.

btford / write-good

Llama a cosas como la voz pasiva y las palabras que debilitan el significado y parece ayudarme a estructurar mis pensamientos.

La mejor manera es echar un vistazo a la fuente en cualquier lugar de Internet sobre cómo escribir oficialmente. Hay toneladas de uso común de latón que puedes usar. Así que intenta