http://barrapunto.com/preguntas/06/01/06/078239.shtml

¿Cómo documentar proyectos?
editado por Candyman el Viernes, 06 de Enero 2006, a las 11:07h
desde el dept. con-mucho-cuidado.

Programación Duncan nos cuenta: «Soy un programador y después de haber
realizado varios proyectos para la empresa en la que me encuentro me veo en la
difícil e ingrata situación de comenzar a documentar cada uno de ellos. Guia
de usuario, diagramas, comentar código, todo... ¿Por dónde se comienza, qué
herramientas se suelen utilizar, cómo hacerlo y qué es realmente útil
documentar y qué no?» Es una buena pregunta, porque hay muchas cosas que
parecen evidentes a quien lleva tiempo haciéndolas y no lo son para quien
empieza.



Los viejos cuentan... (Puntos:5, Inspirado)
por Janete el Viernes, 06 de Enero 2006, a las 11:18h (nº671923)
Info del Usuario nº13965
....que existe una leyenda que dice que se empieza por la documentación y se
termina por la implementación :P


Juas... (Puntos:2, Interesante)
por pax01 (p@...@lAgm@...) el Viernes, 06 de Enero 2006, a las 12:11h
(nº671959)
Info del Usuario nº10710 | http://barrapunto.com/ | Última Bitácora:
Miércoles, 28 de Diciembre 2005, a las 12:49h
Pues, siento decirlo, pero si te encuentras con proyectos terminados por tí
mismo y sin nada de lo que dices, simplemente es que la has cagado xD

Lo primero de cualquier proyecto es definir los requisitos del usuario (lo que
sirve de base a la documentación), luego preparar los diagramas esos... y sólo
entonces ponerse a programar, ¡comentando el código sobre la marcha! xD

Vamos, puedes repetir la receta cuantas veces quieras a lo largo de un mismo
proyecto, pero si hubieses hecho las cosas como hay que hacerlas, ahora no
estarías preguntando. Aunque, por otro lado, tal vez sólo acabas de hacer tu
primero proyecto un poquito más grande que algo básico, quién sabe... por lo
menos para la próxima ya sabes (y puede que tu empresa también, como se dén
cuenta xD)

Herramientas tienes bastantes, algunas en función del lenguaje y entorno:
Javadoc, NDoc, PDoc, POD, phpDocumentor, diagramas autogenerados -o si no con
dia, OpenOffice o cualquier otra cosa-, para más documentación OpenOffice,
tex, docbook, páginas de man... en fin, que haberlas haylas a montones.

Ahora solo faltaría que dijeses que eres titulado, y ahí sí que me iba a
partir de risa xD




Proyecto Readyset (Puntos:3, Informativo)
por miguser el Viernes, 06 de Enero 2006, a las 12:32h (nº671977)
Info del Usuario nº18044 | http://www.retratoensepia.com/ | Última Bitácora:
Martes, 03 de Enero 2006, a las 16:32h

Copio y pego la entrada de mi weblog [retratoensepia.com]:

