¿Qué pasa con la aversión a la documentación en la industria?

47

Parece haber una aversión a escribir incluso la documentación más básica. Nuestro proyecto READMEs es relativamente simple. Ni siquiera hay listas actualizadas de dependencias en los documentos.

¿Hay algo que desconozco en la industria que haga que a los programadores no les guste escribir documentación? Puedo escribir párrafos de documentos si es necesario, entonces, ¿por qué otros son tan reacios?

Más importante aún, ¿cómo los convenzo de que escribir documentos nos ahorrará tiempo y frustración en el futuro?

Rudolf Olah
fuente
13
¡Porque sabemos lo que estamos haciendo! ¿Por qué deberíamos tomarnos un tiempo del día para escribir lo que ya sabemos y nunca olvidaremos? Sin embargo, en serio, me ocupo de lo mismo a diario trabajando en una base de código que comenzó su proceso de diseño hace 7 años y que ha sido actualizado diariamente desde entonces por un equipo de 4 a 7 ingenieros. La documentación es algo con lo que siempre hemos luchado, pero es un mal necesario.
Ampt
6262
Porque la experiencia ha demostrado que nadie lee los documentos.
user16764
8
Desde el punto de vista comercial, una gran cantidad de documentación le está costando dinero a la compañía aquí y ahora, cuando en cambio podría estar trabajando en el próximo proyecto para ganar dinero. Esa necesidad de estar siempre generando ganancias es la presión que siente contra "perder el tiempo" escribiendo documentación. Además, nadie lee los documentos y en su lugar lee las fuentes porque solo ellos son la máxima autoridad.
Patrick Hughes
15
Mantener los documentos sincronizados con el código más reciente puede ser "desafiante" si está escribiendo a un nivel superior al Javadoc o equivalente.
Dan Pichelman
12
No es divertido ...

Respuestas:

21

No creo que sea útil especular sobre las motivaciones de las personas que no están adoptando algo que crees que es una buena práctica o que continúan haciendo algo que ves como una mala práctica. En este negocio, las personas que caen en una o ambas categorías superarán con creces a las que verás cara a cara, así que deja de volverte loco.

En cambio, concéntrese en el problema y las posibles soluciones.

1. Escriba buena documentación usted mismo

Es posible que no sea realista esperar que todos en su equipo dirijan sus esfuerzos a las cosas que ve como un problema. Esto es especialmente cierto si eres relativamente nuevo en el equipo. Me aventuraría a adivinar que sí, porque si fueras miembro fundador del equipo, parece muy probable que ya hayas resuelto este problema desde el principio.

Considere, en cambio, trabajar hacia el objetivo de escribir buena documentación usted mismo y lograr que la gente la use. Por ejemplo, si alguien de mi equipo me pregunta dónde está el código fuente del Proyecto A o qué configuración especial necesita el Proyecto A, lo dirijo a la página wiki del Proyecto A.

Si alguien me pregunta cómo escribir una nueva implementación de Factory F para personalizar una cosa para el Cliente C, les digo que está en la página 10 de la guía del desarrollador.

La mayoría de los desarrolladores odian hacer preguntas que puedan hacer que parezcan que no pueden simplemente "leer el código" incluso más de lo que odian leer la documentación, por lo que después de suficientes respuestas de esta naturaleza, primero irán a los documentos.

2. Demuestre el valor de su documentación

Asegúrese de aprovechar todas las oportunidades para señalar dónde está demostrando su valor la documentación (o lo habría hecho, si se usara). Intenta ser sutil y evita "te lo dije", pero es perfectamente legítimo decir cosas como

Para referencia futura, la página wiki de este proyecto tiene información sobre la rama del código central que se creó para el soporte continuo de la versión 2.1, por lo que en el futuro podemos evitar tener que hacer una prueba de regresión completa si las personas que mantienen versiones publicadas verifican la wiki antes de revisar el código.

o

