¿Qué nivel de documentación esperas que te proporcionen los desarrolladores?

El título lo dice todo.

A veces puede terminar que el desarrollo y la TI están en desacuerdo sobre este tipo de cosas. ¿Qué nivel de documentación espera cuando instala, repara, mantiene, inicia, detiene y diagnostica una solución que se ejecuta en uno o más servidores?

Todas estas cosas deben documentarse en detalle, aunque cuando la operación es estándar para el sistema operativo, el servidor de aplicaciones, el servidor web, etc., puede asumir las operaciones de TI que las personas saben cómo hacer eso.

Instalación: documente todo sobre cómo se instala y configura, incluso cómo saber si está funcionando correctamente.

Cuéntenos sobre la arquitectura, especialmente sobre la comunicación entre varios componentes de la solución (p. Ej., Rango de puertos; los mecanizadores de RPC a menudo usan un rango de puertos; necesitamos saber cuál es el rango y cuándo la aplicación podría quedarse sin puertos).

Aplicación de parches : documente cualquier cosa específica de la aplicación: lo que debe cerrarse antes de la aplicación de parches, y cualquier acción de seguimiento después de la aplicación de parches (cachés, índices, proxies que pueden necesitar ser borrados o reconstruidos).

Mantenimiento: documente cómo se ve la operación normal y anormal: qué colas y otras cosas deben monitorearse y cuál es el rango normal de estas.

Díganos cómo administrar los datos, especialmente las tablas y archivos que crecen sin límite (por ejemplo, archivos de registro e historiales de transacciones). ¿Cómo se deben purgar y cuál es el impacto de eliminar entradas antiguas? (sobre informes, etc.).

Díganos cómo llevar a cabo acciones estándar de administración de "negocios como de costumbre" / en la vida; esto podría ser agregar o modificar cuentas de usuario, por ejemplo.

Infórmenos sobre cualquier otra acción de administración regular que pueda ser necesaria (por ejemplo, qué certificados se usan y qué hacer cuando caducan).

Para todos los cambios, díganos cómo deshacerlos (no todos los cambios son exitosos). ¡Y cuéntanos que has probado los planes de reversión!

Diagnóstico: documentar los formatos y ubicaciones de los archivos de registro y CADA mensaje de error de la aplicación que podría aparecer, indicando qué significa que el mensaje de error salió mal y qué podría ser necesario cambiar para solucionarlo. Nunca use el mismo mensaje de error para dos eventos diferentes.

Derribado y encendido: cómo, en qué orden, cualquier procedimiento especial (por ejemplo, dejar que los servidores agoten las conexiones antes de apagarlas).

Estoy totalmente en desacuerdo con que la mejor manera de hacerlo es lanzar la aplicación por encima y dejar que la gente de TI resuelva lo que se necesita. La documentación operativa (y en general, las características de capacidad de administración de la aplicación) deben pensarse desde el principio.

Una pregunta de seguimiento sería: ¿qué sucede cuando (no si) los desarrolladores no proporcionan suficiente documentación?

Recomiendo que TI tenga la capacidad de ingresar informes de defectos en el software, utilizando cualquier sistema de seguimiento de defectos que utilicen los desarrolladores. De esa manera, si no le dijeron, por ejemplo, que los archivos en una carpeta en particular necesitan ser purgados, y que solo se debe mantener el valor de una semana, podría ingresar un defecto que diga "la aplicación llena el disco con archivos de registro ", y sugiero que trabajen con TI en una técnica documentada para purgar esa carpeta.

Mi lista de requisitos para la documentación sería (no en ningún orden específico):

(documentación sobre :)

• todos los interruptores de línea de comando
• todos los estados de salida y valores de retorno
• mensajes de registro (no tanto el contenido sino más bien explicando los campos si no es configurable)
• sintaxis de configuración
• cambia en los archivos de configuración
• uso de memoria
• ¿Está roscado o bifurcado?
• ¿Cuáles son las señales de reacción del servidor?
  • ¿hay alguna señal que no reinicie el servidor pero haga que vuelva a leer la configuración
  • como se comporta (¿Espera que los hilos / procesos existentes terminen con la configuración anterior? ¿Los mata, ...?)
