Foro de elhacker.net

Hola, pues no supe donde poner esto, asi que lo pongo aqui, si algun administrador o moderador considera que va en otro lado, le agradeceria la indicacion o el favor de moverlo :P

Estoy trabajando en un proyecto, una aplicacion escrita en C que corre en linux (ubuntu en particular) y por la programacion no hay tanto problema, la cosa es que tengo la necesidad de documentarla. El proyecto contará con la licencia GPL3 y para poder acompañarlo por su proceso de vida (esté con quien esté) su documentacion necesita ser libre. Sinceramente NO TENGO IDEA de donde comenzar, nunca antes me vi en la necesidad de documentar algo diferente a un pdf con imagenes y texto que tediga "este programita funciona asi si le picas acá". Si alguien puede ayudarme guiandome en que pasos debo seguir, agradeceria mucho. Aun asi seguiré buscando, si encuentro algo, lo publicaré, de cualquier modo, creo que esto de la documentacion es algo en lo que muchos programadores nunca nos ponemos a pensar :P

Saludos y gracias de antemano n_n

PD: Para evitar confusiones, Necesito documentar formalmente el programa (como si fuera de microsoft o apple o cualquier compañia "formal" pero de modo que pueda presentarse y ampararse como documentacion libre).

Creo que esto depende más que nada del tipo de documentación que quieres hacer.

Es distinto hacer una documentación para un usuario (por ejemplo: Click aquí para fin del mundo...) que tener que documentar tu código para que alguien más lo utilice, como cuando tienes que programar algo importante como un API que otra persona utilizará más adelante.

Para el primer caso una documentación como dices con imágenes y eso (el manual de usuario de toda la vida) pero para el segundo tal vez debas elaborar algo que no dependa de tener que abrir el código fuente para ver cada comentario y lo que hace.

Aquí con Java se proporciona Javadoc, pero ni aun así soy muy fan de su utilización porque además no queda algo muy intuitivo desde mi punto de vista y lo que sí he visto es algún que otro programa opensource documentado el código con doxygen. La licencia es GPLv2 y es bastante fácil de empezar a utilizar, soporta muchos lenguajes y deja una documentación bastante entendible, aquí lo deberías de encontrar:


Se basa en ir creando etiquetas por el documento y una vez terminado ejecutar el doxygen para que explore los ficheros fuente y construya la documentación en base a lo que hay dentro.

Aquí un ejemplo de documentación (obviamente elaborada) hecha con doxygen - El API de bukkit para minecraft -:

Gracias final_frontier! Lo voy a probar y a ver que me dicen, pero, si es como me creo que es, esta herramienta me ayudará a resumir gran parte del trabajo. Si al final me aceptan el formato de la documentacion entonces publicaré aqui como lo hice, por si en el futuro alguien necesita hacerlo :P
Una vez mas muchas gracias! Saludos!