Estoy tan contento de haber anotado los pasos para hacer la Tarea T. Realmente no me importa si nadie más la usa, ya me ahorró más tiempo del que pasé escribiendo.

3. Conseguir la gestión a bordo

Después de unos pocos incidentes en los que tener documentación está probadamente ahorrando tiempo / dinero, probablemente notará un "deshielo" distinto hacia la documentación. Este es el momento de presionar el punto al comenzar a incluir el tiempo de documentación en sus estimaciones (aunque honestamente, generalmente actualizo / creo documentos mientras se ejecutan procesos largos, como compilaciones o registros). Especialmente si se trata de una contratación reciente, es posible que esto no se cuestione, sino que se vea como una nueva práctica que está trayendo de un lugar de trabajo anterior (que bien podría ser).

Palabra de advertencia: a la mayoría de los jefes no les gusta hacer que la gente haga nada, especialmente cosas que no están directamente vinculadas a una tarea facturable, así que no esperes que este apoyo sea en forma de un mandato. En cambio, es más probable que te dé rienda suelta para escribir más documentos.

4. Fomente la documentación cuando la vea

Tal vez parte de la razón por la cual las personas no escriben documentos tan a menudo como deberían es porque sienten que nadie lo está leyendo. Entonces, cuando vea algo que le guste, asegúrese de mencionar al menos que estaba contento de que estuviera disponible.

Si su equipo hace revisiones de código, este es un momento en el que puede escribir una o dos palabras sutiles para alentar los buenos comentarios.

Gracias por documentar la solución para el error B en el Marco G. No sabía sobre eso, y no creo que podría haber entendido lo que estaba haciendo sin eso allí.

Si tiene a alguien en el equipo que está realmente entusiasmado con la documentación, no está de más cultivar a esa persona yendo a almorzar o tomar un café y asegurándose de ofrecer una pequeña validación para contrarrestar el desánimo que pueden obtener al ver al resto del equipo. no valora tanto la documentación.

Más allá de eso, realmente no es su problema a menos que esté en una posición de liderazgo o gerencia. Puedes llevar un caballo al agua, pero no puedes obligarlo a beber. Si no es su caballo, es posible que no esté contento de que tenga sed, pero todo lo que puede hacer es llenar el comedero.

Amy Blankenship
fuente
1
+1 para el Punto # 2, respondiendo directamente a la pregunta del OP que comienza con "¿Cómo puedo convencer ...?"
Ray Toal
Me gusta esta respuesta, las otras se centraron más en el "por qué" en lugar del "cómo"
Rudolf Olah
@omouse: eso es porque en la mayoría de los casos, escribir documentación no le ahorrará tiempo y frustración en el futuro. Raramente son precisos, y la gente nunca los lee incluso cuando lo son.
Telastyn
1
Los principios SÓLIDOS generalmente no le ahorran tiempo ni dan como resultado un mejor diseño, porque la mayoría de la gente no los comprende completamente o realmente no les importa. Según su lógica, no debemos aspirar a aplicarlos, GRASP o cualquier otra buena práctica. ¿Me recuerdas por qué te molestas en volver a participar en programadores?
Amy Blankenship
Considera muy útil especular sobre las motivaciones de las personas.
tymtam
55

Hay dos factores principales en mi experiencia:

Plazos

La mayoría de las empresas están tan limitadas por la fecha que el control de calidad, la deuda tecnológica y el diseño real se reducen solo para que el gerente del proyecto no se vea mal o cumpla con un plazo de cliente absurdo y demasiado prometido. En este entorno donde incluso se reduce la calidad funcional, una inversión a largo plazo como la documentación tiene pocas posibilidades.

Cambio

Una práctica recomendada relativamente nueva para los desarrolladores es quitar el énfasis a los comentarios. La idea es que mantener la información en dos lugares (el código [incluidas las pruebas] y los comentarios sobre el código) conlleva una gran sobrecarga para mantenerlos sincronizados por poco beneficio. "Si su código es tan difícil de leer que necesita comentarios, ¿no pasaría más tiempo limpiando el código?"

