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

15

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

Requisitos, preferencias:

  • Instalación cero en el lado del cliente (basado en WEB).
  • Control de versión del documento.
  • anotaciones del documento.
  • Enlace de documentos.
  • Búsqueda completa (toda la documentación).
  • Importación / exportación de MS Word (* .doc).
  • Editor de texto WYSIWYG.

Sistemas que he descubierto y probado hasta ahora:

pregunta Alex Burtsev 27.12.2011 - 21:19
fuente

6 respuestas

6

¿Qué tal algo como Sphinx ?

Usted escribe su documentación en reStructuredText (la sintaxis es similar a Markdown, que usa Stack Overflow) en archivos de texto simple (= 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 idioma de Python y TortoiseHG (consulte los enlaces de la documentación generada por Sphinx).

EDIT:

Acabo de leer que está hablando de documentación interna del proyecto, no de la documentación del usuario final.
En mi opinión, algo así como Sphinx es la mejor forma 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 los archivos de texto ocupan mucho menos espacio que los archivos binarios como .doc o .pdf).
  2. Si un desarrollador desea un archivo .doc o .pdf legible, puede crearlo con Sphinx desde las fuentes.

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

No importa cuál de las herramientas use, si tiene un servidor web interno y un servidor de compilación, puede configurarlo para que el servidor de compilación genere resultados HTML y los copie en el servidor web cada vez que alguien presione algo para la documentación. Entonces, sus analistas ni siquiera tienen que pensar en el resultado final, solo tienen que comprometerse e impulsar sus cambios.

    
respondido por el Christian Specht 27.12.2011 - 21:42
fuente
5

Bueno, puedes intentar implementar un Wiki. Mediawiki tiene todas las características que faltan de las que está hablando (funciones de búsqueda, historial de versiones, enlaces, categorización). Deberá asegurarse de saber exactamente qué versión de la documentación pertenece a qué versión del software, pero eso puede hacerse por 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 un fanático de esa constelación). Ese tipo de personas a menudo no están contentos cuando reemplazas sus herramientas de MS Office por alguna herramienta de texto orientado como un Wiki. Y dado que MS-Word no es software libre, supongo que el requisito de "software libre" no es realmente un deber. En esta situación, un servidor Sharepoint podría ser la mejor alternativa. No es gratis, pero AFAIK tiene todas las funciones que está solicitando, y los documentos aún se pueden crear con Word, Excel, etc.

    
respondido por el Doc Brown 27.12.2011 - 22:48
fuente
2

Siempre es mejor mantener las especificaciones y la documentación bajo el control de versiones, ya que le daría el mayor apalancamiento, aunque la curva de aprendizaje sería un poco pronunciada. 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á listo y funcionando en unos minutos
  2. MoinMoin : motor de wiki completo. De nuevo Python con muchas características

Ambos tienen interfaces mínimas, admiten la mayoría de las estructuras de 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 tus proyectos sean realmente grandes, puedes elegir cualquiera de los anteriores.

    
respondido por el Ubermensch 16.01.2012 - 09:14
fuente
2

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

  • instalación muy sencilla
  • Tiene un indexador incorporado para la búsqueda rápida a través de montones de documentos
  • Permite flujos de trabajo, grupos y, si es necesario, acceso específico a los documentos por parte de los clientes
  • código abierto
  • 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 un wiki, por lo que el trabajo colaborativo simultáneo en un documento podría ser un poco frágil

Si decides darle un giro, contáctame con tus opiniones.

    
respondido por el Dibbeke 09.02.2012 - 11:44
fuente
0

Otra posibilidad podría ser usar LaTeX o algún otro formato de texto (quizás texinfo o incluso lout ) para la documentación. Partes de ella 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 deben) administrarse como código fuente (por ejemplo, w.r.t. control y compilación de versiones).

    
respondido por el Basile Starynkevitch 27.12.2011 - 22:10
fuente
-2

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

Independientemente de la herramienta que termine utilizando, debe organizar los contenidos del documento con cuidado para poder utilizar la búsqueda de texto y obtener resultados significativos. La organización del contenido del documento, junto con nombres de archivos estándar e inteligentes, podría ser de gran ayuda.

    
respondido por el NoChance 27.12.2011 - 21:46
fuente