Cómo hacer cumplir la documentación del software del proyecto para que sea más fácil para los desarrolladores de software entrantes

¿Es esto lo que la gente llama golpear a un caballo muerto ?

Últimamente, hay una nueva generación de gerentes de ingeniería que creen que la documentación es inútil. No estoy en desacuerdo con ellos.

Sin embargo, también en los últimos tiempos hay una nueva generación de gerentes de ingeniería que creen que es inútil llevar a cabo el diseño de software. Estos surgieron de las filas de los programadores PHP o Python cuya actitud es “solo git’r done”. Estos son pretenciosamente informados twits mal informados.

El estado mental más importante para un programador

  1. Es comprender las reglas de negocio y proceso del entorno para el que está codificando.
    1. Debe comprender el modelo de datos y el flujo de datos.
  2. Debe codificar en patrones. Debe poder reconocer un patrón de codificación o diseño cuando vea uno.
    1. Comentarios solo cuando innova fuera de un patrón.
    2. Es mejor que todo tipo de documentación.
    3. Esto puede ser muy duro para los nuevos programadores. Pero lo siento, esto es lo que tienes que aprender y acostumbrarte.
  3. Debe codificar funcionalmente. El módulo que está codificando
    1. Debe estar diseñado y especificado para proporcionar una función minimalista. Debe proporcionar la menor cantidad de funcionalidad posible, sin afectar el rendimiento de la aplicación en general.
    2. Tiene API como contrato autorizado. El módulo o la función hace exactamente lo que dice la API. Sin efectos secundarios,
      1. Sin manipulación de variables estáticas / globales.
      2. Las interfaces estáticas, globales, constantes son de solo lectura con sus propios contratos API.
      3. Toda la configuración de inyección también debe tener contratos especificados.
    3. No tiene transacciones bajo el mostrador ni comunicación oculta. Deben realizarse a través de canales aprobados y comprobables.
      1. la firma polimórfica habitual
      2. un bus de mensajes, canal o cola, con especificación contratada para solicitud-respuesta o suscripción.
      3. Un modelo de evento contratado.
    4. No deben depender de la retención del estado.
      1. Cualquier comportamiento dirigido por el estado debe diseñarse como una máquina de estado.
      2. Incluso la máquina de estado en sí misma no debe depender de la retención de estado. Es decir, la respuesta de estímulo y la transición de estado siempre deben ser consistentes y no dependientes de un estado retenido.

Los módulos funcionales contractuales son muy útiles y ahorran tiempo, ya que un programador a menudo podría reutilizar un módulo fácilmente.

Lo que acabo de describir es la RESPONSABILIDAD de parte del programador.

Sin embargo, los gerentes de ingeniería y arquitectos lamentablemente no cumplen con su parte de RESPONSABILIDAD.

  1. No practica ni comprende el concepto de normalización del modelo de datos.
  2. No tiene una perspectiva integral y modular del flujo de datos entre los actores / actores, procesos y entidades involucradas.

Todo el mundo sabe qué es la normalización de datos, ¿verdad? Sabes cómo hacerlo para tus bases de datos. Pero, ¿normalizó los modelos de datos que pasan por todos los procesos, servicios y aplicaciones bajo su competencia?

La normalización del modelo de datos es el primer paso hacia el diseño funcional. La normalización del modelo de datos define los módulos y la granularidad de esos módulos.

  1. La normalización de datos garantiza la integridad de la unicidad. Hace exactamente lo que dice que hace con los datos.
  2. Evita la dependencia que un módulo tiene de un estado que se supone que no debe tener.
  3. Evita tener una funcionalidad duplicada y superpuesta, ya sea en servicios web o en funcionalidad de código.

¿Ni siquiera se dan cuenta de que un modelo de datos normalizado proporciona a sus programadores una comprensión completa de lo que necesitan hacer sin mucha documentación excesiva?

Deja de dibujar todos esos diagramas de cajas y rectángulos tontos. Simplemente arregle sus modelos de datos.

Una vez que tenga un modelo de datos normalizado, el programador podrá diseñar el diagrama de secuencia sin esfuerzo y luego con la API y las pruebas. No se necesita más documentación.

Contrata a un analista de negocios o promueve un desarrollador. Mi respuesta sonará un poco frívola, pero realmente es la respuesta correcta.

En serio, esta pregunta es hecha con frecuencia por personas que no son desarrolladores. La documentación es simplemente algo que los desarrolladores no quieren hacer. Solo provocará dolor, resentimiento y demoras en el proyecto si se lo solicita.

Conjuntos de habilidades. Los desarrolladores realmente no tienen estos conjuntos de habilidades. “Pero son tan inteligentes que esto debería ser fácil”, dices. Bueno, muchos desarrolladores no crecieron en un país que habla inglés o no está escrito de la manera que espera, por lo que simplemente los avergüenza. Los desarrolladores que han escrito en inglés desde que eran niños no desarrollaron habilidades de escritura a nivel universitario simplemente porque estaban hablando de clases de álgebra booleana en lugar de su clase de historia estadounidense. Por lo tanto, también los estás avergonzando.