Yo personalmente ni siquiera miraré más comentarios. El código no puede mentir.

La documentación sigue la misma veta. Con la adopción generalizada de ágil, las personas reconocen que los requisitos cambian regularmente. Con el uso generalizado de la refactorización, la organización del código cambiará considerablemente. ¿Por qué pasar el tiempo documentando todo esto que está destinado a cambiar? El código y las pruebas deberían hacer un buen trabajo al hacerlo.

Telastyn
fuente
11
+1 para "Personalmente ya ni siquiera miraré comentarios", creo que esto es común; cuando creces hasta cierto nivel de comodidad con el código en sí, puedes leerlo más rápido que los comentarios (y aún más rápido si los comentarios no están en el camino), y el código no miente
Jimmy Hoffa
41
Esto pierde el punto de comentarios, que es explicar por qué . No necesitan estar por todas partes, y no necesitan ser muy largos, pero un enlace bien ubicado a las reglas comerciales que describe por qué existen las siguientes 20 líneas de lógica realmente extraña en su estado actual es mucho más conveniente que intentar recorrer el historial de versiones para encontrar el razonamiento original.
zzzzBov
77
@zzzzBov - absolutamente, esa es la visión moderna de las cosas. Esto ha cambiado desde puntos de vista anteriores que alentaron comentarios más generalizados. Del mismo modo, la documentación de lo que está haciendo el código se ha reducido a una documentación que se centra en por qué lo está haciendo (documentos de diseño, por ejemplo).
Telastyn
8
El código puede mentir. El cliente puede haber querido algo, y fue codificado para hacer otra cosa. Entonces, si todo lo que tiene ahora es el código, ¿es correcto?
thursdaysgeek
66
El código puede mentir ... Tengo un método de 4,000 líneas (hey, no lo creé, solo lo tengo ahora ...) y veo una colección claramente llamada "productList", así que para un nuevo cambio agrego un Producto objetarlo. Excelente. Solo que no funciona, resulta que algún desarrollador anterior era "eficiente" y reutilizaba la variable de tipo Lista para evitar saturar las 4.000 líneas con demasiadas variables, y en ese ámbito contiene objetos de Cliente ...
Kevin Rubin
17

Aquí hay varios factores en juego:

  1. El código bien escrito es su propia documentación. En igualdad de condiciones, es mejor escribir un código más claro que hable por sí mismo, en lugar de más documentación. Haga eso, y necesitará modificar menos documentación cuando cambie ese código.

  2. Escribir documentación es posiblemente una habilidad diferente que escribir código. Algunos desarrolladores de software son mejores que otros. Algunos son mucho mejores escribiendo código que escribiendo documentación.

  3. La documentación solo debe escribirse una vez , no dos veces (una vez en el código fuente y nuevamente en la guía del programador). Es por eso que tenemos cosas como comentarios XML y generadores de documentación. Desafortunadamente, el uso de tales herramientas puede ser más complicado y engorroso que simplemente escribir la documentación a mano, por lo que no se ven esas herramientas ampliamente utilizadas.

  4. La buena documentación lleva mucho tiempo y es difícil hacerlo bien. En igualdad de condiciones, puede ser más valioso escribir código nuevo que escribir documentación para código ya existente.

  5. Cuando el código cambia, también debe cambiar la documentación. Cuanta menos documentación haya, menos se debe cambiar.

  6. Nadie lee la documentación de todos modos, entonces, ¿por qué molestarse?

