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

Хотя он может не отвечать на все ваши запросы, возможно, стоит взглянуть на «ДокуВики».

Как и другие вики, он имеет простой синтаксис и имеет управление версиями для отслеживать версии, генерирует оглавление и функцию полнотекстового поиска, которая может пригодиться в качестве справочной системы.

Вы можете изучить список функций, чтобы узнать, соответствует ли он вашим потребностям.

Кроме того, похоже, есть хорошая коллекция доступных плагинов. Хотя я не использовал «ДокуВики» или ее плагины, похоже, есть плагины для экспорта в PDF а также.

LaTeX

Для нашего API мы используем Doxygen, и это здорово.

Pandoc - фантастический инструмент для преобразования между различными форматами разметки. Мы пишем документы в уценке и используем Pandoc для конвертации в другие форматы.

С сайта pandoc:

Если вам нужно конвертировать файлы из одного формата разметки в другой, pandoc - ваш швейцарский армейский нож. Pandoc может читать markdown и (подмножества) reStructuredText, textile, HTML и LaTeX, а также может писать простой текст, markdown, reStructuredText, HTML, LaTeX, ConTeXt, PDF, RTF, DocBook XML, OpenDocument XML, ODT, GNU Texinfo, Разметка MediaWiki, текстиль, man-страницы groff, режим организации Emacs, электронные книги EPUB, а также слайд-шоу S5 и Slidy HTML. Вывод PDF (через LaTeX) также поддерживается включенным скриптом-оболочкой markdown2pdf.

Pandoc получает дополнительные баллы за то, что он является открытым исходным кодом и написан на горячем языке Haskell;)

Я не могу сказать достаточно хороших слов о Asciidoc. Он имеет очень простой синтаксис разметки, может генерировать все, от pdf до roff, переносится в реализацию и очень легко вставляется в любую вики с небольшими изменениями.

Даже в состоянии разметки его очень и очень легко читать. Единственное, с чем мне приходится возиться при его использовании, - это таблицы, но это не так уж сложно.

Если вы храните файлы в текстовом формате в своем репозитории, отслеживать редакции довольно просто.

Для документации по коду я использую doxygen.

Мы используем справку и руководство для руководства и файла справки. Экспорт html отсутствует, но он предоставляет справку html, winhelp, pdf и некоторые другие форматы.

Мы пользуемся вики. Я рекомендую MoinMoin, потому что

• очень проста в настройке (даже на ноутбуке)
• очень просто выполнить резервное копирование (вы даже можете передать вики-страницу в систему контроля версий, чтобы синхронизировать ее, скажем, между ноутбуками для автономного использования).
• хороший синтаксис
• легко расширить
• Легко искать

Мы не используем что-то вроде Word, потому что:

• Документация гниет слишком быстро
• Поиск по всем документам - это боль
• Связь между информационными битами - это боль
• Нет разницы между версиями
• Двоичный формат, который чертовски убивает любую VCS
• Нет глубоких закладок
• Документы становятся слишком большими, а затем становятся неуклюжими: разбиваются (и больше не ведется поиск) или долго ждать загрузки.

Вы не упоминаете язык / фреймворк, который используете. Есть действительно хорошие инструменты для документации, но некоторые из них специфичны для того, что вы разрабатываете. Мы - магазин C #, поэтому мой ответ будет относиться к вам только в том случае, если вы используете .NET.

Мы используем Sandcastle, который не только бесплатный, но и с открытым исходным кодом. Хотя люди в первую очередь думают об этом как о приложении, которое генерирует документацию из XML-документации, вы можете предоставить свой собственный контент в MAML. Он может быть нацелен на развертывание как CHM, так и веб-сайтов, что соответствует нашим потребностям. Насколько я понимаю, есть некоторые дополнительные инструменты, которые могут предоставить такие вещи, как отметка избранного и рейтинги тем, но мы еще не начали их использовать.

Это дает нам как внутреннюю, так и внешнюю документацию. Поскольку мы также используем Team Foundation Server, мы используем встроенную вики-страницу для командного проекта в Sharepoint, но она больше ориентирована на совместную работу над проектами.

Изменить: исправлена ​​неработающая ссылка, а также хотелось упомянуть, что есть и другие инструменты, которые мы используем вместе с Sandcastle. Такие вещи, как построитель файлов справки Sandcastle и GhostDoc - распространенные инструменты. Первый предназначен для редактирования проектов Sandcastle и MAML, а второй - для улучшения качества комментариев в коде.

Попробуйте Sphinx. Вся документация по Python создается с использованием этого инструмента http://docs.python.org/

Для "мануалов" - Docbook. Это диалект SGML, разработанный для технической документации. http://www.docbook.org/. Он может не соответствовать вашему критерию "легкой разметки", но определенно дает хороший результат в LaTex (затем может быть преобразован в PDF) и хороший вывод HTML, если вы подготовите для него свою собственную таблицу стилей CSS. Текстовые файлы хранятся в системе контроля версий. Все программы также используют библиотеку, которая объединяет синтаксический анализ аргументов командной строки с выводом «--help» в различных форматах (обычный, справочная страница и docbook). Для справки по API, конечно, doxygen.

На моей нынешней работе мы производим одноразовое программное обеспечение, поэтому документация часто остается на второй план и делается в Word.

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

попробуйте Dikiwiki

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

Мы добились большого успеха с DocToHelp. Он отлично работает с документацией на основе Microsoft Word, а также с другими формами, и у него даже есть отличные функции интеграции для Visual Studio.

Самое приятное то, что как только у вас есть основная база документов, импортированная в DocToHelp, вы можете выбрать любой из множества форматов экспорта, будь то WinHelp, HTML-справка, Java-справка или красивая и удобная Net Help с возможностью поиска.

Для написания кода я использую Doxigen. Я предпочитаю версию для Linux, у меня были проблемы с некоторыми функциями в версии для Windows

Моя компания использует MediaWiki и TikiWiki для большей части документации. У нас также есть парень, который компилирует материалы в форматы MS Word и PDF для печати / отправки клиентам. Я бы рекомендовал вам избегать TikiWiki, как чумы. MediaWiki великолепна как потому, что она действительно проста в использовании, так и потому, что все знают, как ею пользоваться - это де-факто стандартная вики, и это заслуженно, ИМХО.

Некоторое время мы использовали DocBook, но было очень сложно расширить его более продвинутыми и необходимыми функциями (подсветка синтаксиса, разделение на несколько файлов, управление многоязычностью и т. Д.). Позже мы решили написать нашу собственную систему с нуля и выпустить ее с открытым исходным кодом: текст ссылки . Он использует простые текстовые файлы и Markdown в качестве языка синтаксиса, и теперь у нас есть все, что нам нужно. Недостатком является то, что в настоящее время, вероятно, нет парсера Markdown, который производит что-то еще, кроме вывода HTML. На данный момент этого достаточно, но мы думаем о реализации поддержки PDF в ближайшее время.