¿Cuál es la mejor manera de almacenar documentación de software?[cerrado]

Question

Una respuesta obvia es "una wiki interna".¿Cuáles son los pros y los contras de un wiki utilizado para la documentación de software?¿Cualquier otra sugerencia?¿Qué estás utilizando para la documentación de tu software?

Loren Segal - Desafortunadamente no tenemos soporte para ninguna herramienta de documentación para compilar información de los comentarios del código fuente, pero estoy de acuerdo en que sería la mejor manera de almacenar documentación técnica.Aunque mi pregunta era sobre todo tipo de documentación, desde el tipo de administrador de sistemas hasta la documentación del usuario.

Answer 1

Esa es una pregunta muy abierta y depende de muchos factores.

En términos generales, si usa un lenguaje que tiene buenas herramientas de generación de documentación (javadoc, doxygen, C# de MS), debe escribir su documentación encima de sus métodos y hacer que sus herramientas generen las páginas.La ventaja es que conservas el fuente de su texto junto con su código, lo que significa que está organizado en el lugar lógicamente correcto y fácilmente editable cuando realiza un cambio en el comportamiento del método.

Si no tiene un buen soporte de herramientas de documentación o no tiene acceso al código fuente, los wiki no son una mala idea, pero son una segunda opción después de las anteriores.

Nota:Estoy hablando sólo de documentación de código aquí.Obviamente, otros artefactos no se pueden almacenar junto con el código; una wiki es un excelente lugar para colocar esos documentos.Alternativamente, si usa algún CMS, simplemente puede enviarlos en algún docs/ carpeta como texto/pdf/cualquier archivo que se pueda editar a través del repositorio.La ventaja es que permanecen en el repositorio si se mueve, mientras que un wiki no (necesariamente).

Answer 2

Las herramientas son importantes, pero no se obsesione demasiado buscando la herramienta mágica.Ninguna herramienta que he encontrado todavía tiene una casilla de verificación "documentar todo mágicamente usando pequeños elfos invisibles".:-)

Una wiki funcionará bien.O compartir punto.O documentos de Google.O podrías usar un repositorio SVN.Demonios, podrías hacerlo con bolígrafos, papel de notas y archivadores si realmente fuera necesario.(¡Realmente no lo recomiendo!)

La clave más importante es que es necesario contar con la aceptación de toda la organización.Lo que sucede en muchas tiendas es que van y gastan mucho tiempo y dinero en alguna solución sofisticada como Sharepoint, y luego todos la usan religiosamente durante unas dos semanas, y luego la gente se ocupa de alcanzar el último hito y ese es el último. cualquiera se entera de ello.

Dependiendo de su organización, campo, tipo de productos que esté desarrollando, etc., existen algunas soluciones para eso, pero de una forma u otra necesita configurar un sistema y usar él.Nombra a alguien como zar de la documentación oficial, dale una pista y dile que golpee a la gente en la cabeza cada vez que diga "oh, sí, terminaré de documentar eso la próxima semana...".si eso es lo que hace falta.:-)

En cuanto a herramientas...Yo lo recomiendo Confluencia por Atlassian.Es un excelente wiki, está diseñado para funcionar en un entorno empresarial, tiene muchas características ingeniosas, es personalizable, se integra bien con algunas de las otras herramientas ingeniosas de Atlassian y es básicamente un producto bastante sólido.

Answer 3

«Documentación de software» es un término muy general.Hay «Documentación de usuario final», «Documentación de desarrollador», «Documentación de control de calidad».El primero suele ser desarrollado por redactores técnicos cualificados.Otros pueden formarse dinámicamente a partir de wikis, comentarios de documentación del código fuente, etc.Todo este proceso de mantenimiento suele ser muy complejo y cada empresa de software sigue su propio camino.Pero hay un punto necesario para todos estos métodos:cada autor de código, arquitecto, gerente, ingeniero de control de calidad DEBE almacenar bien organizada cada pieza de información que pueda ser útil para los demás.Y alguien más DEBE vigilar el almacenamiento de estas piezas y reorganizarlas si es necesario.Todos estos pasos muy mejorar todas las actividades relacionadas con el proceso de desarrollo.

Answer 4

Suponiendo que esté hablando de documentación de código versus documentación de usuario, una wiki interna es excelente si no necesita distribuir la documentación del código fuera de su organización, a contratistas o socios.

Javadoc o DOxygen es más adecuado si desea documentación de código distribuible.

Si se refiere a la documentación del usuario, es posible que desee echar un vistazo a DITA.

Answer 5

Comencé a experimentar con una forma de realizar documentación de usuario con estos objetivos:

Markdown/Html/Javascript/documentos relativamente vinculados basados ​​en archivos para portabilidad (Puede ejecutarse en el sistema de archivos local o puede ejecutarlo en un servidor web.), manejo integrado de capturas de pantalla (cambiar el tamaño interactivamente), y código abierto en caso de que alguien más quiera hacer algo con esta locura.

La fuente de su documento está escrita en Markdown y representada en HTML a través de Javascript en tiempo de ejecución del navegador.

Hombre caído  -  http://wittman.org/mandown/

Answer 6

Actualmente utilizamos documentación en línea analizada por una aplicación externa (PHP + PhpDocumenter) además de varios wikis internos.A veces, en el mejor de los casos, es doloroso (principalmente porque solo una persona actualiza los wikis o los documentos...)

Sin embargo, he estado considerando usar ikiwiki para hacer documentos internos.Se integra con su sistema de control de origen (incluidos Git, Subversion, Mercurial, Bazaar, TLA y Monotone) para que todos sus documentos sigan su proyecto.Está construido en Perl y tiene un extenso sistema de complementos (que incluye múltiples lenguajes de marcado, siendo el predeterminado Markdown).Además, el sistema de control de fuente está basado en complementos, por lo que si lo que usas no es compatible de inmediato, puedes agregar el tuyo propio.En su idioma preferido, si es necesario, ya que también admite complementos que no son de Perl.

Answer 7

Mi empresa utiliza una variedad de Sharepoint y una wiki.Sharepoint para documentos específicos como requisitos, presentaciones, contratos, etc., mientras que la wiki se utiliza como guía de ayuda y un repositorio de desarrolladores para tutoriales sobre el uso de bibliotecas desarrolladas internamente.

Answer 8

Sí, usamos una wiki, también usamos documentos de Google.Creo que los documentos de Google son mejores que la mayoría de los wikis que he probado y, si no necesitas realizar un seguimiento de todos los cambios, no pierdes nada.Google Docs proporciona un buen marco de colaboración.