Robert Harvey
fuente
2
re # 1, no creo que ese sea el caso, pero el # 4 es definitivamente cierto
Rudolf Olah
3
@whatsisname: en absoluto. Escriba un código más claro que requiera menos documentación y deberá modificar menos documentación cuando cambie ese código.
Robert Harvey
2
@thursdaysgeek: lo que significan esas viñetas es que no debería tener que escribir la documentación dos veces: una para los comentarios del código y otra vez para el archivo de ayuda / referencia del programador. Ciertamente no deberías tener que reescribirlo dos veces. ¿Están leyendo esto?
Robert Harvey
44
# 6 ... Creo que este es un error común. Una gran cantidad de personas que leer la documentación a fondo.
Dinámico
3
@tymek: Tienes tu signo al revés. Amigos, este no es un tutorial sobre cómo crear documentación; Es un cálculo de por qué los desarrolladores tienen una actitud negativa hacia él.
Robert Harvey
11

Elefante en la sala: los programadores no son (necesariamente) escritores. Tampoco son necesariamente susceptibles de desarrollar sus implementaciones a escritores técnicos. Segundo elefante en la sala: los escritores técnicos generalmente no pueden desarrollar detalles útiles para futuros desarrolladores (incluso si los desarrolladores se dignasen a explicárselos).

Un sistema complejo puede volverse casi inescrutable con el tiempo sin la documentación adecuada. El código se vuelve menos valioso inversamente proporcionalmente a su capacidad de desplazamiento [sic]. Resuelto, la gerencia contrata a un ingeniero de software que puede leer el código y los detalles de los desarrolladores, le paga a una tarifa de desarrollador y le ordena documentar y mantener la documentación. Este escritor puede leer el código y sabrá qué preguntas hacer y completará los detalles según sea necesario. Al igual que tiene un departamento de control de calidad, tiene un departamento de documentación interno.

El código se volverá más valioso, ya que puede licenciarlo a un tercero (porque él puede entenderlo), el código se puede auditar y mejorar / refactorizar más fácilmente, tendrá una mejor reutilización del código incluso donde pueda fácilmente descubra las versiones más livianas de su software, y podrá introducir nuevos desarrolladores más fácilmente en el proyecto, a sus ingenieros de soporte les encantará trabajar para usted.

Esto nunca va a suceder.

naftalimich
fuente
1
Sin mencionar que cuando se trata de describir el código existente, es más difícil dar una buena descripción cuando el código y la funcionalidad son tan complejos que ya nadie sabe lo que hace, por lo que cualquier cambio nuevo tiene un impacto que el nuevo desarrollador no tuvo en cuenta. saber sobre ...
Kevin Rubin
1
Sugeriría que "la habilidad básica para comunicar sus intenciones con documentación (limitada)" es una habilidad necesaria del programador. Un programador no tiene que ser poeta, pero si no puede documentar, honestamente no lo quiero en mi equipo. Dicha persona es una responsabilidad a largo plazo.
5

Más importante aún, ¿cómo los convenzo de que escribir documentos nos ahorrará tiempo y frustración en el futuro?

¿Hace eso?

Hay dos tipos de documentación:

Documentación útil

Documenta cómo usar un producto terminado, una API, qué direcciones IP o nombres de URL tienen nuestros servidores, etc. Básicamente, todo lo que se usa de manera intensiva y a diario. La información incorrecta se descubrirá rápidamente y se corregirá. Necesita ser fácil y fácil de editar (por ejemplo, Wiki en línea).

Documentación inútil

Documentación que cambia a menudo, muy pocas personas están interesadas en ella y nadie sabe dónde encontrarla. Como el estado actual de una característica que se está implementando. O documentos de requisitos en un documento de Word oculto en algún lugar de SVN, actualizado hace 3 años. Esta documentación tomará tiempo para escribir, y tiempo para descubrir que está mal más tarde. No puede confiar en este tipo de documentación. Es inútil. Pierde el tiempo.

A los programadores no les gusta escribir o leer documentación inútil. Pero si puede mostrarles la documentación que es útil, la escribirán. Tuvimos un gran éxito con él en mi último proyecto cuando introduje un Wiki donde pudimos escribir toda la información que necesitamos a menudo.

Uooo
fuente
4

