documentation - sistemas - ¿Cuál es la mejor manera de almacenar la documentación del software?
ieee 1063-2001 (8)
Una respuesta obvia es "una wiki interna". ¿Cuáles son los pros y los contras de una wiki utilizada para la documentación de software? ¿Cualquier otra sugerencia? ¿Qué estás usando para tu documentación de software?
Loren Segal : Desafortunadamente no contamos con soporte para ninguna herramienta de doc. Para recopilar información de los comentarios del código fuente, pero acepto que sería la mejor manera de almacenar la documentación técnica. Mi pregunta era acerca de todo tipo de documentación, desde el tipo de sysadmin hasta la documentación del usuario.
«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 técnicos en tecnología calificados. Otros pueden formarse dinámicamente a partir de wikis, comentarios de documentación desde el código fuente, etc. Todo este proceso de mantenimiento suele ser muy complejo y cada compañía de software sigue su propio camino. Pero hay un punto necesario para todas estas formas: cada codificador, arquitecto, gerente, qa ingeniero DEBE almacenar bien organizado cada información que pueda ser útil para los demás. Y alguien más DEBE vigilar el almacenamiento de estas piezas y reorganizar las piezas si es necesario. Todos estos pasos mejoran en gran medida todas las actividades relacionadas con el proceso de desarrollo.
Empecé a experimentar con una forma de hacer la documentación del usuario con estos objetivos:
Markdown / Html / Javascript / documentos relativamente vinculados a archivos para la portabilidad ( puede ejecutarse en un sistema de archivos local o puede lanzarlo en un servidor web ), manejo integrado de capturas de pantalla (cambio de tamaño interactivo ) y código abierto en caso de que alguien más pueda quiero hacer algo con lo loco.
El origen de su documento está escrito en Markdown y se procesa en Html mediante Javascript en el tiempo de ejecución del navegador.
Esa es una pregunta muy abierta y depende de muchos factores.
En términos generales, si utiliza un lenguaje que tenga buenas herramientas de generación de documentación (javadoc, doxygen, MS Cs), debe escribir su documentación sobre sus métodos y hacer que sus herramientas generen las páginas. La ventaja es que mantiene la 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 una buena herramienta de documentación o no tiene acceso al código fuente, las wiki no son una mala idea, pero son una segunda opción para lo anterior.
Nota: estoy hablando solo de la documentación del código aquí. Evidentemente, otros artefactos no se pueden almacenar junto con el código: una wiki es un excelente lugar para colocar esos documentos. Alternativamente, si usa algunos CMS, puede simplemente asignarlos en algunos docs/ carpetas como archivos de texto / pdf / cualesquiera que sean editables a través del repositorio. La ventaja es que se quedan con el repositorio si se mueve mientras que un wiki no lo hace (necesariamente).
Las herramientas son importantes, pero no te empantes demasiado al encontrar la herramienta mágica. Ninguna herramienta que he encontrado aún tiene un tickbox de "documentar todo mágicamente usando diminutos elfos invisibles". :-)
Un wiki funcionará bien. O Sharepoint. O documentos de Google. O podrías usar un repositorio SVN. Demonios, podrías hacerlo con bolígrafos, papel de carta y archivadores si realmente tenías que hacerlo. (¡Realmente no lo recomiendo!)
La gran clave importante es que debe tener aceptación en toda la organización. Lo que sucede en muchas tiendas es que invierten mucho tiempo y dinero en una solución elegante como Sharepoint, y luego todo el mundo lo usa religiosamente durante unas dos semanas, y luego la gente se ocupa de alcanzar el último hito y esa es la última alguien oye sobre eso
Dependiendo de su organización, campo, el tipo de productos que desarrolla, etc., hay algunas soluciones para eso, pero de una forma u otra debe configurar un sistema y usarlo . Nombra a alguien como el zar de la documentación oficial, dales un cluebat y diles que golpeen a las personas en la cabeza cada vez que digan "oh sí, terminaré de documentar eso la próxima semana ...". si eso es lo que se necesita :-)
En cuanto a las herramientas ... recomendaría Confluence by Atlassian. Es una buena wiki, está diseñada para funcionar en un entorno empresarial, tiene muchas funciones ingeniosas, es personalizable, se integra bien con algunas de las otras ingeniosas herramientas de Atlassian, y básicamente es un producto bastante sólido.
Mi empresa usa una variedad de Sharepoint y una wiki. Sharepoint para documentos específicos como requisitos, presentaciones, contratos, etc., mientras que el wiki se usa como guía de ayuda para un repositorio de desarrolladores de tutoriales sobre el uso de bibliotecas desarrolladas internamente.
Sí, usamos una wiki, también usamos documentos de Google. Considero que los documentos de Google son mejores que la mayoría de los wikis que he probado y, si no es necesario que realice un seguimiento de todos los cambios, no pierde nada. Google Docs proporciona un buen marco de colaboración.
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 echarle un vistazo a DITA .
Actualmente usamos documentación en línea analizada por una aplicación externa (PHP + PhpDocumenter) más varios wikis internos. A veces es doloroso en el mejor de los casos (principalmente porque solo una persona actualiza los wikis o los documentos ...)
Sin embargo, he estado buscando 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 puedan seguir su proyecto. Está construido en Perl y tiene un extenso sistema de complementos (incluyendo múltiples lenguajes de marcado, con Markdown predeterminado). Además, el sistema de control de fuente está basado en un complemento, de modo que si lo que usa no se admite de inmediato, puede agregar el suyo propio. En su idioma preferido, si es necesario, ya que también es compatible con plugins no perl.