Un enfoque centrado en las decisiones, no en las tareas

• Centrarse en las decisiones

  • Una cita de Every Page Is Page One generó un gran cambio en el enfoque para redactar documentación técnica
  • En la comunicación técnica se habla principalmente de apoyar tareas, pero en muchos casos la información que la gente necesita para completar una tarea no es cómo operar una máquina, sino información que apoye la toma de decisiones
  • No basta con documentar procedimientos
  • Hay que informar qué decisiones debe tomar el usuario y cuáles son sus consecuencias, y guiarlo, en la medida de lo posible, hacia recursos y materiales de referencia que ayuden a tomar decisiones

Resumen de GN⁺

• Este artículo enfatiza la importancia del apoyo a la toma de decisiones en la redacción de documentación técnica
• Es necesario ir más allá de una simple explicación de procedimientos y ayudar a que los usuarios tomen mejores decisiones
• Para quienes redactan documentación técnica, es importante proporcionar a los usuarios el contexto y la información que necesitan
• Como proyectos del sector con funciones similares, se recomiendan Confluence y Notion

[GN⁺]

Comentarios de Hacker News

• Escribo sobre la burocracia alemana, y estoy totalmente de acuerdo con este enfoque.
  La mayoría de mis guías empiezan con “qué es esto, quién debe hacerlo y por qué debe hacerlo”. Si no ayudas a la gente a asegurarse de que está haciendo lo correcto por las razones correctas, puede terminar yéndose muy lejos en la dirección equivocada.
  La mayoría de los sitios web gubernamentales no explican esto; solo piden lo necesario para completar el trámite que les corresponde. No lo ven como parte de una decisión más amplia, y asumen que el usuario ya llega sabiendo qué está haciendo.

  • En relación con el último párrafo, el sitio web de UK gov hace esto muy bien. Hay una página de aterrizaje que explica el trámite y, solo después de mostrar advertencias y precauciones, te deja completar el formulario real.
    Si entras al resultado de Google para renovar la licencia de conducir, https://www.gov.uk/renew-driving-licence, y haces clic en “Start Now”, vas a ver a qué me refiero.
    Desde la perspectiva de un “usuario avanzado” a veces se siente como un estorbo, pero entiendo que hay que considerar a todo el mundo.
  • Este comentario me hace pensar que te gustaría Every Page Is Page One. La idea central es que las personas pueden llegar a cualquier página de un sitio de documentación, así que cada página debe dar contexto rápidamente y permitir que el usuario determine fácilmente si está en el camino correcto.
    De ahí viene también el título del libro. Cualquier página del sitio puede ser la primera página para el usuario.
  • Ojalá más documentación técnica tuviera este enfoque. Suelo preguntarme constantemente por qué algo se hace de cierta manera, así que termino yéndome por tangentes y avanzando más lento.

• Encaja bien con la forma en que uso los LLM. Siempre pido opciones y luego decido por mi cuenta cuál de ellas tiene más sentido.
  En esencia, lo uso como una especie de documento mágico y extraño que, en cada momento de decisión, escupe opciones posibles de forma imperfecta pero útil.

  • Piensa en un aprendiz que trabajaba bajo las órdenes de un artista famoso como Leonardo. El maestro trazaba el contorno y los bocetos, y los estudiantes rellenaban los espacios en blanco bajo supervisión. A veces el maestro incluso robaba las ideas de sus estudiantes.
  • ¿Podrías dar un ejemplo de este enfoque?

• Muy bueno. Breve, directo y perspicaz. Yo tiendo a una forma de pensar de panorama general, así que para mí no solo importa cómo hacer algo, sino también por qué y cómo se conecta con el contexto más amplio.
  Animo a los desarrolladores a usar activamente el campo Description de las historias y tareas de Jira para incluir un resumen de por qué hacemos este trabajo y cómo se conecta con el panorama general. A algunos parece no gustarles, pero a otros les gusta bastante.
  A mí me gusta porque puedo aportar el panorama general del proyecto, y los desarrolladores están satisfechos porque, al entenderlo, pueden trabajar de forma más independiente.

