¿Software para organizar y mantener documentación del proyecto, especificación? [cerrado]

15

Estoy buscando software para organizar y mantener la documentación interna de los proyectos, las especificaciones, los requisitos, etc. Actualmente almacenamos toda la documentación como muchos archivos MS Word DOC en un repositorio de control de código fuente, lo que nos da control de la versión, y eso es bueno. Pero no puede buscar esta información, crear enlaces entre ellos, clasificar, colaborar.

Requisitos, preferencias:

  • Instalación cero en el lado del cliente (basado en WEB).
  • Control de versiones de documentos.
  • Anotaciones de documentos.
  • Enlace de documentos.
  • Búsqueda completa (toda la documentación).
  • MS Word (* .doc) importación \ exportación.
  • Editor de texto WYSIWYG.

Sistemas que he descubierto y probado hasta ahora:

Alex Burtsev
fuente
¿Qué tipo de documentación del proyecto tiene (textuales, gráficos, diagramas UML, horarios, especificaciones textuales, historias de usuarios, etc.)? ¿Cuántas personas tienen que mantenerlo? ¿Debe estar sincronizado con versiones / revisiones específicas de su código fuente?
Doc Brown
@DocBrown, 95% textual, 3-5 personas lo escribirán. Está sincronizado con versiones de productos de software pero no con revisiones de código fuente.
Alex Burtsev
XWiki parece una buena solución, es gratis, se integra muy bien con MS Office.
Alex Burtsev
1
Esto está muy cerca de ser un duplicado de ¿Qué programa utilizas para escribir documentación técnica? y muchas de las respuestas son similares, pero hay mejores argumentos en contra de usar un wiki para dicha documentación.
Mark Booth
¿Qué tal un software de gestión del conocimiento como PHPKB ? No es gratis, pero parece cumplir muy bien su propósito.
Anirudh Srivastava

Respuestas:

6

¿Qué tal algo como Sphinx ?

Usted escribe su documentación en reStructuredText (la sintaxis es similar a Markdown, que utiliza Stack Overflow) en archivos de texto sin formato (= fácil de controlar la versión) y Sphinx escupe páginas HTML.

Los dos usuarios más destacados de Sphinx (que yo sepa) son el lenguaje Python y TortoiseHG (ver los enlaces para la documentación generada por Sphinx).


EDITAR:

Acabo de leer que está hablando de documentación interna del proyecto, no de documentación del usuario final.
En mi opinión, algo así como Sphinx es la mejor manera de documentación interna también (siempre que pueda hacer que sus analistas escriban reStructuredText) porque:

  1. Puede controlar fácilmente la versión de los documentos (y las diferencias de los archivos de texto ocupan mucho, mucho menos espacio que los archivos binarios como .doc o .pdf).
  2. Si un desarrollador quiere un buen archivo .doc o .pdf legible, puede crearlo con Sphinx desde las fuentes.

Si Sphinx es demasiado complicado, hay una forma más fácil: puede escribir su documentación en Markdown y usar Pandoc para crear (por ejemplo) archivos .rtf, .doc o .pdf (puede hacer mucho más).
Pandoc me pareció más fácil de comenzar que Sphinx, pero Pandoc no puede crear buenas jerarquías de menú como Sphinx (como en la documentación de Python y TortoiseHG que he vinculado anteriormente).

Independientemente de las herramientas que utilice, si tiene un servidor web interno y un servidor de compilación, puede configurarlo para que el servidor de compilación genere una salida HTML y la copie en el servidor web cada vez que alguien envíe algo a la documentación. Por lo tanto, sus analistas ni siquiera tienen que pensar en el resultado final, solo necesitan comprometerse e impulsar sus cambios.

Christian Specht
fuente
Parece que solo genera HTML, luego tendré que publicarlo en un servidor web
Alex Burtsev
1
@AlexBurtsev: Si quieres que sea público, entonces sí. Por otro lado, ahora está utilizando archivos .doc de Word, por lo que también debe colocarlos en un servidor web si desea que sean públicos.
Christian Specht
Observo que Sphinx tiene una ruta de "salida a PDF".
Robert Harvey
@ChristianSpecht, Wiki y Wordpress tienen complementos para importar archivos de Word Doc.
Alex Burtsev
@AlexBurtsev: No estoy seguro si entendí lo que quieres hacer con la documentación. Si desea ponerlo en la web, necesita algún tipo de servidor web, sin importar si usa Sphinx, Wordpress, una descarga .doc u otra cosa. Si necesita distribuir la documentación con el software retráctil, puede usar Sphinx para generar archivos PDF o archivos de ayuda de Windows.
Christian Specht
5

Bueno, puedes intentar implementar un Wiki. Mediawiki tiene todas las características faltantes de las que está hablando (funciones de búsqueda, historial de versiones, enlaces, categorización). Tendrá que asegurarse de saber exactamente qué versión de la documentación pertenece a qué versión del software, pero eso se puede hacer mediante la convención de incluir una referencia de versión o una categoría específica en cada artículo dependiente de la versión.

