Normalmente, los redactores técnicos toman un producto creado por un equipo de desarrollo y escriben documentación que expresa ese producto a los usuarios. En Canonical, adoptamos un enfoque diferente. La documentación es parte del producto. Esta es responsabilidad de todo el equipo. El trabajo de documentación está liderado por un redactor técnico que forma parte de un equipo y cuyo título indica su nivel técnico. autoridad.
En la documentación, el trabajo de articular la lógica interna, las interfaces, los flujos de trabajo y las relaciones conceptuales puede exponer problemas de diseño de productos y reflejarlos poderosamente a sus creadores. Los redactores técnicos que forman parte del equipo y del proceso de desarrollo pueden utilizar la documentación para ayudar a dar forma al producto en sí.
Tabla de Contenidos
Proceso de autor y desarrollo.
Estamos contratando docenas de redactores técnicos. Nuestro anuncio de trabajo indica que parte del puesto es «influir en el desarrollo de productos y servicios de Canonical como un usuario experto con aportes importantes en funcionalidad y diseño». Las habilidades que vale la pena poseer incluyen: «Experiencia de usuario, interacción o diseño visual».
Los redactores técnicos reciben formación en diseño y trabajan en estrecha colaboración con sus compañeros de diseño. Deben integrar habilidades y pensamiento de diseño en el trabajo del equipo de ingeniería.
Este no es un acuerdo típico, aunque muchos candidatos al puesto reaccionaron muy positivamente cuando se les informó. Uno de los comentarios que suelen hacer es que si estuvieran involucrados antes en el proceso de desarrollo del producto, su trabajo sería más efectivo y los resultados de la documentación serían mejores. Describieron unánimemente la frustración de crear documentación para un producto cuando ya era demasiado tarde para hacer el trabajo bien a tiempo. Les alegró saber que íbamos a poner a redactores técnicos al principio del proceso de desarrollo.
por qué hacemos esto
Pero no es por eso que hacemos esto. No hacemos esto para darles más tiempo para escribir buenos documentos (aunque ese también sería un resultado deseable). hacemos esto porque La documentación es parte del producto.los redactores técnicos deben ser parte del equipo que crea el producto.
Como resultado, los redactores técnicos de Canonical participan activamente en reuniones del equipo de ingeniería con otros desarrolladores y participan en conversaciones sobre el diseño y desarrollo de los productos del equipo.
De hecho, los autores de documentos se encuentran en una posición especial para comprender la calidad del diseño del producto y ver cosas que sus colegas no pueden.
Cualquier equipo de desarrollo observará el producto desde la perspectiva de cómo funciona. debería Sí. Tienen una idea en mente y están ocupados haciéndola realidad. Su trabajo está impulsado por ello; en su pensamiento, el producto. Sí Esa idea. Su flujo de trabajo y lógica interna se construyen a partir de ideas que preceden a la realidad del producto, por lo que a menudo se sorprenden cuando lo ven. actual Es frustrante cuando los usuarios no comparten sus modelos mentales del producto o tienen dificultades para comprenderlos.
El problema no es que se permita que estas ideas permanezcan implícitas o sin oposición (aunque eso también puede suceder), sino que las mentes creativas del equipo de desarrollo deben permanecer dentro del mundo de estas ideas. Los supuestos compartidos que estructuran la conversación, los saltos lógicos e imaginativos que deben dar e incluso el lenguaje que utilizan para expresar sus pensamientos y su trabajo construyen un mundo espiritual del que es difícil escapar.
La función de un documento, por otro lado, es expresar la idea del producto con palabras a personas ajenas al mundo cerrado del equipo de desarrollo. El autor documenta las interacciones y flujos de trabajo, secuencias físicas y relaciones lógicas de los productos, exponiéndolos a diferentes luces.
luz despiadada
Todo el mundo conoce la experiencia de tener una gran idea y luego, cuando hay que expresarla con palabras, de repente parece un poco menos brillante.
Para eso está la documentación. La documentación es una luz clara e implacable. Bajo un escrutinio intenso, muchos aspectos de un producto pueden parecer feos, torpes o inconexos.
A menudo, la primera persona del equipo de producto en darse cuenta de que hay un problema con el producto es la persona que intenta crear documentación para él.
Por ejemplo:
- Es obvio que es imposible escribir una descripción elegante del flujo de trabajo porque el flujo de trabajo en sí no es elegante.
- O tal vez un mapa conceptual parece limpio hasta que todas las suposiciones tácitas que lo sustentan quedan claras.
- O, cuando se describe una nueva característica en la CLI o API, resulta obvio que es inconsistente con la forma en que funcionan las características existentes, o incluso que toda la interfaz se creó sin ningún principio rector.
Casi todos los redactores técnicos que trabajan en software han tenido esta experiencia en un momento u otro, pero la mayoría de las veces, el trabajo de un redactor técnico es hacer lo que puedan con lo que se les da: como mucho, ayudar a los usuarios a lidiar con los problemas del producto. defectos de diseño; como máximo, ayudar a los usuarios a resolver defectos de diseño del producto. En el peor de los casos, intentan encubrir el fracaso e ignorar las faltas de lógica que encuentran.
Esta es una oportunidad perdida. En este punto, el redactor técnico debería tener derecho a decir algo sobre el producto: «Estoy teniendo problemas para crear buena documentación para esto porque no es tan buena como debería ser» y esperar que esto se tome en serio.
Pero incluso esto llega un poco tarde. Un escritor técnico que participa en conversaciones al comienzo de un producto o característica, trabaja en ideas y piensa en cómo documentarlas, y obliga a sus colegas de desarrollo a pensar en estas cosas también, tiene la capacidad de contribuir mucho a estas intervenciones. más temprano.
Por lo tanto, esperamos que nuestros redactores técnicos aprovechen su posición especial. Queremos que realicen una función de diseño y aporten valor de diseño al producto. Reciben capacitación en diseño, experiencia de usuario e investigación de usuarios para ayudarlos a pensar más profundamente en estas áreas y realizar la función de manera más efectiva. Aparecen en conversaciones de diseño. Necesitamos redactores técnicos para aplicar el pensamiento de diseño al trabajo de ingeniería de productos, y necesitamos equipos de ingeniería para encontrar formas de aprovechar sus conocimientos.
resultado
Los resultados son visibles en nuestros productos y su desarrollo. Parte de ello se encuentra en el nivel de pequeños detalles, lo que ya demuestra que se están notando y mejorando cosas que de otro modo podrían ignorarse; parte de ello está en el nivel de la definición del producto en sí.
Hay un nuevo trabajo para la salida del comando de ayuda en Multipass. Los autores técnicos han realizado cambios en la funcionalidad CLI nueva y existente y en las definiciones de API en Juju, Data Science Stack y otros productos.
Para Charmcraft, Charmhub y Anbox Cloud, la reciente capacitación en diseño y experiencia de usuario/investigación brindó a los autores los medios para desarrollar críticas más útiles de los viajes de los usuarios y herramientas dirigidas por el usuario en estos productos para que los problemas y debilidades puedan resolverse como un problema de ingeniería. .
En otro producto que aún no se ha lanzado públicamente, la presencia de escritores técnicos en la conversación sobre el diseño significó que pudieron llamar la atención sobre cómo el modelo de precios propuesto afectaría una experiencia tutorial exitosa.
etc. Siempre hemos visto el valor que se aporta al desarrollo de productos cuando un documento y las personas que lo crean tienen la oportunidad de participar en su diseño y adquirir las habilidades y conocimientos para realizar esa función de manera más efectiva. Este modo es autoridad técnica Esto hace que un escritor técnico.
Obtenga más información sobre los redactores técnicos
Si está interesado en unirse al equipo de redactores técnicos de Canonical, Estamos contratando redactores técnicos de todos los niveles para varios equipos diferentes. – Tenemos decenas de puestos que cubrir.
Si desea obtener más información sobre lo que hace un redactor técnico directamente de un redactor técnico, puede ir a Academia Normativa de Archivo Abierto.
