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

Ответ 1

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

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

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

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

Ответ 2

LaTeX

Ответ 3

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

Ответ 4

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

С сайта pandoc:

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

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

Ответ 5

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

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

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

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

Ответ 6

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

Ответ 7

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

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

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

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

Ответ 8

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

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

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

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

Ответ 9

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

Ответ 10

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

Ответ 11

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

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

Ответ 12

попробуйте Dikiwiki

Ответ 13

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

Ответ 14

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

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

Ответ 15

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

Ответ 16

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

Ответ 17

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

Кроме того, мы поддерживаем MediaWiki как помощь на уровне сообщества.