Что такое хороший инструмент для написания руководства пользователя (файла справки), который интегрируется с контролем версий

Люди, пишущие руководство пользователя, не обязательно являются программистами, и им нужен визуальный редактор. Основной проблемой является внутренний формат инструмента разработки; он должен быть читаемым текстом /html, поэтому легко сравнивать версии отдельных страниц, проверенных в контроле версий.

Ответы

Ответ 1

Существуют и другие профессиональные продукты, которые позволяют писать файлы справки, и у них есть поддержка "идентификатора контекста", что делает возможным контекстно-зависимую помощь. Doc To Help и RoboHelp - эти типы продуктов.

Ответ 3

Мастер справки по Microsoft HTML можно использовать для создания файлов справки профессионального качества CHM. Все, что вам нужно, это куча файлов HTML. Инструмент "компилирует" все эти и связки в один файл справки. HTML файлы могут быть сгенерированы с использованием Microsoft Word/Frontpage или даже Dreamweaver. Возможно, вам захочется рассмотреть источник, контролирующий эти HTML файлы.

Ответ 4

Latex. Lyx предоставляет WYSIWYM для записи латексных файлов.

Ответ 5

На моей старой работе они использовали инструмент программного обеспечения madcap под названием факел.

Казалось, он работает очень хорошо.

Ответ 6

Хорошей комбинацией для рассмотрения является Subversion, DocBook и Publican.

На данный момент это одна из тех наборов инструментов, которые используются крупнейшим в мире поставщиком решений с открытым исходным кодом, а также имя, лежащее в основе использования операционных систем на базе Linux на корпоративном рынке. Большинство (и близко всех) официальной документации Red Hat создаются таким образом. То же самое касается Fedora.

Основным "про" здесь является то, что это свободно доступные инструменты, с сильным совпадением на рынке технических писателей. Все из них смогут (но не хотят) писать в XML, а сборка DocBook похожа на сбор HTML в 90-х. Subversion - очень распространенный инструмент управления версиями, который, как DocBook, относительно прост в реализации и использовании. Publican - отличный инструмент для публикации, который может использовать DocBook XML и публиковать его в формате PDF, HTML, HTML-single и т.д. Очевидно, что ваши авторы могут использовать WYSIWYG, например Serna, но я использую фрагменты в Geany (на Fedora) или TextMate (on OS X).

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

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

Ответ 7

Вы можете использовать Subversion и MGTEK Help Producer. Help Producer создает файлы справки из документов Word. TortoiseSVN поставляется со скриптами для сравнения различных версий документов Word, в самом Word (Word имеет инструмент сравнения версий).

Ваши пользователи захотят получить визуальный инструмент сравнения, похожий на тот, который они редактируют. Если они немного не технические, DocBook или Latex не будут работать (я пытался дать своим пользователям оба, и я даже попробовал Epic Editor в качестве редактора DocBook, который очень дорог, но в конце концов не получился очень хорошо). Придерживаясь того, что они знают (Word), вам не удастся много головных болей.

Я тоже очень не хотел идти по этому маршруту, потому что я хотел, чтобы решение было более "технически совершенным", но со временем я осознал, что иметь счастливых и продуктивных пользователей было более важным. Просто говорю, что я знаю, откуда вы, но попробуйте маршрут Word - на практике он работает намного лучше, чем все "чистые" текстовые решения, которые есть там. Обычным пользователям не нравится редактирование на основе разметки.

Ответ 8

Я создал систему документации под названием Mandown ( Markdown/Html/Javascript/файлы на основе относительно связанных документов для переносимости), которые легко поддаются контролю версий. Часть визуального редактора, которую вы должны были бы выяснить отдельно - я иногда использую HTML-Kit, который, по крайней мере, имеет функцию предварительного просмотра.

См. Каков наилучший способ хранения документации по программному обеспечению?

Вот еще один инструмент для проверки: Xilize

Ответ 9

Если вы используете Visual Studio, взгляните на SandCastle - http://www.codeplex.com/Sandcastle.

Там также несколько инструментов, которые помогут вам создавать файлы в песочнице, попробуйте выполнить поиск "sandcastle" на codeplex. Одним из них является SandCastle Help File Builder (http://www.codeplex.com/SHFB), но я никогда не использовал его, поэтому я не знаю, технические пользователи будут довольны этим.

Ответ 10

Mapcap Flare - лучший коммерческий инструмент. Написано бывшими разработчиками Robodoc

Ответ 11

Мы используем APT. Он хорошо интегрируется с CI (стандартным артефактом сборки) и является более живым, чем, например, текстовый документ. Кроме того, при необходимости можно создавать PDF файлы и другие форматы.