Contents
Que es?
El escribir Buena documentacion es esencial en el exito de cualquier poryeto de software: la calidad de esta documentacion puede ser mas importante que la calidad del codigo en si. phpDocumentor esta diseñado para facilitar el porceso de documentacio. phpDocumentor incluso hace posible el generar paquetes separados de documentación desde el mismo codigo fuente.
Considerando la Audiencia
¿La primera pregunta que cualquier escritor debe hacer es Quién es mi público? Esto contestará muchas preguntas. Sólo se piensa que el software es usado para más software, como cualquier producto de MS. Los programadores son las únicas personas que tienen el acceso al código de la fuente. El desafío en este caso es escribir la documentación buena para los fin-usuarios.
Al escribir la documentación para un proyecto de fuente abierta se piensa que ambos son usados extendidos, este desafío se magnifica por el hecho de que muchas personas también pensarán en extender la fuente, o incluso el hallazgo de errores y su reparacion. Estos dos públicos cuidan ser opuestos a nosotros en sus necesidades. Un usuario final generalmente quiere:
- el estilo de las instrucciones escritas, eso explica y describe los conceptos generales más de cómo una variable particular se usa
- La información de la interfaz , ningún detalle de bajo nivel
- Los ejemplos de cómo usar, y guías didácticas
Considerando que un programador además puede querer:
- Los detalles en cómo programa los elementos actúan recíprocamente, qué elementos usan otros
- Donde en el código de la fuente una acción o serie de acciones ocurren
- Cómo extender el código para agregar la nueva funcionalidad
Estos dos tipos de usuarios no pueden ser reparados por sólo documentación del API o sólo guías didácticas, pero una mezcla sutil de los dos.