Toss publica su guía de technical writing

Principios clave para escribir buena documentación técnica

1. Definir el tipo de documento

Según el propósito del documento, cambia la forma más efectiva de escribirlo

• Documento centrado en el aprendizaje: cuando se conoce por primera vez una nueva tecnología o herramienta, con el objetivo de entender el flujo general
• Documento de resolución de problemas: cuando ya hay conocimientos previos, con el objetivo de resolver un problema específico
• Documento de referencia: cuando ya se sabe cómo usarlo, pero se quiere verificar una función específica o cómo usar una API
• Documento explicativo: con el objetivo de comprender en detalle conceptos, principios y conocimientos de contexto

2. Crear una estructura de información

Entender conocimientos nuevos requiere esfuerzo, pero estructurar la información puede reducir ese esfuerzo

• Tratar solo un tema por página
• Ofrecer valor primero
• Escribir títulos efectivos
• No omitir el resumen general
• Hacerlo predecible

3. Pulir las oraciones

Si se mejora la claridad de las oraciones, al lector le resulta más fácil entender el contenido. Si los detalles se expresan con oraciones difíciles de comprender, la capacidad de transmitir el mensaje disminuye mucho

• Dejar claro el sujeto de la oración
• Conservar solo la información necesaria
• Escribir de forma concreta
• Usar expresiones naturales
• Escribir con consistencia

[tested]

¿No hay algún lugar donde estén reunidos sitios como estos que hizo Toss?

[dontdieych]

Me cuesta adaptarme al estilo con "yo".

[gera1d]

Tiene razón.

[winterjung]

Está bueno. En especial, la parte sobre pulir las oraciones me dan ganas de probar crear algo con GPTs usando few-shot.

[mathgig]

Creo que este tipo de textos son buenos. En la era de los LLM, ¿cómo podrían transformarse estas guías?

[bluejoyq]

Es un proyecto excelente ^^