Dede hace un tiempo vengo utilizando las plantillas de documentación del
proyecto readyset [tigris.org] de Tigris [tigris.org] (Los creadores de Argouml
[tigris.org]. En su página web podemos encontrar templates para la
especificación de requisitos, casos de uso, diseño y arquitectura, gestión de
proyectos, pruebas, etc... A mi me han ayudado bastante, porque por muy pequeño
que sea un proyecto, siempre hay que tener a mano la especificación de
requisitos, un pequeño planning y la definición de los casos de uso si
hablamos de un desarrollo orientados a objetos (en mi caso, siempre).

Readyset [tigris.org] tiene un contenido bastante completo. Incluye plantillas
para la documentación de los test xUnit. Son muy precisas, y abarcan toda la
definición de los casos de prueba. Creo que es lo más interesante de este
paquete, teniendo en cuenta que este paradigma de pruebas se está utilizando
cada vez más en los procesos de desarrollo.

Se puede acceder a las plantillas como un documento completo de desarrollo:
Introducción, plan, requerimientos, diseño, calidad, testing, guia de usuario,
etc,... No sigue ningún estándar de documentación al pie de la letra, así
que el mejor uso que se le puede dar es como plantillas individuales que pueden
ayudar durante el desarrollo, para luego ser integradas en la especificación
final del proyecto.

El proyecto sólo contiene plantillas en XHTML y CSS. No provee ningún tipo de
medio para editarla, ni siquiera XSLT. Así que podemos elegir dos cosas: Copiar
el contenido y utilizarlo en nuestro procesador de textos habitual o editar
manualmente el código de las plantillas, mucho más práctico si la
documentación tiene que ser visible por varios stakeholders.

Enlaces:

* Proyecto ReadySet [tigris.org] http://readyset.tigris.org/
* Tigris [tigris.org]
* Acceso a todas las plantillas [tigris.org]
http://readyset.tigris.org/nonav/templates/frameset.html



cómo sois... (Puntos:2, Informativo)
por pobrecito hablador el Viernes, 06 de Enero 2006, a las 13:19h (nº671993)
un par de programas -te recomiendo Umbrello-:

· Konzept [cyblogic.de]

· Umbrello [sourceforge.net]





La documentación es parte del proyecto (Puntos:2)
por wschutz el Viernes, 06 de Enero 2006, a las 14:33h (nº672025)
Info del Usuario nº21130 | http://www.m11m.org/
Ya lo han comentado por aquí, pero bueno... no me podía resistir teniendo en
cuenta que soy un amante de la IS.
La cuestión no es cómo documentar un proyecto pues esa respuesta ya existe
desde hace mucho tiempo: <A HREF="http://www.ambysoft.com/books/inceptionPhase
.html">Proceso Unificado</A> (lo que verás corresponde a un libro pero sirve
para coger la idea, no tengo algo más exacto porque lo tengo en papel, así que
para esto he usado al todopoderoso Google); sino ¿cómo hacer un proyecto?
Siguiendo los canones y patrones establecidos (habitualmente el PU) o
continuando con la tradición... "uséase" programar a saco y luego al final ya
haré algún papelujo.

Ahora bien, tenemos ese problema, si nos ponemos a hacer un análisis y luego su
posterior diseño para una vez tener una buena base y sobre dicha base
programar, a corto plazo, el tiempo (y en consecuencia el coste) se dispara;
pero a largo plazo obtendremos un producto más estable y sobre todo bien
documentado... Por no hablar de que si está bien hecha la documentación del
proyecto luego nos servirá para otros proyectos (famosa reutilización...) y
nos ahorraremos tiempo (y dinero).
Así que sería recomendable que en el futuro intentases hacer uso de las
tecnicas que ofrece la ingenieria del software porque al fin y al cabo la
programación no es más que una parte más del proceso de elaboración de un
programa; ciertamente una parte imprescindible, y por eso creo que los pasos
previos los solemos omitir, pero si queremos una programación sólida (no
sólida en cuanto a fallos sino sólida en cuanto a cambios en el diseño del
programa o cambio en los requisitos de la aplicación o cambios en cuanto a
integrar nuestra aplicación con otra existente... o con una librería)
necesitamos de un estudio previo, que es papel... pero que será muy útil.

En todo caso, siempre pienso que aunque no se haga un análisis-diseño previo,
en el fondo se está haciendo porque normalmente la persona que programa la
aplicación lo va haciendo sobre la marcha y mentalmente. Quizá sea un poco
estúpido, pero cuando te dicen en la empresa o alguien te contrata y te pide
tal cosa; lo primero que haces es preguntarle que quiere (hacer un sondeo, más
o menos, análisis de requisitos) y luego sobre lo poco que dice el cliente, y
lo que tu crees que le puede resultar útil para lo que pide comienzas a darle a
la tecla, pero para dar a la tecla, hay que tener cierta estructura, así que al
final el proceso se realiza, eso sí, no con la rigidez e intensidad con la que
debiera hacerse.

Resumiendo, puesto que querías herramientas... aquí van (todavía no he
encontrado una herramienta decente GNU/GPL... y mira que he buscado pero ninguna
de las que he visto, me acaba de gustar):
- IBM Rational Method Composer (la herramienta por excelencia...): <A
HREF="http://www-306.ibm.com/software/awdtools/rup /">Link</A>
- SPARX Enterprise Architect (una auténtica maravilla, completa aunque un poco
compleja al principio): <A HREF="http://www.sparxsystems.com.au/products/ea.h
tml">Link</A>
- Together (muy útil también y conocido): <A
HREF="http://www.borland..com/us/products/together/ index.html">Link</A>

Estas son las que me vienen a la cabeza... en cuanto a comentar código... eso
lo debes hacer, pero la tónica suele ser... comenta aquello que te esté
costando programar y aquello de lo que no estés seguro que vayas a entender en
un futuro... mientras más comentes mejor, eso sí, es un coñazo.
Para la documentación de pantallas, pues nada de MS Word, con LaTeX te vale, y
si no quieres usar LaTeX pues OpenOffice.

