Barrapunto

...que existe una leyenda que dice que se empieza por la documentación y se termina por la implementación :P

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 ello

Si hubieras hecho todo eso cuando correspondia, que es a la vez que se va haciendo el codigo, y los diagramas antes de nada; ahora no tendrias este problema.
A priori no es facil documentar un proyecto ya hecho y mas si lleva hecho cierto tiempo.
Las cosas es mejor hacerlas cuando corresponden.
Como tu has dicho, eres programador. Un informatico, que se supone que sabe de esto, hace todas esas cosas antes, porque es su secuencia logica.
Si, ya se que soy un troll y no quiero que me respondan porque no hay que alimentar a los trolls. Solo queria desahogarme por toda esta intrusion que hay en España (en todo tipo de profesiones).
Ale, ya me he quedado agusto, voy a ver que me han traido los reyes...

Comentar código... que me parto... ¿donde ha quedado eso de escribir los comentarios antes que el código? Más que nada porque te obliga a pensar el código que vas a escribir de antemano....

En fins, que si no tienes comentarios en tu código ... mal vamos...

Yo te recomendaría NDoc, JDoc y comentarios basados en XML... hay implementaciones para cualquier lenguaje... Luego generas una documentación bastante decente y eso unido a unos diagramás de clases generados automaticamente pues listo...

Pero anda que no tienes curro... te esta de puta madre por chapucero...

Y fijate... no soy Informatico de los que tienen un titulo en la pared pero vamos que en los proyectos que dirijo algo como lo que tu has hecho no tiene cabida. Por ejemplo en C#... warning level a 4 y tratar warnings como errores de compilación y ni dios puede compilar nada que no tenga comentarios por lo menos asociados a las funciones y clases publicas... Eso unido a Entreprise Policies de Visual Studio y listo... no hay programador que se libre de comentar... Luego con el NDoc lo pones bonito... Segurisimo que lo mismo se puede hacer con Eclipse y Jdoc... En Visual C++ o VB tambien se puede...

Asi que la culpa del jefe de proyecto, que no impone eso a priori...

Por cierto escribir el manual de usuario antes de empezar a desarrollar más haya de prototipos iniciales es una técnica cojonuda para tener una captura de requisitos suficiente y no excesiva.

Lo del manual de usuario, normal, puesto que normalmente se quieren incluir screenshots que no se tienen hasta el final del proyecto.

Lo de los diagramas de diseño... pase, si no tenías ninguna herramienta a mano (lo que no quita que estén en papel).

Pero lo de comentar el código... que no hayas comentado el código que has tenido delante de las narices durante todo el desarrollo... eso no tiene nombre. No me extraña que luego pongan a los ingenieros a programar xD

Bueno, aquí va mi regalito de reyes para ti:

• MS Visio [microsoft.com]
• Rational [ibm.com]
• Oracle Developer [oracle.com]
• Desarrollo de Software en SF [sourceforge.net] (a ver qué encuentras para ingeniería inversa)

Y para escribir documentación, pues el todopoderoso Word (si docbook no estuviese tan verde, te lo recomendaría, pero todavía le queda algo por madurar).

Ah, una cosa más, a lo mejor deberías comentar en tu empresa que las cosas no se hacen así... a ver qué pasa xD

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

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]
• Tigris [tigris.org]
• Acceso a todas las plantillas [tigris.org]

... que no quede. ¿Alguien sabe si se usa doxygen en algun sitio profesionalmente?

un par de programas -te recomiendo Umbrello-:

 · Konzept [cyblogic.de]

 · Umbrello [sourceforge.net]

Vamos a ver, amigo mio.

Si te piden la documentación ahora, significa que:

a) El cliente la quiere. b) Lo quiere tu empresa por temas de calidad (aenor o lo que sea).

Pues ves a saco y escribe.

Si la haces ahora, significa que a tu empresa no le interesa un carajo hacer las cosas bien. (Como a la gran mayoria de las empresas de TI).
Lo unico que le interesa es cumplir el plazo. ¿ Como se cumpla ? Eso es indiferente. La cuestion es que se cumple y ya está. Ahora viene la documentación. Pues escribe y escribe, haz hardcopys, ponle los logos de la empresa, una buena caratula de portada, etc...

Es lo que piden la gran mayoria de empresas: Papel para archivar, que no leerá nadie, mas que aquel pringao que le digan: Vas a trabajar en este proyecto, anda!, vete leyendo el funcional.


Uno que está hasta los mismisimos de la informatica.

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.

.

En la universidad nos enseñan a utilizar la metodología metrica 3 [csi.map.es] 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.

No digo que sea el caso, ya que no lo conozco, pero puede estar en la siguiente situación:

- Llega nuevo a la empresa.
- Le endosan unos cuantos proyectos que debían estar listos un par de meses antes de entrar él.
- Tiene que acabarlos a la carrera porque "o lo acabas o ya veremos si alargamos el contrato (de mierda)"
- Cuando ya los ha terminado a la carrera le piden la documentación, cosa que se les "olvidó" pedir cuando "había tanta prisa".
- Se encuentra con 5 o 6 (por decir unas cifras) proyectos sin documentar por las prisas y con prisas por parte del jefe porque queden documentados, que "ahora" sí hace mucha falta esa documentación.

¿A alguien le suena algo así? No hace falta que sea programador.

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).

Tanto si tienes que documentar a posteriori como si lo haces a priori (que es lo ideal), te recomiendo MagicDraw [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 [latex-project.org]. Escribo toda la documentación con kile [sourceforge.net] (editor de latex) e incluyo los diagramas de magicdraw en formato vectorial. Inkscape [inkscape.org] ayuda bastante cuando hay que hacer diagramas que no son UML. Y con latex2html [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 [stack.nl].
Esta es mi forma de trabajar, y resulta bastante bien incluso trabajando en equipo.

Muchas gracias por el aviso, acabo de buscar en la web de micro$oft dicho parche para el WMF [microsoft.com], no hay nada como hacer famoso un error para que intenten solucionarlo lo antes posible eh jejej.

Nota: lo de comentarios que no salen tmb. me ha pasado.