Как лучше всего разработать проектные документы?

Question

Прошло некоторое обсуждение SO (и here), прежде чем о том, как документы в офисе могут быть версиями, однако я думаю, что мой вопрос по-прежнему немного отличается.

Мои проекты программирования начинаются с пустой папки проекта, за исключением подпапки под названием «Дизайнерские документы», которая содержит проект функциональной спецификации проекта для начала и позже расширяется, чтобы содержать спецификации API или что-то еще, что необходимо ,

Естественно, я проверю эти файлы и на SVN. Что я ищу - это хорошие форматы файлов и стратегии, которые хорошо сочетаются со всеми процессами управления версиями, разграничением и слиянием. Например, я считаю, что лучше хранить файлы текстовых процессоров в формате XML, или же различия будут уродливыми и бесполезными для читателей? Вот что я хотел бы сделать:

• сравнения и слияния текстовых документов (должны иметь OOo, хорошо бы иметь MS Word)
• диф (и, возможно, объединить, хотя это может оказаться концептуально сложных) схемных рисунков, таких как диаграммы UML. Я думал, что это могут быть независимые файлы XML/SVG и быть связанными с текстовыми документами, но я не знаю достаточно о том, как эти документы работают, чтобы определить, действительно ли это возможно.
• показать автоматически обновляются номера ревизий внутри текстовых документов (возможно с svn:keywords)

ли кто-нибудь сделал такого рода вещи уже? Вероятно, есть несколько документов и руководств по файлам OOo и т. Д., Которые я мог бы найти, но, хотя я также ценю указания на них, я в основном ищут из первых рук сведения о вещах, которые были или не работали на практике.

---

Edit: Просто, чтобы убедиться, что нет никаких «нетехнических пользователей», участвующих здесь. Это просто программисты, и документы предназначены для использования только в проектах программирования. Там могут быть PDF-файлы, которые будут опубликованы, но это будет просто еще один артефакт сборки, ничего, что должно быть версией.

Тем не менее, мы не действительно хотим использовать Tex или ему подобные. Я знаю, что это здорово и все, но меня просто не беспокоит простой текстовый документ. Мы должны изучить его, получить все лишние пакеты правильно, добавить обработку Tex-to-PDF в наш процесс сборки и т. Д. Это будет похоже на небольшой проект программирования только для двух или трех документов. Во всяком случае, я бы предпочел использовать HTML, но текстовый процессор по-прежнему кажется хорошим вариантом для меня, за исключением того, что я хочу хорошего управления версиями.

Есть еще одна мысль: есть ли что-то вроде SVN-плагина для OOo или наоборот? Или даже, что потребуется, чтобы добавить поддержку SVN для OOo? Как опция «Синхронизировать» в меню «Файл» и текстовое поле «Номер редакции». Я имею в виду, что это не было бы частью нашего бизнеса, но было бы здорово, и в конце концов я босс.

Answer 1

Проблема с OOo - это формат файла, который представляет собой сжатую в сжатом виде группу файлов (попробуйте изменить расширение файла на .zip или .7z). Это затрудняет выполнение различий.

Я смотрел LaTex и DocBook, но создание шаблона стиля для использования довольно сложно. Это сложная часть, которую все угадывают.

Итак, в основном я отказался от получения значимых отличий от документации. Он проверяется как двоичные капли.

Answer 2

Если возможно, я сохраняю все «сырые» файлы в текстовом формате (т. Е. XML/DocBook, обычный текст, LaTeX) в дополнение к визуализированным PDF-файлам под управлением версии версии. Кроме того, я пытаюсь использовать номер версии репозитория Subversion в качестве номера версии для документа.

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

Имея дату и/или номер версии в качестве части верхнего/нижнего колонтитула для каждой страницы также большой плюс, что, как вы избегать людей, смешивая различные версии валяется на их столах ...

Answer 3

Редакторы WYSIWYG (Word, OpenOffice), как правило, не видят причин, по которым кто-то еще должен связываться со своими файлами, поэтому поиск редактора, который нетехнический пользователь может использовать и, который является дружественным к системе управления версиями, невозможен. Исключение: git имеет filter which can look into OpenOffice files. Однако я не уверен, что вы можете использовать расширение ключевого слова.

Предлагаю использовать wiki и неделю обучения для пользователей, как использовать его. Он решает все ваши проблемы (некоторые вики могут быть даже проверены в системе контроля версий). Как я сказал в different post, единственным препятствием является то, что пользователям потребуется несколько дней, чтобы привыкнуть к этой идее. После этого им это понравится.

Answer 4

Мы используем wiki для документации по некоторым нашим проектам. Он имеет отличное отслеживание версий для каждой записи, но не на уровне документа, поэтому мы экспортировали документы и проверили это также для базовых линий.

Answer 5

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

Никакое программное обеспечение не решит проблему несовместимых форматов файлов и не сможет сравнивать разные версии. Инструменты, которые вы используете сейчас, являются неправильными инструментами для работы. Это будет непросто, неудобно и, возможно, дорого изменить свой набор инструментов и ваш образ мышления, но это затраты на то, чтобы достичь того, чего вы хотите, что в конечном итоге будет платить за себя в 10 раз.

Просто подумайте о трудностях, с которыми вы столкнулись первоначально, с документами схемы, диаграммами UML и даже с чем-то простыми, как планирование документа Word. Те работали до этого момента, и они довели вас до сих пор, но единственный реальный путь вперед - перейти к инструментам, которые были разработаны для того, что вам нужно сейчас.

Примечание: конечное решение может быть не вики, но это определенно не то, что вы используете сейчас. Вам нужно немного изучить и попробовать несколько вещей.

Answer 6

Вики, кажется, хорошая идея здесь, но если это не подходит, вы можете рассмотреть возможность использования Sphinx (или аналогичного) с помощью ReStructured Text.

Хотя это тоже было бы «небольшим проектом программирования», оно предоставило бы вам HTML-выход, сохраняя при этом отличительные признаки и читаемые. Полагаю, что это было бы меньше усилий, чем для LaTeX; кривая обучения будет намного меньше; и если вам понадобятся LaTeX и PDF-файлы в будущем, они там ждут вас.

Answer 7

Клиент TortoiseSVN (Windows) для SVN знает достаточно о Open Office, что, когда вы попросите его разложить их, как только он завладеет необходимыми версиями, он открывает Office с открытыми документами, показывая различия. Я использую это много. Я полагаю, что есть даже более благоприятные решения, и аналогичные вещи для Mac/Linux/OS/360 или что-то еще, но для этого очень технического пользователя, который часто чувствует себя очень нетехническим, потому что хочет его обед, TortoiseSVN (http://tortoisesvn.tigris.org/).