Documentación: ¿es una parte asumida del trabajo? [cerrado]

Entonces, los altos mandos me dijeron que un ingeniero de software que dejó la empresa no documentaba sus procesos y debería haberlo hecho como parte de sus funciones. Mi reacción visceral fue decir: "no obtienes lo que no pides", esto es más un problema de gestión de proyectos. Las estimaciones dadas fueron para "desarrollar una pieza de software que funcione", y nunca hubo ninguna discusión sobre la documentación.

¿Es justo suponer que todos y cada uno de los desarrolladores deben ser responsables de crear la documentación, incluso cuando no se menciona explícitamente como entregable?

¿Documentación de código o documentación de usuario? Algunos creen en el código autodocumentado.
Supongo que enviar código a un repositorio, enviar actualizaciones de estado periódicas y otras cosas inútiles tampoco se mencionaron explícitamente como entregables. En serio amigo, ¿dónde estudiaste Ciencias de la Computación?
Respondí asumiendo la documentación del usuario. La documentación en código no debería ser un requisito ya que la gente de negocios no debería decirle a los programadores cómo hacer su trabajo.
Si algo no es un entregable, ¿cómo puede alguien pedirlo?
Entonces, seguro que dijeron "no documentó sus procesos". Procesos es vago. Esperaría que el código, como mínimo, tuviera alguna documentación en línea. Si nada más que una descripción de función, clase, ....
Procesos como "qué hacer cuando vencen los certificados", o "cómo mover el sistema de aceptación a producción" o "cómo ejecutar un script de importación"
Si se trata de "procesos", entonces diría que no son entregables estándar a menos que se llamen. Si querían decir todo eso por "trabajar", entonces eso es una exageración.
@ user1220, las cosas que cita son esenciales para mantener el sistema en funcionamiento. El mandato de "hacer que funcione" se extiende más allá de los primeros cinco minutos de la implementación y, al no preguntar si estaba documentado, varias personas fallaron en el trabajo. Use este incidente para diferenciarse: aliente a los superiores a dejar un presupuesto para la documentación (o la automatización de la implementación) y demuestre que está abordando algo que anteriormente era un problema.
Puede o no ser su responsabilidad escribir la documentación formal. Es su responsabilidad preguntar qué documentación esperan y luego entregarla. Se utiliza cierto nivel de documentación en casi todos los talleres y rara vez se solicita específicamente como parte de los requisitos, a menos que tenga un requisito legal porque es una política general, no específica para cada tarea. De esta manera, es como la revisión de código o el uso de control de código fuente, que también rara vez se especifican por tarea. Debería preguntarse cuál es la política de documentación en su primera semana en un trabajo y luego debería seguirla.
Señalaré que TODAS nuestras estimaciones de tiempo incluyen tiempo para producir la documentación necesaria y la suya también debería hacerlo una vez que sepa lo que se considera necesario. También señalaré que nada matará una buena reputación con sus compañeros más rápido que dejar un trabajo y nadie puede averiguar qué hacen sus cosas o dónde están o incluso en qué estado estaban. para averiguar lo que debería haber documentado mucho después de que se fue y cuando vean su nombre en el futuro cuando se entreviste con sus empleadores actuales también.
La mayor "pista" de la pregunta es que se refirió al desarrollador como un "Ingeniero de software". Eso implica cierto nivel no solo de seguir buenas prácticas de desarrollo de software, sino también buenas prácticas de "Ingeniería". Parte de ser un buen ingeniero es documentar lo que ha hecho, cómo lo hace, cómo se puede repetir, cuáles fueron los resultados, etc. Si bien depende de la compañía, casi siempre si el título tiene "Ingeniero" entonces la documentación y la aplicación sistemática de los procesos definitivamente deben considerarse como una expectativa. La codificación es solo una pequeña parte del desarrollo de software.
Mi regla general es que si tengo que preguntar cómo hacer algo más de una vez, entonces debe documentarse. No es necesario que sea siempre extravagante, un simple archivo de texto de "instrucciones" puede ser suficiente. Estos documentos son muy útiles para aquellas tareas que solo se realizan cada uno o dos años.

Respuestas (3)

El trabajo de un desarrollador de software no es simplemente escribir software que funcione, sino escribir software que funcione y sea mantenible.

Diferentes organizaciones y personas pueden tener diferentes puntos de vista sobre lo que significa mantenible, pero si usted es parte de una empresa que considera que la mantenibilidad es un código altamente documentado, completamente probado por unidad, entonces su trabajo es escribir software que funcione, esté altamente documentado (se requiere para sus empresas). estándar) y completamente probado por unidad.
Para eso te contrataron, no para desarrollar código a tu manera personal.

Si se requieren procesos específicos para que su trabajo sea transferible a otros, es razonable que una empresa espere que los documente . De lo contrario, ¿cómo afrontarán el hecho de que te enfermes o te atropelle un autobús ? por ejemplo.

