USER
Elabora 3 pregunta de respuesta múltiple para un cuestionario a partir de la siguiente información. La información del curso es la siguiente: "Documentación del proyecto
La documentación de un proyecto es
de vital importancia para su éxito.
Desde la fase de diseño, como parte
de la propia arquitectura del
proyecto, deberemos definir y
escoger el sistema de documentación
que usaremos para el proyecto.
Documentación del proyecto. Factores
Formatos de los documentos, según su tipología y métodos de acceso.
Definir los formatos y plantillas elegidos para los diagramas de diseño, hojas de cálculo,
hojas de seguimiento del proyecto, documentos que registren fallos o cambios en las
especificaciones durante el desarrollo, documentos que definan la interfaz de usuario,
etc.
Método de acceso y flujo de trabajo de cada tipo de documento.
Quién va a tener acceso a los diferentes tipos de documentos y bajo qué privilegios.
Dónde se van a notificar los cambios que se realicen (¿en el propio documento?, ¿en
un sistema de control de versiones?).
Documentación. Código fuente del proyecto
En el caso de la documentación del propio desarrollo, conviene estudiar las
herramientas que nos ofrezca el propio lenguaje para generar la
documentación. (por ejemplo, javadoc)
Debido a la existencia de herramientas de generación de documentación a
partir del código fuente y comentarios insertados mediante una sintaxis
determinada que van a ayudar mucho en el proceso.
Documentación. Decisiones relevantes
En el momento de tomar decisiones de formato y flujos de trabajo sobre la
documentación,
es de vital importancia tener en cuenta los estándares de formatos de documento
existentes,
evitando los formatos propietarios sobre todo en organizaciones heterogéneas donde
convivan distintos sistemas operativos o en proyectos de software libre,
para dar a la documentación la mayor accesibilidad posible.
Suele ser una buena decisión escoger un formato de documentación
fácilmente convertible a otros (p.ej., XML) y así poder disponer de la
documentación en HTML para su consulta rápida, en PDF para agregar a la
documentación del proyecto, etc.
Sistemas de creación de documentación
Premisas
Un sistema o software pobremente documentado carece de valor aunque
haya funcionado bien en alguna ocasión.
En el caso de programas pequeños y poco importantes que sólo se utilizan
durante un corto periodo de tiempo, unos cuantos comentarios en el código
podrían ser suficientes.
No obstante, la mayoría de los programas cuya única documentación es el
código no tienen aceptación y es imposible mantenerlos.
Dedicar un poco de esfuerzo a la documentación, incluso dentro de los límites
de un pequeño proyecto, constituye una muy buena práctica.
Premisas
Aprender a documentar software es una tarea
complicada y exige un criterio de ingeniería maduro.
Documentar escuetamente es un error habitual,
pero el otro extremo puede resultar igual de
perjudicial: si escribe documentaciones extensas,
éstas atosigarán al lector y constituirán una carga a
la hora de mantenerlas. Es esencial documentar sólo
los asuntos correctos.
La documentación no sirve de ayuda para nadie si su
extensión desanima a la gente a la hora de leerla.
Documentación del software
Documentación del software. Tipos
La documentación del software está dividida
en distintos tipos de acuerdo a lo que ella
documente generalmente existe:
1) Documentación de desarrollo
2) Documentación de programa
3) Documentación de usuario
Documentación del software. Tipos
Documentación de desarrollo
• Análisis, requisitos, especificaciones
• Diagramas
• Comentarios en códigos
• Documentación de pruebas, etc.
Documentación de programa
• Ayuda en línea
• Páginas de manual
Documentación de usuario
• Manual de uso
• Libros y tutoriales
• Guías de enseñanza o autoaprendizaje
Documentación del software
La documentación del software es que la
misma debe acompañar el desarrollo o
evolución del software que documenta.
De la misma forma que el software
avanza y se desarrolla, la documentación
debe avanzar y desarrollarse
conjuntamente, de manera que la última
versión de la documentación refleje las
características y el estado de la última
versión del software
Licencias o copyright
La documentación que acompaña al software resulta, al igual que éste, en una
producción del intelecto humano, por lo cual le son aplicables las leyes de
derechos de autor o de copyright.
Por este motivo, para poder copiar, modificar o distribuir la documentación, es
necesario tener el permiso del autor de dicha documentación o tener un
documento que le otorga estos permisos.
Este permiso se corporiza en una licencia para la documentación.
Formatos libres y propietarios
Tan importante como tener las libertades para la documentación, es
documentar en formatos libres.
De manera que, una vez que su documento llegue a los lectores, pueda ser
accedido, modificado y vuelto a distribuir con todas las libertades, sin
depender de restricciones impuestas al software de acceso o modificación.
Esto se logra documentando en formatos libres.
Herramientas de control y administración
de versiones
Cada nueva versión del software le corresponderá una nueva versión de la
documentación.
Al menos, la documentación deberá indicar a qué versiones del software le
son aplicables las distintas opciones documentadas.
Se utilizan distintas herramientas que permiten controlar y versionar la
documentación en forma cooperativa y automática. Herramientas estilo
subversión, git, SourceSafe, etc
Además, se han desarrollado algunos sistemas de documentación cooperativa
en línea que permiten un trabajo eficaz en grupos de autores que trabajan
simultáneamente. (soluciones de google).
Tex y LaTex
TeX es un programa de Donald E. Knuth, que está orientado a la composición
e impresión de textos y fórmulas matemáticas.
LaTeX es un paquete de macros que permite al autor de un texto componer
e imprimir un documento con calidad, empleando patrones definidos.
Originalmente, LaTeX fue escrito por Leslie Lamport y utiliza TeX como su
elemento de composición.
LaTeX es una potente herramienta de procesamiento de textos científicos que
aún no ha sido sustituida por los modernos editores de texto en el mundo de
las editoriales científicas y académicas.
Documentación de código fuente
Elementos para la selección
Licencia
Costo
Fecha de creación y mantenimiento
Sistemas operativos
Lenguajes soportados
Formatos de salida
Formatos de entrada
Wiki Interesante
Comparativa de
generadores de
documentación
Comparativa de generadores de documentación
https://es.wikipedia.org/wiki/Anexo:Comparativa_de_generadores_de_documentaci%C3%B3n
Doxygen
Doxygen es un sistema de documentación para códigos fuente de programas
escritos en una variedad importante de lenguajes, entre los que se encuentra:
C++,
C,
Java,
Objective-C,
IDL (Corba),
PHP,
C# http://www.doxygen.org/
Doxygen
Genera documentación para ser publicada en Internet
o para ser procesada con LaTeX.
También puede generar salidas en formatos rtf,
postscript, pdf y páginas de manual (comando man) de
UNIX.
La idea detrás de Doxygen es documentar en el
propio código fuente, a medida que éste se escribe,
de forma tal que Doxygen extrae la documentación
del propio código fuente.
Doxygen fue creado bajo GNU/Linux y Mac OS X,
pero ha sido portado para la mayoría de los sistemas
UNIX y también para Windows.
Doxygen. Puesta a punto
Utiliza un archivo de configuración para determinar cómo debe procesar la
documentación.
Cada proyecto deberá tener su propio archivo de configuración que entre
otras cosas incluirá qué código fuente debe ser analizado, qué directorios, etc.
Existe una forma simple de crear una plantilla del archivo de configuración con
el comando:
doxygen -g archivo-config
Las versiones actuales de doxygen traen una utilidad llamado doxywizard,
que permite editar el archivo de configuración de una forma gráfica.
Doxygen. Puesta a punto
Para un proyecto pequeño constituido por una fuente en C o C++, no es
necesario hacer modificaciones, ya que doxygen buscará los archivos de
fuentes en el directorio actual.
Para generar la documentación basta con ejecutar el comando:
doxygen archivo-config
Documentando en los códigos fuente
Documentando en los códigos fuente
La documentación dentro de los códigos fuente debe ser realizada dentro de
bloques especiales de texto que puedan ser reconocidos por doxygen y a su
vez no interfieran con el compilador del lenguaje.
Dentro de cada bloque de documentación existen dos tipos de descripciones,
que juntándolas se crea la documentación:
descripción abreviada
descripción detallada
Documentando en los códigos fuente
Para marcar un bloque como una descripción detallada, como por
ejemplo, utilizando el estilo JavaDoc, que es un formato de bloque de
comentario tipo C, iniciando con un asterisco, como este ejemplo:
/**
* ... texto ...
*/
También es posible utilizar un formato de comentario tipo Qt, que es un
formato de bloque de comentario tipo C, iniciado con un símbolo de
exclamación, como por ejemplo:
/*!
* ... texto ...
*/
Documentando en los códigos fuente
En ambos casos anteriores, el asterisco intermedio es opcional, o sea, que se
puede aceptar:
/*!
... texto ...
*/
Documentando en los códigos fuente
Una tercera forma de marcar un bloque es con la notación de comentario de
C++, que se individualiza con una barra adicional:
///
/// ... texto ...
///
o también
//!
//! ... texto ...
//!
Documentando en los códigos fuente
Para individualizar la descripción abreviada, también existen varias
posibilidades de marcado.
Una forma es iniciar la línea con el comando
\brief
en alguno de los formatos de bloques detallados anteriormente, seguidos de
una línea en blanco:
/*! \brief Descripción abreviada.
* Continuación de la descripción abreviada.
*
* ... texto ...
*/
Documentando en los códigos fuente
Si el archivo de configuración se configura con la opción
JAVADOC_AUTOBRIEF en YES, es posible utilizar el estilo de bloques de
JavaDoc que automáticamente inicia la descripción abreviada hasta el próximo
punto seguido de un espacio o una nueva línea; como en este ejemplo:
/** Descripción abreviada que termina en un punto. Descripción
* detallada que comienza después.
*/
Documentando en los códigos fuente
Un tercer método para diferenciar los tipos de descripciones es utilizar un
comentario en formato C++ en una sola línea.
/// Descripción abreviada.
/** Descripción detallada */
o también dejando una línea en blanco entre una y otra descripción:
//! Descripción abreviada.
//! Descripción detallada
//! en más de un renglón
Documentando en los códigos fuente
En este último caso tendrá que tener explícitamente indicado
JAVADOC_AUTOBRIEF en NO para que sean propiamente detectadas las
descripciones.
Esto muestra como doxygen es flexible para adaptarse a los formatos de
comentarios de cada uno de los desarrolladores de software.
33
Documentando. Resumen
/**
... texto ...
*/
/*!
... texto ...
*/
///
/// ... texto ...
///
//!
//! ... texto ...
//!
Documentando. Resumen
\file
\var
\fn
\param
\return
\brief
\defgroup
\ingroup
\author
\date
\mainpage
\n
\htmlonly
\par
\verbatim
\see
Ejemplo
/** @file
* \brief Este archivo es de ejemplo
*/
/** \fn void func (char c)
\param c carácter
@return nada.
*/
void func (char c) {
int i;
c = (char) i;
return;
}
Conclusiones
Los sistemas de documentación permiten tener una idea de las características
generales de cada uno de ellos y son una breve guía para poder construir un
documento básico utilizando las herramientas descritas;
Dependerá ahora de ustedes profundizar en el o los sistemas que considere
más apropiados para obtener un conocimiento completo de ellos"