PERO: Usted escribe que tiene "analistas" que no son desarrolladores (lo admito, no soy fanático de esa constelación). Ese tipo de personas a menudo no está contento cuando reemplaza sus herramientas de MS Office por alguna herramienta orientada al texto como un Wiki. Y dado que MS-Word no es software libre, supongo que el requisito de "software libre" no es realmente obligatorio. En esta situación, un servidor Sharepoint podría ser la mejor alternativa. No es gratuito, pero AFAIK tiene todas las características que está solicitando, y los documentos aún se pueden crear con Word, Excel, etc.

Doc Brown
fuente
1
Ya tenemos un servidor de SharePoint, pero a los desarrolladores no les gusta, y no queremos usarlo (yo mismo soy desarrollador). Queremos algo donde podamos encontrar fácilmente la información que necesitamos. Información que está categorizada y vinculada.
Alex Burtsev
@AlexBurtsev: nunca he usado el servidor Sharepoint, pero tenía la impresión de que Sharepoint estaba proporcionando todas esas características que estaba describiendo. Pero si prefiere un Wiki, Mediawiki estará bien para usted. Sin embargo, hará un esfuerzo inicial para instalarlo, definir un esquema de estructura y también definir algunas convenciones sobre cómo usarlo o no.
Doc Brown
Actualmente estoy probando XWiki para su integración con MS Office
Alex Burtsev
@DocBrown - SharePoint es horrible. No es intuitivo, es un laberinto completo de pestañas y subpestañas, y no mantiene ningún control de versión adecuado. Cualquiera que lo use sería mejor volcar todos sus documentos en un directorio compartido en un servidor interno. Una wiki suele ser el camino a seguir para este tipo de cosas.
Polinómico
2

Siempre es mejor mantener las especificaciones y la documentación bajo el control de la versión, ya que le daría la mayor influencia, aunque la curva de aprendizaje sería un poco empinada. En caso de un motor de conocimiento, recomiendo lo siguiente

  1. Trac : sistema de seguimiento de errores y motor de conocimiento fáciles de usar. Escrito en Python y extensible, estarías en funcionamiento en unos minutos
  2. MoinMoin : motor wiki completo. Nuevamente Python con muchas características

Ambas tienen interfaces mínimas, son compatibles con la mayoría de las estructuras wiki, son bastante fáciles de implementar y mantener, admiten revisiones, tienen un buen editor WYSIWYG e incluso pueden conservar su documentación y especificaciones. A menos que sus proyectos sean realmente enormes, puede elegir cualquiera de los anteriores.

Ubermensch
fuente
2

Recientemente comenzamos a usar el Alfresco DMS que tiene muchas propiedades interesantes:

  • Instalar muy simple
  • Tiene un indexador incorporado para realizar búsquedas rápidas en montones de documentos.
  • Permite flujos de trabajo, grupos y, si es necesario, acceso específico a los documentos por parte de los clientes.
  • Fuente abierta
  • Comunidad activa
  • Integración LDAP / AD / SSO
  • Maneja muchos documentos diferentes

También hay algunas desventajas:

  • La interfaz de usuario no siempre es intuitiva
  • No es realmente una wiki, por lo que el trabajo colaborativo simultáneo en un documento puede ser un poco frágil

Si decide darle un giro, contácteme con sus opiniones.

Dibbeke
fuente
0

Otra posibilidad podría ser usar LaTeX o algún otro formateador de texto (quizás texinfo o incluso lout ) para la documentación. Partes de él pueden ser generadas a máquina. Existen algunas herramientas para la conversión de HTML, como HeVeA para convertir LaTeX a HTML. También puede usar doxygen para generar documentación a partir de comentarios estructurados dentro de su código fuente. Y las partes escritas a mano de la documentación pueden (y deberían) gestionarse como código fuente (por ejemplo, control de versiones y compilación).

Basile Starynkevitch
fuente
No estoy hablando de la documentación del producto de software (ayuda, manual). Estoy hablando de especificaciones de software, requisitos comerciales.
Alex Burtsev
Puede escribir especificaciones de software o cualquier documento técnico en LaTeX, y en algunos círculos es una práctica común.
Basile Starynkevitch
2
LaText de alguna manera me recuerda a * NIX, y nuestros analistas nunca acumulan ese sistema operativo -), viven en el mundo de Windows y no estarán de acuerdo en algo que sea más difícil que Word para el ingreso de texto.
Alex Burtsev
-2

Sugeriría usar una herramienta UML y ERD, además de sus documentos. Además, puede almacenar estos documentos en ZOHO en ZOHO-Docs , que no es gratuito, pero es extremadamente barato y permite la búsqueda de documentos.

Independientemente de la herramienta que utilice, debe organizar el contenido del documento cuidadosamente para poder utilizar la búsqueda de texto y obtener resultados significativos. La organización del contenido del documento junto con la denominación de archivos inteligente y estándar podría ser de gran ayuda.

Ninguna posibilidad
fuente