• Medir si la documentación ayuda a las personas a tomar buenas decisiones parece mucho más difícil que medir si las ayuda a completar tareas con éxito.
  La razón por la que se optimiza para documentación basada en tareas y procedimientos es que la empresa exige demostrar el valor del equipo de documentación, hay demanda de este tipo de documentos y existen muchas formas de medirlo y reportarlo en plazos cortos.
  Pero la pregunta “¿este conjunto de documentos ayudó a alguien a construir lo correcto de la manera correcta?” es tan difícil de responder incluso para las organizaciones sobre sus propios productos que, al abstraerla al efecto de la documentación, se vuelve muy difusa.
  No quiero decir que no se pueda escribir documentación que ayude a decidir, sino que es muy difícil demostrar con números que lo hiciste. Puedo clasificar qué tan bien varios conjuntos de documentos apoyan a usuarios que necesitan tomar decisiones y explicar los fundamentos, pero no sé bien cómo cuantificar eso de la forma que quiere la empresa.
  También me intriga cómo cambiaría la estructura de un conjunto de documentación diseñado para apoyar la toma de decisiones frente a uno diseñado para apoyar tareas. Las grandes categorías probablemente seguirían siendo conceptos, referencias y guías, pero habría muchos más documentos conceptuales y más espacio para contextualizar los conceptos. También esperaría más dependencias entre temas y más referencias cruzadas.

  • Es interesante que el primer pensamiento no sea “cómo uso esto para mejorar la documentación que escribo”, sino “cómo demuestro que esto mejora la documentación que escribo”. Parece que trabajas en un entorno bastante estricto.
  • En lugares donde uno puede hacer libremente lo que cree que es mejor para los usuarios, como en proyectos personales, es muy probable que tome el apoyo a la toma de decisiones como base de la estrategia de documentación.
    Desde una perspectiva de trabajar de buena fe, si siento que “apoyar la toma de decisiones” es lo mejor para mi proyecto, creo que tengo la obligación de llevar esa estrategia también a la documentación del trabajo.
    Por suerte no tengo gerentes cortoplacistas apretándome el cuello, pero si tuviera que convencer a alguien en el trabajo, lo haría así. Primero explicaría la lógica de la estrategia. Apoyar la toma de decisiones tiene sentido y también es convincente. La documentación de tareas se sigue escribiendo, pero las tareas son solo un subconjunto del apoyo a la toma de decisiones.
    Después presentaría una lista extensa de ejemplos de tickets de soporte, discusiones en salas de chat, etc., donde la falta de apoyo a la toma de decisiones fue el problema. Por honestidad intelectual, mostraría tanto la lista completa de tickets de soporte relacionados con documentación como el subconjunto de ellos vinculado al apoyo a la toma de decisiones. Si la proporción no es despreciable, por ejemplo 25%, entonces hay que mirar más a fondo el “apoyo a la toma de decisiones”.
    Por último, los stakeholders podrían aportar ejemplos de su propio trabajo. Algo como: “¿Recuerdan lo difícil que fue decidir por qué CMS cambiarlo?”.

• Esto es lo que normalmente llamo un enfoque heurístico.
  Siento que el trabajo necesita un enfoque tipo lógica difusa. Aunque funciona mejor cuando el ingeniero ya tiene cierto grado de experiencia.
  Si falta experiencia, aunque la persona sea capaz e inteligente, hay que ser mucho más prescriptivo.

  • Thinking in Bets fue uno de los libros más útiles para mi forma de abordar la ingeniería de software. No es un libro sobre código, sino sobre cómo tomar decisiones de manera efectiva en entornos con información limitada.
  • No entiendo bien qué significa abordar el trabajo con un enfoque de lógica difusa. ¿Podrías explicarlo un poco más?

• Rich Hickey explica aquí un buen enfoque para tomar decisiones en un contexto de equipo: https://www.youtube.com/watch?v=c5QF2HjHLSE
  La charla se titula “Design in Practice”, pero en realidad trata sobre la toma de decisiones.

• “El trabajo es simplemente todo lo que hay que hacer para pasar de una decisión a la siguiente.” — Venkatesh Rao, Tempo

