¿Debería utilizarse Git para la documentación y la gestión de proyectos? ¿Debería el código estar en un repositorio separado?

Almacenamos documentación en SVN todo el tiempo. De hecho, nuestro manual de usuario completo está escrito en LaTeX y almacenado en SVN. Elegimos LaTeX específicamente porque es un lenguaje basado en texto y es fácil de mostrar las diferencias línea por línea.

También almacenamos algunos archivos sin formato de texto, como archivos .doc de Microsoft Office, hojas de cálculo, archivos .zip, etc. cuando sea necesario ... pero algunos de los beneficios de un RCS se pierden cuando no puede ver las diferencias incrementales.

La clave es realmente asegurarse de que su documentación esté bien organizada, de modo que las personas puedan encontrar (y actualizar) la documentación (y la fuente) cuando la necesiten.

Bueno, depende del formato que use para la documentación. Si es algo basado en texto, todo está bien.

Git también puede almacenar contenido binario y puedes hacer un seguimiento de las revisiones, pero la salida de diferencias no tendrá sentido.

También es posible almacenar documentación en el propio código como perldoc pod, java también tiene algún formato / anotación para esto.

No puedo imaginar por qué crees que podría haber un problema al usar git, o cualquier otro sistema de control de versiones, para la documentación. Al igual que el código fuente, la documentación debe tener un historial completo y la capacidad de revertir a una versión anterior si es necesario. Un sistema de control de versiones es perfecto para esto.

Está claro que usar algún tipo de Sistema de Control de Versiones para almacenar documentos no es un problema. La parte más interesante de la pregunta es si es una buena idea almacenar documentos en la misma SOMBRA como el código fuente. El posible problema aquí es que puede ser difícil establecer diferentes privilegios de acceso para el código y la documentación en ese caso. Y en muchos casos de negocios, las personas necesitarán acceder a documentos, pero no al código fuente, como los departamentos de marketing o BA.

En la empresa que trabajo ponemos la documentación en SVN. Sin embargo, después de algunos conflictos y la necesidad de compartirlo, decidimos moverlo a Mediawiki.

Al principio era trac, luego se mudó a Mediawiki porque era más fácil de usar ...

El principal problema con SVN fue el hecho de compartir el sistema de autorización para SVN.

• Es algo muy bueno tener más que solo código fuente en un repositorio.

  Agrupa todos sus recursos y convierte el proyecto en una entidad cohesiva y centralizada en lugar de una colección dispersa de archivos. Los colaboradores / empleados saben dónde encontrar todo, en lugar de enviar "¿Dónde cambio la documentación de la función x?" .

  Querrás mantener las cosas organizadas. Tenga un sistema para separar el src del images del docs . Siempre puede agregar un .gitignore a un directorio para mantener limpios el historial y el repositorio. Debido a que las confirmaciones de Git se basan en archivos, * puede desacoplar los cambios de origen de los cambios en la documentación tanto como desee.

• Como han dicho otros, Git es ideal para la versión de documentación, siempre y cuando esté basado en texto.

• Estoy completamente de acuerdo; La documentación debe estar versionada justo al lado del código.

Mi credibilidad proviene de ser un usuario de GitHub y contribuir a un proyecto y explorar muchos otros. En mi experiencia, un proyecto completo y unificado es fácil de distinguir de uno que falta a medias. Intento contener todos mis proyectos dentro de directorios individuales siempre que sea posible.

Vine aquí con una pregunta similar. Venimos de un entorno SVN, en el que básicamente no hay que pensar en mantener todos los materiales relacionados con un proyecto en el mismo repositorio. Debido a la naturaleza de SVN, puede revisar partes del repositorio fácilmente, por lo que si solo necesita el código fuente (por ejemplo, una implementación de sitio web), eso no es un problema.

Con Git, las cosas son diferentes. Una comprobación es siempre en el nivel raíz, por lo que si desea colocar todo en el mismo repositorio, siempre tendrá la misma estructura de directorios. Un enfoque que he encontrado es colocar todo en ramas separadas, es decir, tiene ramas de código (que normalmente serían sus ramas maestras, de desarrollo, etc. normales) y una rama doc, que tiene su propia estructura de directorios separada. No estoy seguro de que esa sea la mejor idea, pero es una sugerencia que evita el problema, y me imagino que está en la base de su pregunta.

Uso un wiki para documentos internos ... obtenga una revisión MÁS acceso prominente / fácil edición. Cuando la documentación no esté sincronizada, actualícela en ese momento. Para la documentación del usuario final, considere una herramienta profesional como Madcap Flare Ellos usan un dialecto XML para compartir , componiendo y transformando documentación.

En el código, los pensamientos suelen estar separados línea por línea. Tiendo a escribir documentación con líneas suaves. Cuando confirmo esos archivos, las líneas son un párrafo entero. Eso no es muy útil para leer en git diff . Ese es el problema que estaba tratando de resolver cuando busqué en Google y encontré esta página. Gracias a Arne Hartherz por presentarme a git diff --word-diff . Es posible que te guste git diff --color-words aún mejor.