Mentalidad Su soldado promedio sabría cómo cuidar a un bebé y la mayoría de las niñeras sabrán cómo lanzar una granada de mano. Si les pide que cambien de trabajo por un día, ambos serán infelices e improductivos. Así se sienten los desarrolladores cuando les pides que escriban documentación.

Otras tareas. Quizás lo más importante, habrá alguna tarea de codificación que desee que el desarrollador asuma y nunca la terminará de todos modos.

¿Quién debería hacerlo? La documentación es una tarea clave para los analistas de negocios, gerentes de proyectos, arquitectos y gerentes de desarrollo, así que pídales que se encarguen de esto. Seriamente.

“No hay atajo para el éxito”, dicen, en la misma nota, un proyecto solo puede tener éxito si está bien documentado desde el día 1.

La documentación debe comenzar desde la primera interacción para comprender el proyecto, es decir, la declaración del problema. Esto tiene que ser detallado y una solución propuesta para esto en igual detalle.

A partir de ahí, cada etapa del proyecto tiene su propio conjunto de documentos, consulte CMMi o PMP para obtener más detalles.

La conclusión es hacerla obligatoria y dedicar tiempo a la documentación tanto como priorice el desarrollo. Va a ser como gastos generales para el costo, pero es absolutamente necesario para ofrecer una buena calidad de manera efectiva.

Utilice la documentación del proyecto como un KPA para la evaluación, no se debe planificar ningún otro incentivo, debe convertirse en el producto de facto, solo ellos tendrán éxito.

En primer lugar, no hay dos roles iguales, tampoco para las empresas.

Hay muchos tipos diferentes de documentación.

En su mayor parte, los programadores deben tener una necesidad mínima de documentar en un mundo ideal.

Su documentación debe ser un comentario sobre su código de registro, comentarios en línea en una capacidad muy limitada y quizás comentarios de método.

Los documentos de diseño comercial deben ser manejados por un BA o gerente de proyecto, tal vez un escritor técnico si puede.

Cuando comience a hacer que los desarrolladores hagan la documentación, puede esperar que sea superior y limitada. Esto se debe a que los desarrolladores no están capacitados como escritores tradicionalmente y tienen poca experiencia en la creación de documentos sofisticados.

La documentación es importante, permite a los desarrolladores una lista de verificación para asegurarse de que sus diseños y código realmente estén haciendo lo que se espera. Sin embargo, pedirles que escriban sus discursos es como pedirle al taxista que te prepare un sándwich, tendrán que dejar de conducir y probablemente no será tan bueno como lo hace el tipo de Subway.


En pocas palabras, contratar a un escritor técnico.

Haga que una persona de control de calidad ISO 9001: 2000 del personal revise todo el código para asegurarse de que esté documentado.

Haga que esa persona sea responsable de toda la documentación. Haga que esa persona pueda eliminar codificadores que no cumplan con esto.

O para operaciones de menor presupuesto, solo asegúrese de que la documentación esté incluida en el alcance del empleo de un codificador.

More Interesting

¿Cuáles son algunos hábitos o prácticas sociales de los equipos de desarrolladores de software que son insultantes para las mujeres?

¿Cuáles son los principales malentendidos sobre el desarrollo de software?

¿Cuáles son las ventajas y desventajas de utilizar un equipo remoto para el desarrollo de software?

¿Qué parte de la Introducción a los algoritmos de Thomas Cormen debería ser capaz de comprender y utilizar para cuando termine mi BS en Informática?

Si Sundar Pichai estudió metalurgia en IIT KGP y una especialización en electrónica en Stanford, ¿cómo terminó en Google liderando el equipo de desarrollo de Chrome cuando ni siquiera tenía ningún conocimiento relacionado con el desarrollo de software en ese momento?

¿Puede un desarrollador de software entrar en un campo relacionado con negocios o comercio en la misma compañía?

¿Cuáles son las cosas que desearía haber sabido antes de su primer trabajo como desarrollador de software?

¿Cómo se mantienen actualizados los desarrolladores de software en la explosión de bases de datos "políglotas" y el espacio de marcos web?

¿Cuáles son algunas de las excelentes extensiones de Google Chrome que todo desarrollador de software debería saber?

Cómo llegar a Silicon Valley como futuro desarrollador de software

Cuando un desarrollador de software dice que una tarea no se puede hacer técnicamente, ¿qué haces?

Soy un desarrollador de software, ¿vale la pena hacer MBA, dado su costo?

¿Cuánto salario debo exigir como desarrollador de software de una agencia de viajes en línea (MNC) en Bangkok? Están ofreciendo 1400k baht tailandés anualmente.

¿Cuál es el mejor sitio independiente de subastas para desarrolladores de iPhone y Android?

¿Qué significa cada uno de estos términos: desarrollador de software, programador e ingeniero?