Modelo de Documentación

Modelo de Documentación

Esta página define el formato recomendado para la documentación de las notas de instalación y configuración.

Propósito

el propósito de estas notas NO es repetir documentación de instalación y configuración que puede encontrarse en otro lado, seguramente mejor armada y más completa. El propósito de estas notas es reunir en forma clara y concisa lo necesario para efectuar una tarea. Muchas veces la documentación es extensa, y a veces compleja. Lo que se busca en estas notas es describir los pasos necesarios para realizar una tarea, de modo que dicha tarea pueda realizarse sin tener que consultar otras fuentes. Las notas de este wiki deben haber sido verificadas: alguien debe haber seguido estos pasos y verificado fehacientemente que la tarea quedó cumplida en forma correcta y completa.

Estructura

Cada página debe contener estas secciones:

• Borrador: notas informales de administración aportadas por el docente del curso, o tomadas de alguna otra fuente para tener como punto de partida. Esta sección debe desaparecer una vez que su material haya sido incorporado al resto de las secciones de la página.
• Objetivos: qué se quiere lograr.
• Software: qué paquetes son necesarios, dónde se encuentran.
• Conceptos, comandos, archivos: conceptos generales, los comandos relacionados con el tema, los archivos de configuración usados para esta tarea.
• Procedimientos: los pasos necesarios para lograr los objetivos.
• Verificación: qué debe hacerse para comprobar fehacientemente que los objetivos han sido cumplidos en forma correcta y completa.
• Notas adicionales: todo lo que se considere de interés pero no corresponda a las secciones anteriores.
• Referencias: las fuentes de información utilizadas.

Cualidades

Una buena documentación debe ser:

• completa: no debe faltar nada de lo necesario para realizar la tarea.
• adecuada: no debe contener información no necesaria para ejecutar la tarea, ni información que está bien explicada en otro lado.
• clara: que se entienda.
• concisa: redactada con las palabras justas, sin que parezca una larga conversación ni que parezca un mensaje cifrado.