Sin embargo, si no se solicitó o no se describió en los procesos o la capacitación de la empresa, ¿cómo se supone que debe saberlo? Depende de la empresa establecer expectativas.
@JonStory Si lo contratan como graduado universitario, entonces estoy de acuerdo. Se espera que alguien más senior sepa mejor. ¡Ciertamente no le gustaría contratar a un CEO que dice que no presentó la información financiera de la empresa a los accionistas porque nadie le dijo que lo hiciera!
Veo tu punto, pero no estoy seguro de que sea equivalente.
He trabajado en empresas en las que los colegas han guardado información para sí mismos como una forma de volverse más valiosos para la empresa. Está incorrecto. Si se requieren procesos específicos para que su trabajo sea transferible a otros, es razonable que una empresa espere que los documente.
Dada la elección entre un sistema de trabajo y documentación, la mayoría de la gente elegiría el primero y se olvidaría del segundo. No lo pides, no lo obtienes, como yo lo veo.
La documentación es una de esas cosas que creo que es una ocurrencia tardía en el mejor de los casos. Intento documentar mi código y produzco guías técnicas de mi trabajo para mis clientes, con información como depuración, solución de problemas, cómo funciona, capturas de pantalla, cómo interactuar con él y, finalmente, un enlace al código en sí y Datos de contacto.
@Rob: ¿pero lo ve como su obligación profesional o está cumpliendo con una solicitud de entrega?
La mayoría de la gente elegiría la salida de un sistema en funcionamiento. Por otro lado, la mayoría de la gente también elegiría trabajar en un sistema bien documentado que en uno que funcione. Los desarrolladores deben dejar de ser tan egoístas.
¿Egoísta? No depende de ellos. Ellos no son los que dictan lo que es o no es un entregable.
Es egoísta en el sentido de que los desarrolladores están demasiado interesados ​​en hacer que algo funcione sin tener en cuenta qué tan mantenible o intuitivo es su código. Eso es solo tratar de hacerlo lo más fácil posible para ti.
Mantenible o intuitivo no tiene nada que ver con la documentación. Puedo construir un sistema fácil de mantener con código intuitivo sin ninguna documentación de respaldo.
¿Puede escribir un sistema que los usuarios, desarrolladores, probadores y soporte puedan entender, usar y mantener fácilmente sin tener ningún tipo de documentación? En ese caso, usted es probablemente el único desarrollador que he conocido o del que he oído hablar en mi carrera de 10 años que puede hacerlo.
Entonces, ¿es la documentación lo suficientemente importante como para ser un entregable explícito y, como tal, solicitarse y asignarse en el tiempo adecuado?
Es su deber, diría yo, averiguar qué nivel de documentación requiere una empresa y luego asignar el tiempo que necesita para completarla.

La respuesta a su pregunta es específica de la empresa. Le habría dicho que consultara con su gerencia, excepto que su gerencia ya se lo dijo a quemarropa.

Hay muchas formas de documentación: documentación a través de Test Driven Development (TDD), documentación formal, comentarios, documentación a través de código, etc. Debe definir con su gerencia el tipo de documentación que están buscando y el estilo de esta documentación. no se sale con la suya documentando de la forma que desee.

Eso depende.

Si el software se lanza como una API para que lo usen otros programadores (incluso internamente), debe proporcionarse algún tipo de documentación/guía de usuario. Eso podría no ser documentación formal. Podría ser solo un correo electrónico con algún código de ejemplo. Pero ese tipo de soporte al cliente es necesario ya que el código es el producto en ese caso.

De lo contrario, si las personas involucradas (o la industria misma) son mayores, entonces la expectativa de documentación es justa.

Antes del advenimiento de la metodología de desarrollo ágil, la documentación formal era una parte clave del proceso. Las industrias más formales (médica, bancaria, gubernamental) o las industrias que se mueven más lentamente (manufactura, por ejemplo) todavía hacen uso de la documentación. Además, las personas que aprendieron sobre el desarrollo de software antes de Agile pueden esperar que la documentación sea parte del curso.

Pero casi todos los demás deben estar familiarizados con las prácticas modernas de desarrollo de software que tienden a evitar la documentación. No es razonable suponer que el desarrollador producirá documentación sin preguntar.

Aunque, como dices, es bastante trivial incluir eso explícitamente como requisito. En caso de duda, comuníquese.

Sí, comunicarse. Hazlo explícito, no hace falta mucho. No lo tomes como un hecho.
Documentar "Código" y documentar "Procesos" son 2 temas diferentes. Claro, usted sabe cómo realizar una compilación desde cero de su sistema hoy, pero dentro de 6 meses, cuando haya estado trabajando en un proyecto diferente, ni siquiera sabrá por dónde comenzar (o peor aún, su reemplazo en el proyecto anterior no sabrá por dónde empezar). Y ciertamente no podrá duplicar el proceso de manera confiable a menos que haya documentado ese proceso. Es posible que se acerque, pero con demasiada frecuencia se olvidará de esa pequeña configuración o controlador para instalar.
Documentación: ¿es una parte asumida del trabajo? [cerrado]
RespuestasAquíPolítica de privacidad1y, 0v