Компания настаивает на использовании двоичного формата для всей нашей документации
Я работаю в компании, которая по какой-то причине настаивает на том, чтобы вся наша документация по разработке была в формате MS Word. Что, будучи двоичным форматом, означает, что мы не можем:
- Различаются версии документа друг против друга (поэтому рецензирование их является проблемой - из-за области, в которой мы работаем, рецензирование всех изменений имеет важное значение)
- Grep папка-полно документов по ключевым словам
Что вы используете для написания документации и почему?
Пожалуйста, дайте мне боеприпасы, чтобы изменить эту ситуацию с...
19 ответов
Недавно я начал использовать DocBook XML для написания своей документации.
С другой стороны, это чистый текстовый формат. Вы можете разбить большой документ на несколько файлов и использовать узлы, чтобы объединить их в одну книгу. Содержание и указатель генерируются автоматически. Ссылки внутри документа (в произвольном тексте, указывающие на главы или разделы) очень просты. И одним нажатием кнопки я могу создать версию с одним html-файлом, версию chunked-html (один файл на главу) и версию PDF.
После некоторых настроек и настроек я очень доволен результатом. Документы выглядят великолепно!
DocBook широко используется настоящими издателями (прежде всего, O'Reilly), и существует уже более пятнадцати лет, поэтому он достиг определенного уровня зрелости.
С другой стороны, вся обработка выполняется с помощью XSLT с использованием специального набора инструментов. (Мой собственный конвейер документации включает в себя Python, Java, Xerces, Xalan, Apache FOP и PDF-SAM. Плюс официальное распространение таблицы стилей XSLT и мои собственные настройки XSLT.)
DocBook - это не готовое решение. Вы не сможете быстро приступить к работе, не прочитав руководство. И если вы ничего не знаете о XSLT, вам придется учиться.
С другой стороны, есть только дюжина или два тега XML, которые вам действительно нужно знать, чтобы написать документы. (Реальный опыт вступает в игру при создании документации из источников XML.) Если один человек в вашей команде желал быть ответственным за написание сценария сборки документа, то все остальные в команде могли бы просто изучить DTD и сделать достойную работу содействие.
Во всяком случае... DocBook определенно имеет некоторые недостатки. Это не самая простая система для технического авторства. Но это лучший инструмент с открытым исходным кодом, который я знаю.
"Книга Subversion" написана в DocBook. Вот страница со ссылками на разные версии книг (single-html, chunked-html и PDF):
А вот ссылка на исходные тексты DocBook XML для первой главы, чтобы вы могли понять, как это работает:
http://sourceforge.net/p/svnbook/source/HEAD/tree/branches/1.7/en/book/ch01-fundamental-concepts.xml
Для боеприпасов есть верный старый прагматичный программист, глава 14: "Сила простого текста".
Как прагматичные программисты, наш базовый материал - это не дерево или железо, это знания. Мы собираем требования как знания, а затем выражаем эти знания в наших проектах, реализациях, тестах и документах. И мы считаем, что лучший формат для постоянного хранения знаний - это простой текст. С помощью простого текста мы даем себе возможность манипулировать знаниями как вручную, так и программно, используя практически все имеющиеся в нашем распоряжении инструменты.
В Word есть отслеживание изменений для документов (хотя оно работает только до тех пор, пока вы не примете изменения), и вы также можете выполнять их поиск (текст не зашифрован). Так что я не уверен, что любой из ваших аргументов выдержит проверку. Я хотел бы дать вам боеприпасы, чтобы изменить это, но я стал измученным и циничным с возрастом.
Мы используем MS Word для наших документов (что является огромным улучшением по сравнению с предыдущим выбором (Lotus WordPro - тьфу!).
Мы используем вики (в частности ту, что предоставлена Trac) по двум причинам, которые вы упомянули. Кроме того, если нам действительно нужно, мы можем получить текстовую версию разметки и манипулировать ею также в текстовой среде (например, как часть комментариев SVN во время коммита).
Формат, который можно легко преобразовать в текстовый (недвоичный), безусловно, является обязательным. Возможность конвертировать его в красивый формат, такой как PDF, для нас не очень важен.
Мы используем вики - в частности, Confluence от Atlassian.
Это коммерческий продукт, и это здорово. Одна из причин, по которой мы выбрали его среди бесплатных / открытых вики-движков, заключается в том, что он имеет полноценный редактор WYSIWYG и различные другие функции, которые делают его более доступным для пользователей, знакомых с Word.
Мы также придумали изящный прием, в котором мы храним изображения, рисунки, каркасы и т. Д. В Subversion, а затем встраиваем ссылки в вики-документы в URL этих ресурсов через модуль веб-интерфейса Apache/SVN; заметки о том, как мы это делаем, здесь, если вам интересно.
Как и организация Дилана, мы также используем отличную вики Confluence. Я написал статью о том, почему этот лучший подход, под названием Wiki, является моим текстовым процессором, который должен дать вам несколько причин изменить ситуацию.
Преимущества использования вики для внутренней документации включают следующее.
- Пользователи текстовых процессоров втягиваются в изменение макета и типографики, какими бы хорошими ни были ваши шаблоны, что тратит время и снижает согласованность.
- Вики предоставляет полнотекстовый поиск, который вы вряд ли будете иметь в своем теле документов MS Word, написанных всеми.
- Вики предоставляет историю версий документа; Я никогда не слышал, чтобы команда успешно сохраняла все ревизии в документах Word и всегда могла сравнивать старые версии или использовать систему контроля версий (за исключением, возможно, SharePoint, но это совершенно другой сценарий сбоя).
- Вики облегчает гиперссылки между документами; слишком трудно надежно связать документы в коллекции документов Word, поэтому новые документы в конечном итоге дублируют старый контент в новые монолитные документы, а это означает, что им требуется больше времени для чтения и записи.
- Отдельные вики-страницы могут редактироваться разными людьми одновременно, и Confluence может объединять изменения, когда несколько человек редактируют одну и ту же страницу одновременно; сотрудничество сложнее с документом Word, который может редактировать только один человек одновременно.
- Вики, как Confluence, автоматически генерирует страницы навигации на основе структуры и тегов вики; вам нужен библиотекарь и много дисциплины, чтобы можно было просматривать большую коллекцию документов Word.
- Вики-страница обычно загружается и отображается быстрее, чем документ Word.
- На вики-странице больше автоматических метаданных; вам нужны шаблоны и дисциплина, чтобы убедиться, что документы Word всегда имеют заголовок, автора и версию, установленные в свойствах документа и видимые в документе на экране и в печати.
Если вы хотите больше боеприпасов, чем это, тогда есть много вики-продвижения в блоге Atlassian.
Текстовый формат облегчает объединение вашей документации с сгенерированными элементами, такими как JavaDoc, ссылки на API или словари данных. Он также масштабируется намного лучше, чем word, что трудно использовать для больших документов. Наконец, формат, который позволяет включать, позволяет нескольким авторам работать над документом одновременно.
LaTeX и FrameMaker (две системы, которые я использовал для этого) имеют значительно превосходные возможности индексирования и перекрестных ссылок и имеют либо собственный текстовый формат, либо текстовую версию их собственного формата, который может быть включен (MIF в случае Framemaker), Они также намного более стабильны, чем слова.
Я создал инструменты, которые читают словари данных и генерируют документацию, которая может быть включена в более крупный документ со стабильной индексацией и двусторонними перекрестными ссылками. Функциональная спецификация для этого продукта была сделана с LaTeX таким образом, и я получил еще один концерт в компании. Я также разработал аналогичный процесс с FrameMaker.
Вы могли бы попросить документацию быть в OOXML (.docx, в случае Word) формат. Однако, на мой взгляд, он не такой идеальный, как использование ODT, это все же просто zip-файл с кучей XML-файлов внутри.:-)
Вся команда разработчиков против этого требования, или это небольшая группа? Если это вся команда, просто проигнорируйте мандат и используйте текстовый формат - не первый раз, когда сотрудники игнорируют глупое правило. Работает особенно хорошо, если в прошлом вы не суетились по этому поводу. Если у вас есть, руководство может особенно внимательно смотреть на ваши документы.
Вы можете хотя бы сравнить документы Word, увидеть команду "Отслеживать изменения" в меню "Дополнительные" или использовать программное обеспечение, такое как DeltaView. Нашел через поиск Google первую ссылку на lifehacker.com. Поиск в текстовых документах должен быть возможен с помощью Google Desktop Search или других подобных программ, которые индексируют все файлы, которые они могут читать.
MS Word поддерживает отслеживание изменений документа и рецензирование.
Новый формат MS Office полностью основан на XML (чтобы увидеть это, переименуйте файл MS Word .docx в.zip, затем распакуйте его, чтобы увидеть).
Может быть, Office 2007 может соответствовать требованиям вашей компании и вашим интересам?
Они настаивают на том, чтобы вы написали это в Word или только в формате Word? Вы можете написать в текстовом формате и автоматически преобразовать его в Word.
Разве вы не храните файлы документации в какой-либо системе контроля версий, в идеале вместе с исходным кодом? Я бы порекомендовал сделать это (облегчает получение документации для старых выпусков программного обеспечения).
И если вы сохраните документы в VCS, вы заметите, что обычный текст или XML-файлы намного лучше для этого, потому что вы можете получить diff; Кроме того, изменения между текстовыми файлами обычно хранятся более эффективно, чем изменения между двоичными файлами.
Также обратите внимание на рекомендуемые наборы инструментов для DocBook.
Должно быть легко автоматизировать слово, чтобы извлечь весь текст из документа Word в текстовый файл. Таким образом, вы можете написать скрипт, создающий текстовые файлы из Word Docs, и grep, сравнить, контроль версий, просмотреть эти текстовые файлы.
Конечно, это не идеальное решение, так как вы теряете свое красивое форматирование, но оно должно работать.
Не для защиты продуктов MS здесь, но MS Word может различать документы.
Есть много инструментов для сравнения текстовых документов. В настоящее время я использую скрипт Python, который помещает командную строку во встроенную функцию сравнения и слияния слова.
Я думаю, что есть программы, которые конвертируют документы Word в простой текст. Используйте один из них, чтобы преобразовать слово doc в обычный текст, а затем используйте diff, grep и т. Д.
Если вы используете Beyond Compare в качестве инструмента сравнения для вашей системы контроля версий (как у нас с Perforce), он покажет вам различия между версиями ваших документов Word. По общему признанию, это только показывает текстовые различия - изменения форматирования не показаны - но этого обычно достаточно, чтобы вы увидели, что изменилось.
Это еще одна причина инвестировать в Beyond Compare, так как это одна из самых совершенных программ, которые я когда-либо использовал - и это лучшие 30 долларов (меньше, если вы купите несколько), которые я потратил на программное обеспечение.