Какие инструменты использует ваша команда для написания руководств пользователя?
Основные запросы:
- удобочитаемый / текстовый формат (для простого контроля версий)
- онлайн (для совместной работы)
- простое форматирование (уценка в порядке, HTML слишком много)
- строгое форматирование (поэтому авторы не изобретают новые типы заголовков, маркеров и т. д.)
- экспортируется в PDF, HTML
- Простое резервное копирование и развертывание (поэтому мы можем "развернуть" на сайте клиентов как версию только для чтения)
Мы думаем об использовании какого-то вики-движка, но для этого нужно будет использовать файлы для хранения или иметь другие средства "развертывания" для клиента и их легко установить /maintan. Кроме того, это должно быть бесплатно / дешево (слияние слишком дорого)
Какие-либо предложения?
Изменить: я не ищу инструменты для документирования кода, мы рассмотрели это с помощью Sandcastle.
17 ответов
Хотя это может не ответить на все ваши запросы, возможно, стоит взглянуть на DokuWiki.
Как и в других вики, он имеет простой синтаксис и имеет контроль версий для отслеживания изменений, генерирует оглавление и функцию полнотекстового поиска, которая может пригодиться для справочной системы.
Вы можете оценить список функций, чтобы увидеть, будет ли он соответствовать вашим потребностям.
Кроме того, кажется, есть также хорошая коллекция доступных плагинов. Хотя я не использовал DokuWiki или его плагины, похоже, что есть плагины для экспорта в PDF.
Pandoc - это фантастический инструмент для конвертации различных форматов разметки. Мы пишем документы в уценке и используем Pandoc для конвертации в другие форматы.
С сайта Пандока:
Если вам нужно конвертировать файлы из одного формата разметки в другой, pandoc - ваш швейцарский армейский нож. Pandoc может считывать уценки и (подмножества) reStructuredText, текстиля, HTML и LaTeX, а также может писать простой текст, уценку, reStructuredText, HTML, LaTeX, ConTeXt, PDF, RTF, DocBook XML, OpenDocument XML, ODT, GNU Texinfo, Разметка MediaWiki, текстиль, справочные страницы groff, режим Emacs org, электронные книги EPUB, а также слайд-шоу HTML S5 и Slidy. Вывод PDF (через LaTeX) также поддерживается с помощью включенного сценария оболочки markdown2pdf.
Пандок получает дополнительные очки за то, что он с открытым исходным кодом и написан в жарком, что Хаскелл;)
Я не могу сказать достаточно хороших слов об Asciidoc. Он имеет очень простой синтаксис разметки, может генерировать все, от pdf до roff, переносимо для реализации и очень легко вставляется в любую вики с небольшими изменениями.
Даже в состоянии разметки его очень легко читать. Единственное, с чем мне приходится возиться при использовании, это таблицы, но это не так уж сложно.
Если вы сохраняете файлы в текстовом формате в своем хранилище, отслеживание изменений довольно простое.
Для документирования кода я использую doxygen.
Мы используем справку и руководство для руководства и файл справки. Нет экспорта html, но он предоставляет справку html, winhelp, pdf и некоторые другие форматы.
Вы не упоминаете язык / рамки, которые вы используете. Существуют действительно хорошие инструменты для документирования, но некоторые из них относятся именно к тому, что вы разрабатываете. Мы - магазин на C#, поэтому мой ответ применим только к вам, если вы используете.NET.
Мы используем Sandcastle, который не только бесплатный, но и с открытым исходным кодом. В то время как люди в основном думают о нем как о приложении, которое генерирует документацию из XML Documentation, вы можете предоставить свой собственный контент на MAML. Он может быть ориентирован как на CHM, так и на веб-сайты, что отвечает нашим потребностям. На мой взгляд, есть некоторые дополнительные инструменты, которые могут обеспечить такие вещи, как отметка избранного и рейтинг темы, но мы еще не начали их использовать.
Это дает нам как внутреннюю, так и внешнюю документацию. Поскольку мы также используем Team Foundation Server, мы используем встроенную вики в Team Project в Sharepoint, но это больше ориентировано на совместную работу над проектом.
Изменить: Исправлена неработающая ссылка, а также хотел упомянуть, что есть другие инструменты в сочетании с Sandcastle, которые мы используем. Такие вещи, как Sandcastle Help File Builder и GhostDoc, являются распространенными инструментами. Первый - для редактирования проектов Sandcastle и MAML, а второй - для улучшения качества комментариев в коде.
Попробуйте Сфинкс. Вся документация Python производится с помощью этого инструмента http://docs.python.org/
Мы используем вики. Я рекомендую MoinMoin, потому что
- очень прост в настройке (даже на ноутбуке)
- очень простое резервное копирование (вы даже можете зафиксировать вики в системе контроля версий, чтобы синхронизировать ее, скажем, с ноутбуками для автономного использования).
- хороший синтаксис
- легко продлить
- Легко искать
Мы не используем что-то вроде Word, потому что:
- Документация гниет слишком быстро
- Поиск всех документов - это боль
- Связывание между информационными битами - это боль
- Нет различий между версиями
- Двоичный формат, который черт возьми из любого VCS
- Нет глубоких закладок
- Документы становятся слишком большими, а затем они становятся неуклюжими: разбиваются (и больше не ищут) или загружаются целую вечность.
На моей нынешней работе мы производим одноразовое программное обеспечение, поэтому документация часто отодвигается на второй план и выполняется в Word.
На моей последней работе, однако, команда документации, казалось, непрерывно разглагольствовала и восхищалась продуктом Mad Cap Software "Flare". Он позволяет вам писать в одном формате и публиковать на многих носителях, поэтому ваше руководство также может быть вашей онлайн-справкой или веб-сайтом и т. Д.
Для "мануалов", Docbook. Это диалект SGML, разработанный для технической документации. http://www.docbook.org/. Он может не соответствовать вашему критерию "простой разметки", но он определенно дает хороший вывод в LaTex (может быть затем преобразован в PDF) и хороший вывод HTML, если вы подготовите для него свою собственную таблицу стилей CSS. Текстовые файлы хранятся в системе контроля версий. Все программы также используют библиотеку, которая объединяет синтаксический анализ аргументов командной строки с выводом "--help" в различных форматах (обычный, справочная страница и документация). Для справки по API, конечно, doxygen.
Для этого кода я использую Doxigen. Я предпочитаю версию Linux, у меня были проблемы с некоторыми функциями в версии Windows
Некоторое время мы использовали DocBook, но было очень сложно расширить его с помощью более сложных и необходимых функций (подсветка синтаксиса, разбиение на несколько файлов, управление многоязычием и т. Д.). Позже мы решили написать нашу собственную систему с нуля и выпустить ее с открытым исходным кодом: текст ссылки. Он использует текстовые файлы и Markdown в качестве языка синтаксиса, и теперь у нас есть все, что нам нужно. Недостатком является то, что в настоящее время, вероятно, не существует анализатора Markdown, который производит что-то еще, кроме вывода HTML. Пока этого достаточно, но мы думаем о внедрении поддержки PDF довольно скоро.
Более того, мы поддерживаем MediaWiki как помощь сообщества.
Мы используем Word. Он включается в наш контроль версий, поэтому у нас есть история (есть папка документации, связанная с каждым проектом). Форматированием можно управлять с помощью шаблонов, которые мы сейчас настроили, поэтому вносить изменения легко в рамках стандартов макета. Файлы могут быть экспортированы в PDF. Вы можете опубликовать их как документы только для чтения, чтобы поделиться с пользователями.
У нас был большой успех с DocToHelp. Он отлично работает с документацией на основе Microsoft Word, а также с другими формами, и у него даже есть отличные функции интеграции для Visual Studio.
Самое приятное то, что, как только вы импортируете базовую базу документов в DocToHelp, вы можете выбрать любой из нескольких форматов экспорта, будь то WinHelp, HTML Help, Java Help или симпатичная и интересная сетевая справка с возможностью поиска.
Моя компания использует MediaWiki и TikiWiki для большей части документации. У нас также есть парень, который компилирует вещи в форматы MS Word и PDF для печати / отправки клиентам. Я бы порекомендовал вам избегать TikiWiki, как чума. MediaWiki великолепен, потому что он действительно прост в использовании и потому что все знают, как его использовать - это де-факто стандартная вики-версия, и заслуженно так, ИМХО.