Diría que la razón principal es la falta de voluntad y la falta de comprensión de la función de la documentación. Hay una serie de clases de documentación a considerar:

Documentación de producto / lanzamiento

Esto es todo lo que sale con su producto 'terminado'. Esto es más que solo manuales, esto es README, registros de cambios, instrucciones y demás. En teoría, puede salirse con la suya al no escribir estos, pero termina con un producto que la gente no quiere usar, o una carga de soporte que es innecesariamente costosa.

Documentación API

Esto describe algo que debería ser relativamente estático. Dado que numerosos consumidores pueden estar codificando su API, debe ser lo suficientemente estable como para que alguna prosa que describa cómo usarla tenga valor. Describir qué parámetros son compatibles, cuál puede ser el valor de retorno y qué errores pueden generarse permitirá a otros usuarios la capacidad de comprender su API en el nivel correcto de abstracción: la interfaz ( no la implementación).

Comentarios de código

La opinión de la industria sobre los comentarios parece estar cambiando, por el momento. Cuando comencé a codificar profesionalmente, los comentarios eran una condición sine qua non cuando se trataba de escribir código. Ahora, la moda es escribir código que sea tan claro que los comentarios sean innecesarios. Me arriesgaría a adivinar que esto se debe, en parte, al hecho de que muchos lenguajes modernos están escritos en un nivel mucho más alto y es mucho más fácil escribir código legible en Java, JavaScript, Ruby, etc. de lo que estaba en ensamblador , C, FORTRAN, etc. Por lo tanto, los comentarios tenían un valor mucho mayor.

Todavía creo que hay valor en los comentarios que describen la intención de una sección de código, o algunos detalles sobre por qué se eligió un cierto algoritmo en lugar de uno más obvio (para evitar que los demonios de refactorización excesivamente entusiastas 'arreglen' el código que no t realmente necesita ser reparado).

Desafortunadamente, hay mucho egoísmo, racionalización y autoengaño involucrados en las decisiones de los programadores de no documentar. La realidad es que, como el código, la audiencia principal para la documentación son otras personas. Por lo tanto, las decisiones de escribir (o no escribir) documentación, en cualquier nivel, deben tomarse a nivel de equipo. Para los niveles más altos de abstracción, puede tener más sentido tener a alguien que no sea desarrollador para hacerlo. En cuanto a la documentación a nivel de comentarios, se debe llegar a un acuerdo sobre el propósito y la intención de los comentarios, especialmente en equipos mixtos de habilidades y experiencia. No es bueno tener desarrolladores senior escribiendo código que los desarrolladores junior no pueden abordar. Alguna documentación bien ubicada y bien escrita puede permitir que un equipo opere de manera mucho más efectiva

Dancrumb
fuente
1
+1 para "la audiencia principal para la documentación son otras personas". Demasiados programadores realmente no valoran la comunicación con otros. (Por eso también les resultará difícil avanzar en antigüedad.)
Donal Fellows
4

Aquí están mis dos centavos.

  1. El Manifiesto Ágil dice "Software de trabajo sobre documentación exhaustiva" y no todos leen para llegar a "Es decir, si bien hay valor en los elementos de la derecha, valoramos más los elementos de la izquierda".

  2. Lamentablemente, es común en https://en.wikipedia.org/wiki/Code_and_fix y la documentación no funciona con este modelo (se desincroniza).

  3. La industria del desarrollo de software no está bien regulada. No existe un requisito legal para escribir documentación.

  4. El código autodocumentado es la tendencia actual.

Dicho esto, creo que hay mucha buena documentación por ahí.

tymtam
fuente
(1) " Valoramos más las cosas de la izquierda ... " no implica que no nos importe en absoluto el lado derecho. (2) " 4. El código de autodocumentación es la tendencia actual " Si la documentación no es necesaria entonces, ¿por qué entonces las personas se quejan ante todo de una documentación mala / faltante? (3) El tiempo que un desarrollador ahorra al no documentar su trabajo lo dedica cada desarrollador que necesita la información, porque tiene que escanear 5000 líneas de código de autodocumentación en lugar de la documentación de 5 páginas. La eficiencia es otra cosa, pero bueno, ¡somos ágiles!
JensG
2

