Posted by Después de haber trabajado en equipos de Db2 DBA, principalmente en funciones de consultoría, el valor de una buena documentación es enorme. Esto me queda claro una vez más al empezar a trabajar en una nueva empresa. La documentación aquí es excelente y hace que poner en marcha a una nueva persona (¡yo!) Sea mucho más rápido.
Dónde documentar
Dónde crear la documentación es a menudo la primera pregunta. Mi herramienta de documentación favorita es Confluence. Me parece flexible y fácil de usar, con mucha documentación disponible en línea sobre cómo usarlo de manera efectiva. Es excelente para equipos que comparten documentación así como la creación y el mantenimiento de dicha documentación. También he trabajado con Microsoft Sharepoint, y también es decente. Incluso puede usar documentos de Google o una carpeta en una unidad compartida. La conversión entre ubicaciones lleva mucho tiempo, pero es mucho más fácil que no tener documentación.
Qué documentar
He visto ambos extremos del espectro de documentación. He visto clientes sin documentación, donde todo el conocimiento está en la cabeza de alguien. También trabajé con un cliente que exigía tener documentación de cada parámetro de configuración para cada base de datos. No me gusta ninguno de los extremos del espectro. En un extremo, no hay ningún lugar para comenzar, y en el otro extremo, se dedica demasiado tiempo a documentar cosas que probablemente cambien.
La virtud, como siempre, está en el medio. Documentar los nombres de servidores, direcciones IP, nombres de instancias, puertos y nombres de bases de datos es realmente lo mínimo indispensable. Además de eso, tiene sentido documentar cualquier procedimiento personalizado. También me gusta la documentación de las mejores prácticas de Db2 / base de datos organizativas: ¿cuál es el diseño estándar de su sistema de archivos, los valores críticos de documentación, dónde se almacenan los scripts de mantenimiento, qué hacen sus scripts de mantenimiento, cuáles son sus planes HA y DR? Este es un gran recurso para quienes son nuevos en la empresa, y también para que usted pueda comparar sistemas con sus propios estándares y mejores prácticas.
No me gusta documentar todos los parámetros de configuración de la base de datos y del administrador de la base de datos, sin embargo, si está utilizando un administrador de configuración, podría hacerse. Por lo general, no vale la pena documentar las cosas que pueden cambiar.
Cómo documentar
Una vez que sepa qué documentar y dónde documentarlo, hay varios elementos que debe tener todo buen documento. Me gusta llevar un registro de cambios cerca de la parte superior de cualquier documento, incluso los que están en sistemas que lo ayudan con la gestión de cambios como Confluence. Esto le permite ver quién actualizó un documento y cuándo, y una descripción general de sus cambios. Aquí hay un ejemplo de uno para un documento en el que he estado trabajando últimamente:
También hacia la parte superior de un documento, es importante tener en cuenta el propósito del documento en una o dos frases. He aquí un ejemplo:
También es importante tener en cuenta a quién va dirigido el documento. Un documento se escribe de manera diferente si está dirigido a otros DBA, administradores de sistemas, desarrolladores, directivos o usuarios. Aquí va otro ejemplo:
Soy un gran admirador de incluir una tabla de contenido para cualquier documento más largo que una sola pantalla de datos. Por ejemplo así:
El meollo del documento debe estar bien organizado y separado con encabezados de sección y encabezados de subsección. Esto hace que la sección de la tabla de contenido sea fácil de generar en Confluence, Google Documents o MS Word.
Y al final de cualquier documento, tiene sentido incluir enlaces a referencias útiles u otros documentos relacionados. Por ejemplo así:
El uso de estructuras de metadatos disponibles también ayuda. La categorización o el etiquetado de documentos no parece ser un gran problema cuando solo tiene un puñado de documentos, pero si hay más de 20 documentos ó tres personas trabajando en las mismas cosas, es probable que le resulte más fácil encontrar lo que necesita.