¿Qué documentos deben almacenarse en el control de la versión y cómo deben almacenarse?

He encontrado algunas preguntas similares ( aquí , aquí y aquí ) sobre cómo almacenar documentos en el control de versiones. Tengo un requisito más específico y una pregunta general. El requisito específico es que quiero usar Git. La pregunta más general es, ¿cómo deben almacenarse los documentos (para layout, testing, prácticas generales, sugerencias, etc., de un proyecto) en Git? En términos más generales, ¿qué documentos deben almacenarse?

Puedo pensar en algunas maneras:

  1. Word / documentos de Open Office. El nuevo Office Word tiene formatting docx, que comprime documentos, pero también tiene un formatting XML descomprimido que se puede usar para almacenar eficientemente diffs en Git. Sin embargo, la característica de diferencia aún está rota, ya que los XML se agrupan en una sola línea. Esto no es mejor que save un file binary en Git.
  2. Wiki. ¿Qué wikis distribuidos existen? Sería como una especie de látex donde los documentos son escritos y comstackdos / vistos como una wiki.
  3. Látex, pero al usarlo para documentos, me parece bastante inadecuado para documentos. ¿Hay una documentation equivalente? (¿Cómo se escriben las páginas man?)
  4. Formatos de text sin formatting, pero esto es bastante deficiente debido a la falta de diagtwigs, lo que trae a queueción otro punto.

¿Cómo deben almacenarse las imágenes? ¿En qué deberían estar compuestos en primer lugar? Estoy desarrollando en un entorno Linux, pero algunos otros participantes en el proyecto están en Windows. ¿Qué solución multiplataforma hay que se parezca a Visio? Y, por supuesto, no debería crear files binarys para almacenarlos en Git. ¿Cómo sería esto vinculado con la documentation? (Por ejemplo, similar a cómo Latex puede hacer reference a otros diagtwigs cuando se comstack).

Al decidir qué formatting de documento eliges, debes asegurarte de que los miembros del equipo (¿o trabajas solo?) Se sientan cómodos trabajando con el formatting en sí.

  1. El almacenamiento no es tanto el problema como lo es poder ver las diferencias entre las versiones y la fusión. En mi experiencia, nada mejor que los formattings de text que se pueden editar libremente en cualquier editor de text. Esto excluye HTML y sobre cualquier formatting basado en XML. DocBook es una exception apenas utilizable.

  2. Una buena wiki que puede usar cualquiera de los populares sistemas de control de versiones y configurarse de manera distribuida es IkiWiki . Con IkiWiki, el análisis de marcado se realiza en complementos, por lo que puede elegir el formatting de input por documento. El "pnetworkingeterminado", Markdown se acerca mucho a los formattings de text sin formatting.

  3. Si no está satisfecho con el uso de LaTeX, no lo use. Creo que no es adecuado para tomar notas rápidas. Las páginas man están escritas en nroff, pero muchas personas usan otros formattings, como POD .

Algunos proyectos que se esfuerzan por ser alternativas a Visio son Kivio (KDE) y Dia (Gtk / Gnome). No he utilizado Visio en sí mismo, por lo que no puedo comentar sobre sus sets de características. Probablemente depende de qué tipo de imágenes / diagtwigs quieras crear. UML? Diagtwigs de flujo?

Mi empresa almacena documentos de Word en SVN y accede a ellos a través de TortoiseSVN.

Tortoise utiliza la function de seguimiento de cambios incorporada de Word para mostrarle una "diferencia" de dos revisiones.

Esto funciona realmente bien, pero requiere Windows y Word.

Editar:

Probablemente también puedas hacer que esto funcione con git. Si instala TortoiseSVN, busque en %PROGRAMFILES%\TortoiseSVN\Diff-Scripts\ , verá lo que está haciendo la tortuga.

Si estás usando git, supongo que tienes 1337 suficiente para hackearlo para que funcione para ti 🙂

Para documentos de Word, intente usar RTF (formatting de text enriquecido), que es básicamente text. Otra posibilidad sería HTML. Son text, por lo que debería poder hacer diffs en ellos.

La mayoría de los wikis se distribuyen porque están diseñados para queueboración. Creo que realmente está preguntando si hay soluciones alojadas o si tiene que administrarlas. Eche un vistazo a http://www.atlassian.com/ .

Git puede manejar files binarys tan bien como files de text. En lugar de almacenar explícitamente los diffs, Git almacena todas las revisiones previas de los files en el repository. Los objects del repository se comprimen para ahorrar espacio. Los Diffs se reconstruyen sobre la marcha cada vez que los solicite.

Por lo tanto, considerando solo el espacio en disco, hay poca diferencia entre almacenar un documento XML Office descomprimido en Git y almacenar una versión comprimida de ese mismo documento. La única diferencia sería el performance relativo de Zip frente a cualquier compression que Git decida usar.

La mayoría de los formattings de documentos no juegan terriblemente bien con el control de fuente. Casi todo lo que enumera es efectivamente un formatting binary o un marcado complicado que no se diferenciará. Siempre que solo desee versiones de documentos y no le importe la diferencia, use el formatting que desee. Prefiero los documentos de Microsoft Word porque puede usar el sistema incorporado de seguimiento de cambios y comentarios para rastrear deltas entre documentos.

En cuanto a qué documentos almacenar, le recomiendo que guarde todo lo que tenga para más adelante. ¿Qué documentos podría utilizar alguien para continuar el proyecto en caso de que se vaya? ¿Qué documentos serían útiles para poner a una persona nueva al tanto? Esto significa especificaciones, pero no documentos como charts burndown.

Para responder a la parte wiki de tu pregunta, echa un vistazo a DokuWiki . Almacena todo en files de text por lo que sería muy fácil de agregar a un sistema de control de origen.

Acabo de vivir con el hecho de que no puedo rastrear los cambios en los formattings de file binarys a través de un sistema de control de versiones, pero lo uso de todos modos, ya que es útil. Tenga en count que normalmente la mayoría de estos types de files son productos de trabajo que se lanzarán (guías de usuario, documentos, etc.)

Para los primeros artefactos del proyecto, como los requisitos y los layouts iniciales, tiendo a usar documentos de text, no porque pueda seguir los cambios, sino porque me gusta usar mi IDE para ello.

Nunca he sido realmente "mordido" por el hecho de que un cambio no puede ser "diferido" en el control de la versión. Los comentarios de compromiso y otras pautas de documentation sobre el cambio de un documento binary importante generalmente compensan esa falta de visibilidad, en el sentido de que hay otro path si lo busca.

Estoy de acuerdo en que esto no es ideal, pero no creo que realmente valga la pena preocuparse.

Tal vez me acabo de acostumbrar a la idea de un set de files que podría rastrear tanto como me gustaría.

Puse mucho control de versiones, pero también uso el seguimiento de defectos para algunas cosas con períodos de vida que son temporales.

Para OOo, documentos de Word y otros files binarys, debería echar un vistazo a pro-git http://git-scm.com/book/ch7-2.html