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

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

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

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

я создал инструменты, которые читают словари данных и генерируют документацию, которая может быть включена в больший документ со стабильной индексацией и двухсторонними перекрестными ссылками. функциональная спецификация для Этот продукт был сделан с ЛАТЕКСОМ таким образом и получил меня другой концерт с компанией. Я также разработал подобный процесс с FrameMaker.

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

Мы используем Wiki - конкретно Слияние Atlassian.

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

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

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

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

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

, Если Вы хотите больше боеприпасов, чем это, затем существует большое продвижение Wiki на Блог .

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

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

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

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

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

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

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

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

После некоторой тонкой настройки и настройки, я очень доволен выводом. Взгляд документов большой !!

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

, С другой стороны, вся обработка сделана с XSLT, с помощью специального набора инструментов. (Мой собственный конвейер DocBook включает Python, Java, Xerces, Xalan, ЩЕГОЛЯ Apache и PDF-SAM. Плюс официальное распределение таблицы стилей XSLT и мои собственные настройки XSLT.)

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

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

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

"Книга Подверсии" записана в DocBook. Вот страница со ссылками на различные книжные версии (единственный HTML, разделенный на блоки HTML и PDF):

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

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

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

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

Существует много инструментов для сравнения документа слова. Я в настоящее время использую сценарий Python, который помещает командную строку на встроенное, сравнивают и объединяют функциональность слова.

http://nicolas.lehuen.com/index.php/post/2005/06/30/60-comparing-microsoft-word-documents-stored-in-a-subversion-repository

Должно быть легко автоматизировать слово для извлечения всего текста из документа слова в текстовый файл. Таким образом, Вы могли записать сценарий, создающий текстовые файлы из документов в формате Word и grep, выдержать сравнение, управление версиями, Обзор эти текстовые файлы.

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

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

Это - просто другая причина вложить капитал во Вне всякого сравнения, как это - одна из наиболее полируемых частей программного обеспечения, которое я когда-либо использовал - и это - лучшие доллары за 30$ (Меньше при покупке нескольких), я потратил на программное обеспечение

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

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

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

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

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

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

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

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

Простой, глупый способ:

system("kdestroy");

Или если вы хотите быть более легальным, просто проверьте источник kdestroy реализации. krb5 _ cc _ destroy () является соответствующим вызовом функции.

http://code.activestate.com/recipes/65212/

def base10toN(num,n):
    """Change a  to a base-n number.
    Up to base-36 is supported without special notation."""
    num_rep={10:'a',
         11:'b',
         12:'c',
         13:'d',
         14:'e',
         15:'f',
         16:'g',
         17:'h',
         18:'i',
         19:'j',
         20:'k',
         21:'l',
         22:'m',
         23:'n',
         24:'o',
         25:'p',
         26:'q',
         27:'r',
         28:'s',
         29:'t',
         30:'u',
         31:'v',
         32:'w',
         33:'x',
         34:'y',
         35:'z'}
    new_num_string=''
    current=num
    while current!=0:
        remainder=current%n
        if 36>remainder>9:
            remainder_string=num_rep[remainder]
        elif remainder>=36:
            remainder_string='('+str(remainder)+')'
        else:
            remainder_string=str(remainder)
        new_num_string=remainder_string+new_num_string
        current=current/n
    return new_num_string

Вот еще один из тех же ссылок

def baseconvert(n, base):
    """convert positive decimal integer n to equivalent in another base (2-36)"""

    digits = "0123456789abcdefghijklmnopqrstuvwxyz"

    try:
        n = int(n)
        base = int(base)
    except:
        return ""

    if n < 0 or base < 2 or base > 36:
        return ""

    s = ""
    while 1:
        r = n % base
        s = digits[r] + s
        n = n / base
        if n == 0:
            break

    return s

Посмотрите на рекомендуемые цепочки инструментов для DocBook.