Компания настаивает на использовании бинарного формата для всей нашей документации

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

  • Diff-версии документа друг против друга (так что их просмотр - это боль - из-за домена, в котором мы работаем, независимые оценки для всех изменений являются существенными).
  • Grep папка, полная документов для ключевых слов

Что вы используете для написания документации и почему?

Пожалуйста, также дайте мне боеприпасы, чтобы изменить эту ситуацию...

ОТВЕТЫ

Ответ 1

Недавно я начал использовать DocBook XML для написания моей документации.

В верхней части это чистый текстовый формат. Вы можете разбить большой документ на несколько файлов и использовать узлы, чтобы объединить их в одну книгу. Содержание и индекс автоматически генерируются. Внутридокументные ссылки (в пределах произвольного текста, указывающие на главы или разделы) очень просты. И одним нажатием кнопки я могу создать версию с одним html файлом, версию chunked-html (один файл на главу) и версию PDF.

После некоторой настройки и настройки я очень доволен выходом. Документы выглядят великолепно!!

DocBook широко используется настоящими издателями (особенно O'Reilly), и он существует уже более пятнадцати лет, поэтому он достиг определенного уровня зрелости.

С другой стороны, вся обработка выполняется с помощью XSLT, используя специальную коллекцию инструментов. (Мой собственный конвейер docbook включает в себя Python, Java, Xerces, Xalan, Apache FOP и PDF-SAM. Кроме того, официальное распределение таблиц XSLT и мои собственные настройки XSLT.)

DocBook не является готовым решением. Вы не сможете быстро идти, не читая руководство. И если вы ничего не знаете о XSLT, вам придется учиться.

С другой стороны, существует только десяток или два тега XML, которые вам действительно нужно знать для написания документов. (Настоящий опыт вступает в игру во время генерации doc из источников XML.) Если один человек в вашей команде был готов отвечать за запись doc build script, тогда все остальные в команде могли бы просто изучить DTD и сделать достойная работа.

Во всяком случае... DocBook определенно имеет некоторые недостатки. Это не самая простая система для технического авторства. Но это лучший инструмент с открытым исходным кодом, о котором я знаю.

"Книга подрывников" написана в DocBook. Здесь страница со ссылками на разные версии книг (single-html, chunked-html и PDF):

http://svnbook.red-bean.com/

И вот ссылка на источники DocBook XML для первой главы, чтобы вы могли понять, как это работает:

http://sourceforge.net/p/svnbook/source/HEAD/tree/branches/1.7/en/book/ch01-fundamental-concepts.xml

Ответ 2

Для боеприпасов есть верный старый прагматический программист, глава 14: Сила простого текста.

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

Ответ 3

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

Формат, который может быть легко сведен к текстовому (не двоичному), определенно является обязательным. Имея возможность преобразовать его в довольно формат, например, PDF, для нас это не очень важно.

Ответ 4

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

Мы используем MS Word для наших документов (что значительно улучшает предыдущий выбор (Lotus WordPro - ugh!).

Ответ 5

Мы используем wiki - в частности Confluence by Atlassian.

Это коммерческий продукт, и это здорово. Одной из причин, по которой мы выбрали его над свободными/открытыми вики-движками, является то, что он имеет полномасштабный редактор WYSIWYG и другие функции, которые делают его более доступным для пользователей, знакомых с Word.

Мы также придумали опрятный трюк, в котором мы храним изображения, рисунки, каркасы и т.д. в Subversion, а затем вставляем ссылки в вики-документы на эти URL-адреса ресурсов через модуль веб-интерфейса Apache/SVN; примечания о том, как мы это делаем, здесь, если вам интересно.

Ответ 6

Как и организация Dylan, мы также используем отличную Confluence wiki. Я написал статью о том, почему это лучший подход под названием Wiki - это мой текстовый процессор, который должен дать вам некоторые причины для изменения ситуации.

Преимущества использования вики для внутренней документации включают следующее.

  • Пользователи текстовых процессоров втягиваются в изменение макета и типографики, однако хороши ваши шаблоны, которые теряют время и уменьшают согласованность.
  • Вики предоставляет полнотекстовый поиск, который вряд ли будет иметь для вашего тела документов MS Word, написанных всеми.
  • wiki предоставляет историю версий документа; Я никогда не слышал о том, чтобы команда успешно сохраняла все версии в документах Word и всегда могла сравнивать старые версии или использовать систему управления версиями (за исключением, возможно, SharePoint, но в целом с другим сценарием отказа).
  • Вики упрощают гиперссылки между документами; слишком сложно надежно связывать документы в коллекции документов Word, поэтому новые документы в конечном итоге дублируют старый контент в новые монолитные документы, что означает, что они занимают больше времени для чтения и записи.
  • Отдельные страницы вики могут редактироваться разными людьми одновременно, и Confluence может объединять изменения, когда несколько человек одновременно редактируют одну и ту же страницу; сотрудничество сложнее с документом Word, который может редактировать только один человек за раз.
  • Вики вроде Confluence автоматически генерируют страницы навигации на основе структуры и тегов wiki; вам нужен библиотекарь и много дисциплины, чтобы можно было просмотреть большую коллекцию документов Word.
  • Страница wiki обычно загружается и отображается быстрее, чем документ Word.
  • Страница wiki имеет более автоматические метаданные; вам нужны шаблоны и дисциплина, чтобы убедиться, что документы Word всегда имеют название, автор и версию, установленные в свойствах документа и видимые в документе на экране и в печати. ​​

Если вам нужно больше боеприпасов, чем это, то есть много wiki-рекламы на The Atlassian Blog.

Ответ 7

Вы можете запросить документацию в формате OOXML (.docx, в случае Word). Не так идеально, как использование ODT, но, на мой взгляд, это все еще только zip файл с кучей XML файлов внутри.: -)

Ответ 8

Текстовый формат облегчает объединение вашей документации с сгенерированными элементами, такими как JavaDoc, ссылки API или словари данных. Он также масштабируется намного лучше, чем слово, которое сложно использовать для больших документов. Наконец, формат, который позволяет включить, позволяет нескольким авторам работать с документом одновременно.

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

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

Ответ 9

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

Ответ 10

MS Word поддерживает отслеживание изменений документов и экспертную оценку.

Новый формат MS Office полностью основан на XML (чтобы увидеть это, переименуйте файл MS Word.docx в .zip, а затем распакуйте его, чтобы увидеть).

Возможно, Office 2007 может соответствовать как требованиям вашей компании, так и вашим проблемам?

Ответ 11

Вы можете, по крайней мере, сравнивать документы Word, см. команду "Отслеживание изменений" в меню "Экстренное" или использовать программное обеспечение, например DeltaView. Найдено через google поиск первой ссылки на lifehacker.com. Поиск в текстовых документах возможен с помощью Google Desktop Search или других подобных программ, которые индексируют все файлы, которые они могут читать.

Ответ 12

Они настаивают на том, что вы пишете его в Word или только в том, что он доступен в формате Word? Вы можете писать в текстовом формате и автоматически конвертировать его в Word.

Ответ 13

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

И если вы храните документы в VCS, вы заметите, что файлы с обычным текстом или XML-базами намного лучше для этого, потому что вы можете получить diff; Кроме того, изменения между текстовыми файлами обычно сохраняются более эффективно, чем изменения между двоичными файлами.

Ответ 14

Не защищать MS-продукты здесь, но слово MS может различать документы.

Ответ 15

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

Это еще одна причина для инвестиций в Beyond Compare, поскольку это одна из самых отполированных программных продуктов, которые я когда-либо использовал - и это лучшие 30 долларов США (меньше, если вы покупаете несколько), которые я потратил на программное обеспечение

Ответ 17

Легко автоматизировать слово, чтобы извлечь весь текст из текстового документа в текстовый файл. Таким образом, вы можете написать script создание текстовых файлов из текстовых документов и grep, сравнить, контроль версий, просмотреть эти текстовые файлы.

Конечно, это не идеальное решение, так как вы теряете свое красивое форматирование, но оно должно работать.

Ответ 18

Я думаю, что есть программы, которые конвертируют документы Word в обычный текст. Используйте один из них, чтобы преобразовать слово doc в обычный текст, а затем использовать diff, grep и т.д.