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.
fuente
Respuestas:
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.
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.
fuente
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:
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.
fuente
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.
fuente
Tiene sentido almacenar la documentación en el mismo repositorio que el código fuente. Sphinx me parece una buena opción.
fuente
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.
fuente
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.
fuente
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.
fuente