• lo que sucede en el apagado no limpio (especialmente si se trata de algún tipo de servicio / servidor persistente)
• ¿Se registra a través de llamadas proporcionadas por el sistema o se registra con algo escrito por sí mismo ( qué asco para el registro de acceso y apache; claramente prefiero las herramientas integradas para el registro)
• IPv4 e IPv6 listos si es un servicio de red
• documentación en el tronco y documentación en una versión específica
  • nada es tan malo como configurar algo durante horas solo para descubrir que se ignorará porque la opción de configuración solo está disponible en el tronco
• qué opción de configuración es válida en qué versión (disponible desde: v1.0, en desuso desde: v1.2 o algo similar)

Documentación como esta son ejemplos de buena documentación:

• http://httpd.apache.org/docs/2.2/
• http://www.postgresql.org/docs/8.3/static/index.html

Consideraría que documentación como esta está llena de fallas:

• http://tomcat.apache.org/tomcat-6.0-doc/index.html

Además, el Manual de FreeBSD es un gran ejemplo de documentación y el enfoque de OpenBSD. Expulsan cosas que no están debidamente documentadas.

EDITAR: esta lista no está completa, es solo lo básico que me vino a la mente de inmediato. Además, la documentación debe ser legible, no solo algo que se lea como si alguien vomitara .

En resumen, espero la documentación que especifico y contrato.

Demasiadas veces este detalle crítico queda fuera de un acuerdo. El usuario final lo espera y lo quiere de forma gratuita, por supuesto. Los buenos desarrolladores corregirán esta supervisión al inicio del proceso y establecerán expectativas que incluyen un requisito de precio y tiempo.

Creo que TI necesita comunicarse con los desarrolladores qué tipo de documentación se necesita. La mejor manera de hacerlo es si el desarrollo ofrece versiones preliminares (o versiones iterativas) de una solución para que TI juegue y pruebe para que pueda responder con lo que se necesita.

Crear notas de lanzamiento adecuadas con una aplicación sería un buen comienzo. Si hay cambios en el comportamiento actual con la versión, cualquier nota del control de calidad sobre cambios en dependencias o comportamientos de inicio / parada, cambios en la carga a servidores o bases de datos dependientes, etc.

@Spoike (Todavía no puedo comentar las respuestas ...)

Los implementadores de TI (el rol variará según el tipo y el tamaño de la empresa) deben trabajar de manera consistente para lograr lo siguiente:

• Requisitos mínimos de instalación / rotación : en otras palabras, TI no puede ser pasivo y esperar que los desarrolladores "sepan" qué información se necesita en el momento de la instalación / rotación. He descubierto que a menudo hay una considerable confusión / desacuerdo en TI sobre lo que constituye la documentación adecuada de una aplicación. Dev entiende los requisitos (esperamos) y TI debe hacer una reunión para encontrar lo que, como mínimo, se requiere.

• Un procedimiento de instalación / rotación : en la configuración de la empresa, puede llamar a esto Control de cambio o gobernanza, pero es esencialmente un ciclo de revisión estándar en el que TI se sienta con la instalación superior Dev PRIOR para obtener una sesión informativa sobre el producto y sus necesidades.

Instalar una aplicación no es diferente a debutar una producción teatral. Antes de que se levante el telón, el director (desarrollador principal) se reúne repetidamente con el equipo de producción escénica (implementadores de TI) para asegurarse de que todo esté "justo" para la noche de apertura (la instalación pública).

No puede cambiar la persona de Dev (¿por qué querría hacerlo?), Pero puede señalar su objetivo compartido de una aplicación fantástica que se ejecuta a toda velocidad para todos los usuarios. Sus requisitos de documentación de TI de consenso son solo una de las cosas necesarias para garantizarlo.