capitulo-01.md

Capítulo 1: Documentación

Este primer capítulo trata el tema más importante en el trabajo de un Administrador de Sistemas la documentación.

Documentación

• Documentar absolutamente todo el trabajo realizado.
  • Mantener un registro diario de las actividades.
    • Utilizar al menos un archivo de texto plano.
    • Guardar la fecha para cada entrada.
      • Cuidar la ortografía aunque ningún colega o superior tenga acceso a la documentación. Tener una buena ortografía es una característica destacable en toda persona, especialmente en un profesional.
      • Este registro está principalmente destinado a uno mismo:
        • Es nuestra propia FAQ.
        • Es nuestra colección de tutoriales para ayudarnos y ayudar a otros a reproducir en un futuro un mismo trabajo sobre un sistema diferente.
          • Al momento de documentar una tarea es necesario preguntarse si es suficiente información para que otros puedan reproducirla.
        • Este documento puede crecer mucho al pasar el tiempo, por lo que se debe considerar rápidamente utilizar un mejor sistema de documentación, preferentemente una wiki (mejor escalable considerando que nuestro equipo puede crecer y se puede necesitar una herramienta de edición colaborativa), un blog, o ambos.
      • Este documento tiene que ser resguardado periódicamente de forma segura.
        • Algunos administradores guardan notas en papel, algo totalmente arcaico y opuesto a la tecnología con la que trabajan.
        • Si el registro/log/documentación se encuentra en un servidor corporativo dentro de una red privada y se necesita información vital estando a kilómetros de distancia, estaremos en problemas. De ser posible (siempre que no incluya información sensible/confidencial) debe ser accesible desde cualquier ubicación.
    • Utilizar comentarios en archivos de configuración para documentar los cambios.
      • Agregar una identificación del administrador (nombre) y fecha en los comentarios para saber con exactitud quién y cuándo realizó un cambio en la configuración.
• En general, debemos ser metódicos y organizados.
  • Este puede que sea uno de los aspectos más difíciles de alcanzar pues es una característica propia de la personalidad y carácter de cada persona.
  • Ya sea para organizar la jerarquía de directorios de nuestro $HOME o nuestra documentación, debemos mantener un orden y "limpieza digital".
  • Un SysAdmin bien organizado está mejor preparado para enfrentar situaciones adversas.
• Aprovechar el uso de la tecnología para documentar.
  • Configurar un sitio Web o FAQ (wiki, blog, etc.)
  • Hacer un uso intensivo de las imágenes y capturas de pantalla en la documentación (siempre que corresponda).
  • Utilizar medios enriquecidos (video) siempre que sea posible.
• Recordar y resguardar enlaces a todas las fuentes de información valiosa.
  • Para cada entrada, agregar todas las fuentes de información que nos ayudaron a resolver una tarea (y si es posible, guardar una copia).
  • Mantener un registro centralizado (y accesible desde cualquier parte) de fuentes de información valiosa (sean tutoriales, manuales, FAQs, guías, wikis, listas de correo, foros, etc.) organizado por tópicos y tecnologías.