¿Qué tipo de sistema de documentación técnica en línea recomendaría? [cerrado]

11

El objetivo es tener un sistema de documentación en línea, con estos requisitos principales:

  • se utilizará principalmente como una etapa intermedia para los documentos técnicos finales de toda nuestra aplicación (que probablemente nunca se completará:]). Por lo general, se usaría así: alguien tiene un problema, lo soluciono y escribo la solución inmediatamente. Lo que sucede ahora es inmanejable: alguien tiene un problema, lo soluciono, tanto yo como alguien estamos contentos, pero 2 meses después alguien más tiene el mismo problema y nadie recuerda cuál fue la solución.
  • accesible desde cualquier lugar, ejecutándose detrás de nuestro servidor apache
  • gestión de usuarios / grupos, permitiendo acceso de solo lectura / lectura-escritura / administrador
  • el formato no es demasiado importante: el texto plano lo haría, aunque el estilo wiki sería mejor
  • barato o gratis

algunas ideas mias:

  • simplemente sirva archivos en un recurso compartido de archivos o mediante ssh (contras: no es demasiado copmatible con Windows, pros: simple, puede ser cualquier tipo de archivo)
  • manténgalo en un SCM (svn / git, ídem como arriba pero más fácil de acceder y controlar el acceso)
  • Confluencia: ya usamos Jira, ¿vale la pena Confluencia? ¿Cómo se integra con Jira?
  • ¿algo más?

No dude en comentar sobre estos o comparta su experiencia con otros sistemas.

documentation stijn
fuente
¿Se está generando la documentación a partir del código (como Javadocs) o se está escribiendo desde cero, como una guía del usuario, o alguna combinación de ambos?
FrustratedWithFormsDesigner
es principalmente más de un guía del usuario, no la documentación del código (bueno, tenemos que, además, generada por doxygen, podríamos incluirlo, pero no es el primer punto de interés)
Stijn
Le entregaría algo de dinero a Spolsky.
Trabajo

Respuestas:

11

Iba a sugerir un Wiki

Como Confluence es un wiki, creo que usarlo con su JIRA es una excelente idea. Tendrá la ventaja de poder vincularse directamente con los problemas de JIRA y, por lo tanto, el código / doc / cualquier cambio realizado, etc.

La clave para cualquier repositorio de documentos de código como este es el aspecto de navegación. No desea páginas desconectadas, difíciles de encontrar, etc. Piense en un "diseño de sitio" como lo haría con un sitio web.

Martijn Verburg
fuente
La confluencia aparentemente puede exportarse en varios formatos planos. Suena como una de las formas más fáciles de pasar de productos fácilmente editables a productos terminados
2
Tenemos Confluence donde trabajo (migramos de MediaWiki) y hace un buen trabajo en varios formatos (Word es el más popular). Pero tenga en cuenta que sus herramientas de edición WYSIWYG son increíblemente defectuosas y el sistema de etiquetado deja mucho que desear, al menos en nuestra instalación.
Philip Regan
+1 para Wiki, también encontré que Trac es muy útil en ese caso, ya que se integra con SVN permitiendo también compartir archivos.
Verificamos una prueba de Confluence y será la solución. Parece ser capaz de hacer mucho más de lo que necesitamos, pero es bastante fácil trabajar con él. Probé Trac hace un par de años y que era un poco demasiado complicado para mi gusto, sobre todo cuando se trataba de plugins, etc.
Stijn