..So this is how liberty dies... with a thunderous applause (Star Wars III:
Revenge of the Sith 2005)





Métrica 3 (Puntos:3, Informativo)
por jacoboworldwide ({jacobo.ibook} {at} {ya.com}) el Viernes, 06 de Enero 2006,
a las 14:44h (nº672034)
Info del Usuario nº14354 | http://jacoboworldwide.aenima.org/ | Última
Bitácora: Lunes, 19 de Diciembre 2005, a las 19:47h
En la universidad nos enseñan a utilizar la metodología metrica 3
[http://www.csi.map.es/csi/metrica3/] para desarrollar y documentar proyectos.

En esta metodología se especifica cuando y como hay que escribir diagramas,
documentación, manuales de usuario, etc.

Se supone que el Estado Español exige la utlización de esta metodología en
sus proyectos.




herramientas (Puntos:1)
por levhita el Viernes, 06 de Enero 2006, a las 19:09h (nº672179)
Info del Usuario nº22587 | http://levhita.blogspot.com/
Para documentar tu base de datos te recomiendo DBDesigner4(tiene funciones de
ingenieria inversa).

El código se comenta a mano, no hay de otra, dependiendo del lenguaje puedes
conseguir parsers que convierten tus comentarios en documentación HTML.

los diagramas generalmente no son necesarios, a menos que hallas desarrollado en
base a casos de uso y en ese caso debiste diagramar antes, ahora simplemente te
seria imposible y ademas inutil.

El manual de usuario lo haces directo en OpenOffice no hay otra (bueno tambien
esta word y HTML puro)."La libertad viene en paquetes pequeños, usualmente
TCP/IP"




Yo recomiendo (Puntos:2)
por epoh el Domingo, 08 de Enero 2006, a las 02:13h (nº672966)
Info del Usuario nº8012 | http://pinguino.dyndns.org/
Tanto si tienes que documentar a posteriori como si lo haces a priori (que es lo
ideal), te recomiendo MagicDraw [http://www.magicdraw.com/]. No es software
libre, y no se si eso realmente te importa, pero merece la pena, y la licencia
no es demasiado cara.
Es muy productivo, te recomiendo que al menos pruebes la versión community (es
gratuita) y tu mismo verás lo rápido que se trabaja.
Y si lo usas a priori, además tiene la ventaja de soportar generación de
código y round-trip, es decir: una vez que tienes diagrama y código, si
actualizas el diagrama te sincroniza el código, y si modificas el código, te
actualiza el diagrama.
Incluso tiene ingeniería inversa de diagramas de secuencia (es decir, se
generan a partir del código tambien), que es una funcionalidad poco habitual y
ahorra mucho trabajo.
Para escribir manual de usuario yo trabajo con latex
[http://www.latex-project.org/]. Escribo toda la documentación con kile
[http://kile.sourceforge.net/] (editor de latex) e incluyo los diagramas de
magicdraw en formato vectorial. Inkscape [http://www.inkscape.org/] ayuda
bastante cuando hay que hacer diagramas que no son UML. Y con latex2html
[http://www.latex2html..org/] mantengo una versión navegable online del manual,
para utilizar más en plan referencia mientras trabajas.
Para el manual de referencia con la documentación de los API, utilizo doxygen
[http://www.stack.nl/~dimitri/doxygen/l].
Esta es mi forma de trabajar, y resulta bastante bien incluso trabajando en
equipo.
Los libros son las abejas que llevan el polen de una inteligencia a otra. James
Lowell


-----------------------------------------------------
Este correo electrónico y, en su caso, cualquier fichero anexo
al mismo, contiene información de carácter confidencial
exclusivamente dirigida a su destinatario o destinatarios. Queda
prohibida su divulgación, copia o distribución a terceros sin la
previa autorización escrita de Dap. En el caso de haber
recibido este correo electrónico por error, se ruega notifíquese
inmediatamente esta circunstancia mediante reenvío a la dirección
electrónica del remitente.
----------------------------------------------------------
The information in this e-mail and in any attachments is confidential
and solely for the attention and use of the named addressee(s).
You are hereby notified that any dissemination, distribution or copy
of this communication is prohibited without the prior written consent
of Dap. If you have received this communication in error,
please, notify the sender by reply e-mail.
-------------------------------------------------------------