La documentación lleva tiempo, y sospecho que muchos desarrolladores han tenido demasiados encuentros con documentación que era peor que inútil. Se les ocurre la idea de que la documentación no solo les causará problemas a su gerente (el mismo tipo que sigue cortando la parte de control de calidad del horario), sino que no ayudará a nadie, incluidos ellos.

Cualquier documentación medio decente es una inversión en el futuro. Si no le importa el futuro (porque no piensa más allá del próximo cheque de pago o porque cree que no será su problema), entonces la idea de hacer la documentación es extremadamente dolorosa.

Michael Kohne
fuente
2

Muchas de las otras respuestas pasan por alto al punto de que hay al menos dos tipos de documentación: un conjunto para otros desarrolladores y un conjunto diferente para los usuarios finales. Dependiendo de su entorno, también puede necesitar documentación adicional para los administradores del sistema, los instaladores y el personal de la mesa de ayuda. Cada público objetivo tiene diferentes necesidades y niveles de comprensión.

Considere el desarrollador (estéreo) típico: es un codificador por elección. Ha elegido una carrera fuera del ojo público y pasa largas horas detrás de un teclado comunicándose principalmente consigo mismo. El proceso de documentación es una forma de comunicación y el conjunto de habilidades requeridas para producir una buena documentación es antitético a las habilidades requeridas para producir un buen código.

Un buen escritor de documentación puede comunicarse en varios idiomas: el idioma de los usuarios, el idioma de administración, el idioma del personal de soporte, el idioma de los desarrolladores. Es el trabajo de un escritor de documentación comprender lo que comunica un codificador y traducirlo a una forma que todos los otros grupos puedan entender.

Cuando esperas que los codificadores desarrollen la habilidad necesaria para convertirse en buenos comunicadores (escritos o de otro tipo), la cantidad de tiempo dedicado a perfeccionar el conjunto de habilidades primario (¡codificación!) Disminuye. Cuanto más se aleje de su zona de confort (codificando y comunicándose con otros codificadores), se necesitará más tiempo y energía para realizar bien la tarea. Puede esperar razonablemente que un programador profesional desee centrarse principalmente en sus competencias básicas, a expensas de todos los demás.

Por este motivo, es mejor dejar la documentación (con la excepción de los comentarios de código en línea) a los comunicadores, no a los codificadores.

George Cummins
fuente
44
Oh, pish Cuantas más cosas aprendas a hacer bien, mejor aprenderás a hacer las cosas bien. Del mismo modo que las personas que conocen varios idiomas programan mejor que las personas que solo conocen uno (porque saben más formas de pensar sobre el problema), poder escribir e incluso visualizar gráficamente le brinda más herramientas para pensar y resolver problemas. Las habilidades que necesita para poder describir lo que está sucediendo son las mismas que necesita para descifrar lo que debería suceder.
Amy Blankenship
1
Quiero que otros desarrolladores sean o se conviertan en comunicadores expertos. La gran mayoría de la programación que hacemos (al menos en software empresarial) no requiere el conjunto de habilidades de codificación perfeccionadas más absoluto. Requiere habilidades de comunicación persona a persona mucho mejores para que los futuros desarrolladores entiendan lo que se escribió. Cuanto mejor se comunique un desarrollador, especialmente a personas que nunca conocerán, mejor se les considerará a largo plazo, y no es probable que tengan un código inteligente.
Kevin Rubin
2

Leer el código te muestra cómo funciona. No puede explicar por qué : necesita comentarios.

Leer el código le muestra el nombre de un método y los tipos de los parámetros. No puede explicar la semántica, o la intención exacta del autor: necesita comentarios.

