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

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

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

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

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

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

Изменить: Чтобы быть уверенным, здесь нет "нетехнических пользователей". Это просто программисты, и документы предназначены для использования только в проектах программирования. Там могут быть PDF файлы, которые будут опубликованы, но это будет просто еще один артефакт сборки, ничего, что должно быть версией.

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

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

Ответ 1

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

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

Ответ 2

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

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

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

Ответ 3

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

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

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

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

Ответ 4

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

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

Ответ 5

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

Ответ 6

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

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

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

Ответ 7

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