wordreference traduccion software example español documentation

documentation - traduccion - Documento técnico blanco: Cómo escribir uno



python documentation español (6)

Gente,

¿Cuál es la mejor manera de investigar y presentar para un documento técnico? No me refiero al formato, visión general, secciones y cosas por el estilo.

Nunca he escrito uno, y me pregunto si un libro blanco debe ser muy muy genérico (conceptual) o específico (por ejemplo, favoreciendo una herramienta / metodología particular)

Y si su respuesta favorece el enfoque genérico, me gustaría saber cómo se puede investigar para eso. ¿Es mejor enfocarse en un escenario de caso de uso más pequeño, comenzar de a poco, usar una herramienta / método particular, obtener una buena comprensión y luego investigar más y desarrollar una visión de gran angular sobre el tema?

El objetivo de un libro blanco suele ser abogar por un punto de vista particular o proponer una solución específica a un problema.

Sin embargo, si su libro blanco se presenta como poco más que marketing o un argumento de venta, no habrá presentado un buen caso. El consejo convencional es que debe comenzar articulando una necesidad que su audiencia tiene (el "punto de dolor" en bizspeak) y abordar su solución a esa necesidad.

Esto suena un poco inútil, pero los libros blancos tienen todas las formas, desde muy específicos hasta muy generales. Determine cuál es el objetivo final. ¿Estás tratando de vender algo, o describir cómo funciona un nuevo widget técnico, o describir una experiencia? Además, determine su público: ¿son comerciales, técnicos, domésticos, etc.?

Eche un vistazo a ejemplos: la mayoría de las grandes empresas (IBM, etc.) tienen cientos en su sitio web. Lea algunos y vea lo que le llama puntos buenos y malos.

Mi 0.02:

Lee un par y trata de hacer mapas mentales tratando de tener una idea de cómo se ven.

Después de hacer este análisis, retroceda y elija las secciones que su documento técnico va a necesitar. En particular, construya OTRO mapa mental con la estructura de su documento.

Los datos también son una forma importante de transmitir información. Por lo tanto, piense un momento sobre las técnicas de visualización de datos antes de trazar sus datos.

Un documento técnico puede ser general o muy específico. Depende completamente del sujeto, la audiencia y la intención.

Por ejemplo, un artículo sobre un tema de I + D, o presentado dentro de la academia, o diseñado para proporcionar un bosquejo conceptual de algún trabajo futuro va a escribirse en una voz más pasiva, casi en formato Q + A. Una discusión. Probablemente presente múltiples ideas y pueda pro / con ellos sin llegar necesariamente a una conclusión fija.

Un documento técnico sobre una tecnología en particular, para beneficio de los clientes de aclaración, o para ilustrar o documentar algún resultado será muy firme, fijo y tendrá conclusiones definitivas. Números.

Lo único que puede decir en general es que el proceso funciona desde el vago -> específico.

Sí, intenta leer otros documentos técnicos. Pero no solo lea cualquier libro blanco. Lee los mejores Por lo general, se puede determinar cuál es el "mejor" al verificar cuántas veces se ha citado el documento (Un sitio web al que voy es cite seer y google scholar). Algunas pautas generales serían:

  1. Trate de ir directo al grano, no ande por las ramas.
  2. Usa tus siglas de forma consistente.
  3. Aproveche la oportunidad para expresar las debilidades de los métodos anteriores, ya que muestra que se ha esforzado por revisar / estudiar los métodos de los demás.
  4. Un documento técnico debe ser muy específico. Indique exactamente cómo funciona su método, establezca exactamente cómo realiza los experimentos (para que otros puedan replicar sus experimentos), establezca exactamente sus hallazgos (muchos gráficos serían agradables), y finalmente, concluya en 40-60 palabras más o menos.
  5. Énfasis en cosas que son nuevas (cosas que estás proponiendo) y menos en cosas que son viejas (ese sería tu fondo). Haga la distinción clara.
  6. Generalmente, no incluye su código fuente en su documento. Si debe, publicado en una página web junto con enlaces a su papel.

P / S: Mi consejo es un poco parcial hacia el trabajo académico. Pero creo que debería aplicarse en tu caso.