Los comentarios no reemplazan la lectura del código, sino que le agregan.

benlast
fuente
44
+1 para el sentimiento. Pero esta no es una respuesta a la pregunta; parece que estás respondiendo a algo más aquí que no sea la pregunta real que se hizo.
bignose
2

La documentación no se ejecuta como el código. Como resultado, a menudo no hay bucles de retroalimentación efectivos para verificar que la documentación esté en su lugar y esté completa. Esta es la misma razón por la que los comentarios de código tienden a pudrirse.

Donald Knuth promovió la programación literaria como una forma de mejorar la calidad del software, escribiendo efectivamente la documentación con el código. He visto algunos proyectos que han utilizado este enfoque con bastante eficacia.

Personalmente, trato de mantener la tendencia moderna de mantener la API pública de su código lo más legible posible y usar pruebas unitarias para documentar el uso para otros desarrolladores. Creo que esto es parte de la idea más importante de que su API sea de una forma que pueda ser explorada y descubierta. Creo que este enfoque es parte de lo que HATEOAS intenta lograr con los servicios web.

aboy021
fuente
Para justificar mis elecciones para la generación automatizada de documentación, se me ocurrió una fórmula simulada para mostrar cómo la inercia humana es la culpable de toda podredumbre de comentarios. Al ampliar el argumento, descubrí que la creación de métodos que brindan ventajas reales para un desarrollador, como la generación de diagramas parcialmente automatizada a partir de meta comentarios en el código fuente, tiende a actualizarse cada vez que un desarrollador intenta darle sentido al código. Por cierto, la mayoría de las veces este desarrollador es solo "mi futuro".
wolfmanx
0

Un punto menor, pero que parece ser importante con algunos desarrolladores que escriben poca documentación desagradable: no pueden escribir. Si tiene una aproximación del sistema de 10 dedos, tiende a escribir más documentación solo porque es fácil. Pero si estás atrapado con la caza y el picoteo, estás perdido. Si fuera responsable de contratar, esto es realmente algo que comprobaría.

Hans-Peter Störr
fuente
0

A las personas que no les gusta leer documentación no les gusta escribir documentación. Muchos programadores harán todo lo posible para evitar leer un documento a fondo.

No se concentre en la escritura, concéntrese en la lectura. Cuando los programadores lean la documentación y asimilen cosas de ella, verán el valor y estarán mucho más inclinados a escribir algo.

Joeri Sebrechts
fuente
-1

Cuando comencé mi trabajo actual y asumí un proyecto de hardware + software de las personas que anteriormente habían estado trabajando en él, me dieron un documento de más de cien páginas que describía el sistema. Debe haber tomado días para producir. Lo miré tal vez dos veces. A pesar de la gran cantidad de información allí, rara vez respondía las preguntas reales que tenía sobre el sistema, e incluso cuando lo hizo, fue más rápido mirar el código.

Después de suficientes experiencias como esa, empiezas a pensar, ¿por qué molestarte? ¿Por qué dedicar su tiempo a responder preguntas que la gente nunca hizo? Empiezas a darte cuenta de lo verdaderamente difícil que es predecir qué información buscarán las personas en la documentación; inevitablemente está lleno de hechos que resultan inútiles, poco claros u obvios, y que carecen de las respuestas a las preguntas más apremiantes. Recuerde, producir documentación útil es un esfuerzo para predecir el comportamiento humano. Así como es poco probable que el diseño de una interfaz de usuario tenga éxito antes de que haya pasado por múltiples iteraciones de pruebas y depuración, es ingenuo pensar que es posible escribir documentación útil basada solo en las expectativas de cómo las personas interpretarán el sistema y qué papel que desempeñará la documentación y su lenguaje en esa interpretación.

Tiendo a pensar que la mayor parte de la presión para escribir documentación se debe al hecho de que es una tarea desagradable y a la gente le gusta culparse mutuamente por hacer tareas desagradables ("¡No te has comido tu filboid studge!").

