¿Son los wikis realmente apropiados para almacenar documentos para el desarrollo de software? [cerrado]

18

Todos saben que el desarrollo de software bien documentado conduce al éxito. Sin embargo, generalmente significa que no solo el texto simple sino también el contenido binario estarán involucrados en el documento, como un diagrama UML. Y he escuchado a mucha gente decir eso. El sistema de control de versiones no es el lugar apropiado para los archivos binarios. Entiendo totalmente y estoy de acuerdo con el tema. Pregunté a varios desarrolladores experimentados dónde debería estar el mejor lugar para almacenar documentos y la respuesta que obtuve fue "wiki". Wiki es bueno, pero consideré otro problema potencial. ¿Cómo se puede conectar el código fuente que se ha almacenado en un sistema de control de versiones a su documento relacionado en wiki? Digamos que alguien clona el repositorio de git o mercurial. ¿Cómo puede él / ella encontrar el documento fácilmente? ¿O acabo de perder algo?

Sé que algunos sistemas wiki tienen la capacidad de integrarse con los sistemas de control de código fuente. Pero mi preocupación no es sobre la capacidad de integración. Si ha clonado el código fuente de un repositorio git y después de un tiempo se sube a un tren y desea continuar trabajando sin conexión en el tren (que es una gran característica de DVCS). Entonces, de repente te das cuenta de que no tienes acceso al documento ya que estás trabajando sin conexión en el tren. Por otro lado, si el documento se almacenó en el repositorio de git, tendría acceso al documento con el repositorio clonado.

Edison Chuang
fuente
3
FYI: Wiki no es un acrónimo, es una palabra hawaiana que significa "rápido".
Jörg W Mittag
El hecho de que la documentación incluya binarios no es realmente una buena razón para evitar almacenarlo en su sistema de control de versiones. Los VCS pueden manejar fácilmente archivos binarios. Y si lo almacena en el VCS de su proyecto, tiene la ventaja de poder bifurcar su documentación cuando bifurca su proyecto.
JW01
En cuanto a trabajar sin conexión: la solución de fuerza bruta es simplemente descargar las páginas que desee utilizando un lector sin conexión. Más práctico es clonar de alguna manera todo el wiki, si es práctico (por ejemplo, copie la base de datos subyacente y tenga su propia instalación del wiki). Los wikis basados ​​en VCS son una solución aún más elegante. A menudo trabajo sin conexión y, por lo general, basta con descargar las páginas que necesito regularmente.
sleske

Respuestas:

16

¿WIKI es realmente apropiado para almacenar documentos para el desarrollo de software?

En lugar de escribir documentos, archivos PDF y otro tipo de archivos, ¿por qué no desata todo el potencial de WIKI como herramienta de colaboración? Puede escribir sus documentos allí, adjuntar sus diagramas y aún mejor: si usa Fitnesse , puede convertir sus páginas wiki en documentación realmente útil y viva, ya que pueden convertirse en una especificación ejecutable.

Todos saben que el desarrollo de software bien documentado conduce al éxito

Cuidado con este. Los documentos NO LLEVARÁN AL ÉXITO, ya que no convertirán el código basura en uno bueno. Pero los documentos son parte del camino hacia el software exitoso. Pero solo una parte y no reemplazarán las buenas prácticas y las buenas personas.

Fernando
fuente
8

Como las respuestas múltiples apuntan a Trac como una sugerencia, me gustaría sugerir una alternativa similar, pero mejor en mi opinión: Redmine .

Redmine es una solución de gestión de proyectos, que incluye Wiki, Repositorio de documentos e integración de control de versiones. También está escrito en Ruby on Rails y, en mi experiencia, es mucho más fácil de extender y hackear que Trac.

Más que todo, es realmente fácil de usar y es fácil hacer que el equipo lo use.

