LO
Redactor técnico / ingeniero de documentación — tareas, una a una
La unidad de análisis es la tarea, no el nombre del puesto. Cada una de las siguientes lleva su dirección, si el juicio se apoya en evidencia o en una inferencia de la plataforma, el razonamiento y lo que no establece.
Todas las tareas de esta página#
Redactar la referencia
Automatizándose✓ Con evidenciaLa referencia de la API, la tabla de parámetros, la nota de versión, la entrada del registro de cambios: documentación cuyo contenido lo determina el código.
Esta es la tarea de escritura más expuesta de este sitio, porque la fuente de verdad es legible por máquina y el formato de salida es fijo. Generar una tabla de parámetros a partir de una firma ya lo automatizaban en parte los generadores de documentación mucho antes que los modelos; lo que añadieron los modelos es prosa que se lee como si la hubiera escrito una persona, y eso quitó la última razón para que la escribiera una persona.
Una referencia generada es una referencia que nadie leyó antes de publicarla, y el modo de fallo no es que esté equivocada sino que sea verosímil: documentación que describe lo que el código declara y no lo que hace. Ese hueco solo lo encuentra alguien usando la cosa, que es la tarea siguiente, así que automatizar esta sube el valor de aquella en vez de quitar el puesto.
Usar de verdad aquello que estás documentando
Sigue llevándola una persona≈ Inferencia de la plataformaSeguir tus propias instrucciones en una máquina limpia y encontrar el paso que era obvio para quien lo programó e imposible para todos los demás.
La entrada de esta tarea no existe en ningún repositorio: es la experiencia de estar perdido en un sitio concreto. Un modelo entrenado sobre el código hereda el conocimiento de quien lo escribió, que es precisamente el conocimiento que tiene que faltar para que la prueba funcione: aquí el valor viene de no saber.
Esta tarea es el argumento más fuerte a favor de la ocupación y el más débil en una reunión de presupuesto, porque su producto es una ausencia: los tickets de soporte que no ocurrieron. Allí donde se han recortado equipos de documentación, esta es la tarea que se fue primero, y para eso no hizo falta nada de la tecnología.
Decidir qué no se escribe
Sigue llevándola una persona✓ Con evidenciaElegir qué veinte por ciento de la superficie se documenta bien, y negarse al resto.
La generación barata convierte esta en la tarea más valiosa y no en la menos, porque la restricción se movió: cuando escribirlo todo se volvió posible, elegir pasó a ser el puesto entero. Decidir qué se deja fuera depende de saber qué usuarios existen y qué están intentando hacer, y eso no está en el código.
Ser más valiosa no es lo mismo que ser reconocida: la documentación se suele medir por cobertura, y la cobertura es justamente la métrica que la generación barata vacía de sentido. A un equipo juzgado por páginas publicadas se le premiará por abandonar esta tarea justo en el momento en que se vuelve la importante.
Sacarle la respuesta a un ingeniero
Sigue llevándola una persona≈ Inferencia de la plataformaAveriguar cuál de cinco personas sabe por qué se comporta así, y conseguir quince minutos de su tiempo para enterarte.
La información que hace falta está sin documentar por definición: si estuviera escrita, esta tarea no existiría. Extraerla es un acto social que se ejecuta contra la agenda de alguien, y la destreza está en saber qué pregunta produce la respuesta real y no la oficial.
Esta tarea es lo que hace difícil hacer este puesto en remoto, a tiempo parcial o desde la silla de un proveedor externo, que es exactamente la dirección hacia la que empuja la presión de costes. La amenaza aquí no es la automatización, es que el puesto se reestructure en algo que no pueda incluir esta tarea, tras lo cual la documentación se degrada por razones que nadie atribuye correctamente.