SIN EMBARGO

No creo que la documentación sea, en todos los sentidos, inútil. Creo que es inútil principalmente cuando las personas ven la documentación como esta carga adicional que debe cumplirse antes de que se termine un trabajo, como un último trabajo de limpieza que debe apresurarse y como una casilla para verificar. La documentación es algo que debe trabajar en los aspectos de su día que siempre hace de todos modos. Creo que el correo electrónico es una forma particularmente buena de hacer documentación. Cuando agregue una nueva función, escriba a algunas personas un correo electrónico rápido diciendo qué es. Cuando dibuje un nuevo esquema, genere un PDF y envíelo a cualquier persona que pueda estar interesada. Las ventajas del correo electrónico son:

  1. La gente generalmente revisa el correo electrónico, mientras que nadie navega por una carpeta llamada "doc".

  2. El correo electrónico existe en contexto, rodeado de otros correos electrónicos que discuten la característica y las características relacionadas y todo lo que estaba sucediendo en ese momento.

  3. El correo electrónico es corto y enfocado y tiene una línea de asunto.

  4. El correo electrónico permite a las personas que se preocupan hacer preguntas de inmediato,

  5. El correo electrónico es altamente buscable, porque la gente lo usa para todo y los clientes de correo han avanzado bastante con los años.

  6. Si está en un correo electrónico, al menos otra persona sabe dónde encontrarlo.

En teoría, debería parecer que los comentarios en código también deberían ser "aspectos de tu día que siempre haces de todos modos", pero para ser sincero, nunca leo comentarios en código. No estoy seguro de por qué, pero simplemente no son muy útiles, tal vez porque hay una falta de contexto, que el correo electrónico resuelve.

Owen
fuente
a excepción del n. ° 4 ("personas que se preocupan por hacer preguntas de inmediato"), ninguno de los beneficios de correo electrónico que usted enumera ha funcionado de manera confiable para mí. 1: las personas tienden a ignorar el correo electrónico, cuando hay mucho de él 2: el correo electrónico con frecuencia tiende a perder contexto, enterrándolo en cuestiones secundarias y citando en exceso 3: los correos electrónicos son demasiado largos / largos y tienden a perder el foco a medida que avanza la discusión más problemas secundarios y líneas de asunto a menudo son irrelevantes / obsoletos ("Re: ¿WTF sucedió en el servidor hoy?") ...
gnat
... 5: La búsqueda de correo electrónico se ve altamente comprometida por la capacidad de eliminar correos, una característica que tiene cualquier administrador de correo decente y cualquier usuario de correo activo, utiliza mucho 6: vea 5, si se elimina el correo, nadie podrá encuéntrelo (lo único en lo que puedo confiar es en buscar mis correos enviados y esto es solo porque trato de no eliminarlos). Aparte del elogio por correo electrónico (que me parece bastante injustificado), sin embargo, usted hace algunos buenos
comentarios
@gnat Supongo que puede variar de una compañía a otra sobre la eliminación. En mi empresa, guardamos todos los correos electrónicos, además de los archivos de todos los correos electrónicos de empleados anteriores, y cada vez que una nueva persona comienza una tarea, reenviamos a esa persona todos los correos electrónicos relacionados. Supongo una diferencia de estilo.
Owen
Sí, eso depende mucho del estilo / cultura. Si bien la "lucha contra la eliminación" es factible (e incluso técnicamente simple de lograr mediante la exportación de hilos de correo a algún servidor), cosas como mantenerlos enfocados, líneas de asunto relevantes, las citas limitadas a límites razonables es algo muy cultural, que requiere mucho esfuerzo y determinación (y soporte de gestión) para mantener ... En comparación con este esfuerzo, y especialmente con la necesidad de la compra de mgmt, mantener cosas como wiki / comentarios de código / carpetas de documentos puede resultar más fácil
mosquito