caracteristicas:

  • Múltiples proyectos de apoyo
  • Control de acceso flexible basado en roles
  • Sistema flexible de seguimiento de problemas
  • Diagrama de Gantt y calendario
  • Gestión de noticias, documentos y archivos.
  • Feeds y notificaciones por correo electrónico
  • Por proyecto wiki
  • Por foros del proyecto
  • Seguimiento de tiempo
  • Campos personalizados para problemas, entradas de tiempo, proyectos y usuarios.
  • Integración SCM (SVN, CVS, Git, Mercurial, Bazaar y Darcs)
  • Creación de problemas por correo electrónico
  • Soporte de autenticación LDAP múltiple
  • Soporte de autorregistro de usuario
  • Soporte multilenguaje
  • Soporte de múltiples bases de datos.

Para sus necesidades fuera de línea, no me gusta la idea de desordenar el control de versiones con documentos de diseño. Estoy seguro de que tiene sus razones para preguntar esto, pero ¿con qué frecuencia está desconectado y necesita acceso a los documentos de diseño? Las posibilidades son realmente un caso de esquina.

Vitor Py
fuente
+1 Uso Redmine en el trabajo y es realmente un gran sistema.
Luiz Damim
5

Algunos wikis (por ejemplo, Ikiwiki ) tienen la capacidad de almacenar sus datos en Git, como usted mencionó. Dado eso, puede vincular la documentación como un submódulo Git en su repositorio fuente habitual.

Con la configuración anterior, extraer la fuente y actualizar los submódulos extraería la última copia de la documentación. Fuera de línea, puede editar cada uno a voluntad. Cuando regresa a una red, ambos pueden retroceder a la ubicación compartida que esté utilizando.

La parte incómoda de esto es que cada vez que se actualiza la documentación (incluso a través de la interfaz web Ikiwiki), también necesitaría actualizar el submódulo correspondiente en el repositorio de origen de Git. Sin embargo, esto podría automatizarse fácilmente.

Greg Hewgill
fuente
Interesante. ¿Hay alguna diferencia entre poner el documento en el repositorio de git y almacenar el documento a través de ikiwiki?
Edison Chuang
1
@Edison Chuang: No, no lo hay. De hecho, dado un clon de un repositorio de ikiwiki, puede editar las páginas usando el editor de texto de su elección (no tiene que usar un cuadro de entrada de texto basado en el navegador). Incluso puede tener diferentes ramas de la wiki, para mantener una instantánea de la documentación anterior o lo que sea.
Greg Hewgill
Parece que el documento puede almacenarse en el sistema de control de versiones sin ningún problema a pesar de que los archivos binarios. El desarrollador puede usar herramientas como ikiwiki para convertir páginas wiki en páginas HTML a pedido.
Edison Chuang
+1 para el motor wiki de Ikiwiki; El motor wiki de Hatta es una idea similar para los repositorios de Mercurial.
David Cary
ISTR Fitnesse también almacena sus páginas wiki como archivos de texto, por lo que también pueden mantenerse en su sistema de control de versiones si lo desea. Si bien sus propósitos principales son las pruebas, no hay razón para no usarlo como un sistema wiki de propósito general para su documentación también.
Julio
4

Tiene sentido almacenar la documentación en el mismo repositorio que el código fuente. Sphinx me parece una buena opción.

Brecht Machiels
fuente
2

Trac proporciona una interfaz para Subversion, un Wiki integrado y prácticas funciones de informes. http://trac.edgewall.org/
Pero no sé acerca de su pila instalada.

Quirón
fuente
Y una buena interfaz para Mercurial. Y es eminentemente pirateable.
Frank Shearar
0

No intentaría conformarme con el trabajo fuera de línea. Usaría el recurso con el que sea más fácil trabajar para todos. Por ejemplo, si está escribiendo código PHP, sugeriría usar documentación en línea que PHPDocumentor pueda generar . Se puede generar en cualquier lugar y hay un complemento para Trac . Luego, en línea o apagado, también tiene acceso a la documentación, bastante rápido.

La clave está en la usabilidad. Si es difícil de mantener, comenzará a sufrir. Cuando comienza a sufrir, la calidad de la documentación disminuye. Cuando eso sucede, la gente comienza a quejarse y luego todo va cuesta abajo.

Chuck Burgess
fuente
-1

Usar un wiki para almacenar documentación tiene mucho sentido para mí.

Veracity es un ejemplo de un DVCS que permite una mayor integración del contenido wiki y el código fuente.

Jace Browning
fuente