• He venido defendiendo algo parecido. No hay que describir las herramientas solo en un nivel alto; en particular, la gente suele entrar en modo marketing, y hay que hablar de qué problema intenta resolver esa herramienta y qué concesiones se hicieron en el proceso.
  Así es mucho más fácil poner la herramienta, las opciones y modos disponibles, etc., en contexto, y evaluar rápidamente si es adecuada para uno.

• Este consejo me resulta un poco confuso. ¿La decisión de quién? ¿La del creador de la herramienta o la del usuario?
  En general, parece una simplificación excesiva. Es más útil entender primero qué tipo de documentación estás escribiendo: de aprendizaje, orientada a objetivos, de comprensión o informativa [1].
  Por ejemplo, si estás buscando la API de una función, puede ser molesto que te lluevan datos sobre “decisiones”.
  1 - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

  • La documentación siempre debe atender las necesidades del usuario. Eso no desaparece. Lo mismo aplica a Diataxis, los cuatro cuadrantes del documento que mencionas.
    Creo que este artículo resuena porque expone el punto ciego de dos estrategias conocidas. Todo el mundo intenta crear documentación centrada en el usuario y muchos equipos siguen Diataxis, pero aun así siguen teniendo dificultades para lograr que la documentación ayude a terminar el trabajo.
    Partir de la perspectiva básica de que “la documentación debe apoyar decisiones” puede ser un camino para hacerla más útil.

• Es importante saber cómo la gente usa mi sistema para tomar decisiones. Creo que ese conocimiento es esencial para mantener, ampliar o crear un sistema nuevo.
  Pero el texto propone una responsabilidad mayor: documentar el proceso de toma de decisiones del usuario e informar sobre el contexto, las opciones y las consecuencias de la decisión.
  Trabajé en un “sistema de apoyo a la toma de decisiones” con esa responsabilidad, y se volvió complejo muy rápido. A la gente le gusta discutir sobre los resultados incluso cuando se conocen con 100% de certeza. Tampoco le gustan los correos automáticos que incluyen incertidumbre, ni que la documentación la obligue a elegir entre dos opciones cuando en la realidad hay muchas más.
  Más allá de este artículo, me gustaría que el libro tratara el concepto de control. Para documentar cierto comportamiento, debe existir algún grado de garantía o aplicación sobre ese comportamiento para que la documentación conserve su autoridad. Personalmente, creo que la falta de autoridad y control es un punto ciego común e importante en iniciativas de escritura como https://www.plainlanguage.gov.

  • Citando de nuevo lo que escribí sobre este artículo en r/technicalwriting, lo realmente importante de la idea de Baker es que la doctrina de la formación en documentación técnica está absolutamente orientada a las tareas.
    Si se encuestara a redactores técnicos profesionales, muchos creerían que “ayudar a los usuarios a completar tareas” es el objetivo principal de la documentación, quizá EL objetivo principal.
    La breve cita de Baker es bastante radical en el sentido latino de “volver a la raíz”, porque sugiere que una de nuestras suposiciones fundamentales tiene una carencia importante.
    Personalmente, la idea de Baker me resulta interesante porque establece un estándar mucho más alto que el que hoy se espera de la documentación técnica. Muchos documentos asumen que, si una tarea está documentada, “misión cumplida”, pero Baker parece decir que eso no basta.
    Por supuesto, las tareas igual deben documentarse, pero son un subconjunto de la información que conforma las decisiones.
    No recuerdo si el libro de Baker discutía el control en el sentido que mencionas aquí. Para mí es una idea nueva, así que gracias.
    Un ejemplo concreto de control que se me ocurre es este: gran parte de mi documentación depende de páginas de otros proyectos open source, y si la calidad de esas páginas externas es baja, probablemente mejorar esa documentación también debería ser mi responsabilidad. Mucha gente podría considerar que la documentación fuera de su propio sitio no es su responsabilidad, pero si de verdad se quiere apoyar decisiones, no importa quién la aloje.
    Quizá haya mucho que aprender de la actitud de ser un buen ciudadano del open source.