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 -: