Какие документы следует хранить в контроле версий и как их хранить?

Я нашел несколько похожих вопросов (здесь, здесь и здесь), спрашивая о хранении документов в контроле версий. У меня есть более конкретное требование и общий вопрос. Особым требованием является то, что я хочу использовать Git. Более общий вопрос: как документы (для проектирования, тестирования, общей практики, советы и т.д. Проекта) должны храниться в Git? В более широком смысле, какие документы следует хранить?

Я могу придумать несколько способов:

Документы Word/Open Office. Новый Office Word имеет формат docx, который застегивает документы, но также имеет распакованный формат XML, который можно использовать для эффективного хранения различий в Git. Функция diff все еще не работает, поскольку XMLs сжимаются на одной строке. Это не лучше, чем сохранение двоичного файла в Git.
Wiki. Какие распространенные вики существуют? Это было бы похоже на какую-то латексную вещь, где документы записываются и компилируются/рассматриваются как вики.
Латекс - но, используя его для бумаг, я нахожу его довольно непригодным для документов. Есть ли эквивалент документации? (Как написаны man-страницы?)
Обычные текстовые форматы, но этого недостает из-за отсутствия диаграмм, которые вызывают еще одну точку.

Как следует хранить изображения? В чем они должны состоять в первую очередь? Я развиваюсь в среде Linux, но некоторые другие участники проекта находятся в Windows. Что такое кросс-платформенное решение, похожее на Visio? И, конечно же, он не должен создавать двоичные файлы для хранения в Git. Как тогда это связано с документацией? (Например, аналогично тому, как Latex может ссылаться на другие диаграммы при компиляции.)

Ответ 1

При выборе формата документа вы должны убедиться, что члены команды (или вы работаете в одиночку?) удобны в работе с самим форматом.

Хранение - это не столько проблема, сколько возможность видеть различия между версиями и слиянием. По моему опыту, ничто не сравнится с текстовыми форматами, которые можно редактировать свободно в любом текстовом редакторе. Это исключает HTML и любой формат на основе XML. DocBook - едва ли используемое исключение.
Хорошая вики, которая может использовать любую из популярных систем управления версиями и настраиваться распределенным образом, IkiWiki. С помощью IkiWiki разметка выполняется в плагинах, поэтому вы можете выбрать формат ввода для каждого документа. "Default", Markdown довольно близок к форматам обычного текста.
Если вы недовольны использованием LaTeX, не используйте его. Я считаю, что он не подходит для быстрых заметок. Страницы man написаны в nroff, но многие используют другие форматы, такие как POD.

Некоторые проекты, которые стремятся быть альтернативой Visio, - это Kivio (KDE) и Dia (Gtk/Gnome). Я сам не использовал Visio, поэтому я не могу комментировать их функциональные возможности. Вероятно, это зависит от того, какие виды визуальных образов/диаграмм вы хотите создать. UML? Технологические схемы?

Ответ 2

Моя компания хранит документы Word в SVN и обращается к ним через TortoiseSVN.

Tortoise использует Word, встроенный в функцию отслеживания изменений, чтобы показать вам "разницу" двух версий.

Это работает очень хорошо, но требует Windows и Word.

Edit:

Возможно, вы тоже можете работать с git. Если вы установите TortoiseSVN, посмотрите в %PROGRAMFILES%\TortoiseSVN\Diff-Scripts\, вы увидите, что делает черепаха.

Если вы используете git, я предполагаю, что вам достаточно 1337, чтобы взломать его, чтобы работать на вас:)

Ответ 3

Для документов Word попробуйте использовать RTF (форматированный текстовый формат), который является в основном текстовым. Другая возможность - это HTML. Это текст, поэтому вы должны иметь возможность делать разницы на них.

Большинство Wikis распределены тем, что они предназначены для совместной работы. Я думаю, вы действительно спрашиваете, есть ли размещенные решения или вам нужно управлять ими. Взгляните на http://www.atlassian.com/.

Ответ 4

Git может обрабатывать двоичные файлы так же, как и текстовые файлы. Вместо явного хранения различий Git хранит все предыдущие версии файлов в репозитории. Объекты репозитория затем сжимаются для экономии места. Разновидности реконструируются на лету всякий раз, когда вы просите их.

Таким образом, учитывая только дисковое пространство, существует небольшая разница между сохранением документа XML Office, несжатого в Git, и сохранения зашифрованной версии этого же документа. Единственная разница была бы относительной производительностью Zip против любого сжатия Git, которое выбирает использовать.

Ответ 5

Большинство форматов документов не очень хорошо работают с контролем источника. Почти все, что вы перечислите, либо эффективно представляет собой двоичный формат, либо свернутую разметку, которая не будет сильно отличаться. Пока вы просто хотите версии документов и не заботитесь о diff, используйте любой формат, который вам нравится. Я предпочитаю документы Microsoft Word, потому что вы можете использовать встроенную систему отслеживания изменений и комментариев для отслеживания дельт между документами.

Что касается того, какие документы хранить, я бы рекомендовал хранить все, что вы будете использовать позже. Какие документы могут быть использованы кем-то для продолжения проекта, если вы уйдете? Какие документы были бы полезны для того, чтобы привести нового человека к успеху? Это означает спецификации, но не такие документы, как графики сжигания.

Чтобы ответить на часть вики вашего вопроса, выберите DokuWiki. Он хранит все в текстовых файлах, поэтому их можно будет легко добавить в систему управления версиями.

Ответ 6

Я только что жил с тем, что не могу отслеживать изменения в бинарных форматах файлов через систему управления версиями, но я все равно использую его, поскольку это полезно. Обратите внимание, что обычно большинство этих типов файлов являются рабочими продуктами, которые будут выпущены (руководства пользователя, документы и т.д.).

Для ранних артефактов проекта, таких как требования и первоначальные проекты, я обычно использую текстовые документы - не потому, что я могу отслеживать изменения, а потому, что мне нравится использовать мою среду IDE.

Я никогда не был "укушен" тем фактом, что изменение не может быть "разбросано" в управлении версиями. Комментарии коммита и другие рекомендации по документированию вокруг изменения важного двоичного документа обычно компенсируют отсутствие видимости - в том, что есть другой след, если вы его ищете.

Я согласен, что это не идеально, но я не думаю, что это действительно стоит беспокоиться.

Возможно, я просто привык к идее набора файлов, которые я мог бы отслеживать столько, сколько захочу.

Я много использую в управлении версиями, но также использую отслеживание дефектов для некоторых вещей с временными временными ограничениями.

Ответ 7

Для OOo, текстовых документов и других двоичных файлов вы должны взглянуть на pro git http://git-scm.com/book/ch7-2.html