Какой хороший инструмент для написания руководства пользователя (файла справки), который интегрируется с контролем версий [закрыто]
https://stackoverflow.com/questions/152241
-
02-07-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianВопрос
Люди, пишущие руководство пользователя, не обязательно являются программистами, и им нужен визуальный редактор.Основной проблемой является внутренний формат инструмента разработки;это должен быть читаемый текст/html, чтобы можно было легко сравнивать версии отдельных страниц, проверенных в системе контроля версий.
Решение
Существуют и другие профессиональные продукты, которые позволяют писать файлы справки и поддерживают «идентификатор контекста», что делает возможной контекстно-зависимую помощь. Док в помощь и РобоПомощь это такие продукты.
Другие советы
Документ
(источник: docbook.org)
Microsoft HTML Help Workshop можно использовать для создания профессиональных файлов справки CHM хорошего качества.Все, что вам нужно, это несколько HTML-файлов.Инструмент «компилирует» все это и объединяет в один файл справки.Файлы HTML можно создавать с помощью Microsoft Word/Frontpage или даже Dreamweaver.Возможно, вы захотите рассмотреть возможность управления источниками этих HTML-файлов.
На моей старой работе они использовали инструмент от MadCap Software под названием вспышка.
Казалось, это сработало очень хорошо.
Хорошей комбинацией для рассмотрения является Subversion, DocBook и Publican.
- Контроль версий = Подрывная деятельность
- Авторский контент = Документ
- Публикация = Мытарь
- Необязательный WYSIWYG = Серна
На данный момент это одна из цепочек инструментов, используемых крупнейшим в мире поставщиком решений с открытым исходным кодом, и имя, лежащее в основе большей части мирового использования операционных систем на базе Linux на корпоративном рынке.Большая часть (и почти вся) официальной документации Red Hat создана таким образом.То же самое касается и Федоры.
Главный плюс здесь в том, что это свободно доступные инструменты, которые сильно пересекаются с рынком технических писателей.Все они смогут (но, возможно, не захотят) писать в XML, а знакомство с DocBook похоже на изучение HTML в 90-х.Subversion — это очень распространенный инструмент контроля версий, который, как и DocBook, относительно прост в реализации и использовании.Publican — отличный инструмент для публикации, который может использовать DocBook XML и публиковать его в формате PDF, HTML, HTML-single и т. д.Очевидно, что ваши авторы могут использовать WYSIWYG, например Serna, но я лично использую фрагменты в Geany (в Fedora) или TextMate (в OS X).
Главный «минус» — это восприятие формальности.Вашим авторам может потребоваться WYSIWYG (и они могут его иметь), и в зависимости от ваших потребностей в документации вы в конечном итоге можете использовать именно его.Как вы знаете, существует рынок «технических писателей», которые специализируются на исправлении стилей Microsoft Word (и разметки), поэтому аргументы в пользу отделения «авторства» от «публикации» основаны на проверенных, но различных вариантах использования для организаций, которые требуют, чтобы документация соответствовала тем же стандартам проектирования/программирования/исходного производства.
Некоторые из крайних советов, которые вы получите, исходят от людей и компаний, которые столкнулись с ценностью XML-документации, особенно от тех, кто работает в сфере DITA, где некоторые транснациональные корпорации имеют репутацию компаний, осуществляющих поглощения, на которые влияет формат и наличие знаний о продукте.Есть также аргументы в пользу того, что закрепление вашей документации в «прикрепленном» или закрытом формате не способствует соблюдению требований к будущему обслуживанию.Именно здесь варианты с открытым исходным кодом получают поддержку на корпоративном уровне.Плюс, очевидно, это бесплатно.
Вы можете использовать Subversion и MGTEK Help Producer.Help Producer создает файлы справки из документов Word.TortoiseSVN поставляется со сценариями для сравнения различных версий документов Word в самом Word (Word имеет инструмент сравнения версий).
Вашим пользователям понадобится инструмент визуального сравнения, похожий на тот, в котором они редактируют.Если они немного нетехнические, DocBook или Latex не будут работать (я пытался предоставить своим пользователям и то, и другое, и даже пробовал Epic Editor в качестве редактора DocBook, который очень дорог, но сработал не очень хорошо). после всего).Приверженность тому, что они знают (Word), избавит вас от многих головных болей.
Поначалу мне тоже очень не хотелось идти по этому пути, потому что мне хотелось более «технически совершенного» решения, но со временем я понял, что более важно иметь счастливых и продуктивных пользователей.Просто говорю, что я знаю, откуда вы, но попробуйте путь Word — на практике он работает намного лучше, чем все существующие «чистые» текстовые решения.Обычным пользователям не нравится редактирование на основе разметки.
Если вы используете Visual Studio, взгляните на SandCastle — http://www.codeplex.com/Sandcastle.
Также есть несколько инструментов, которые помогут вам создавать файлы замков из песка, попробуйте поискать «замок из песка» на codeplex.Один из них — SandCastle Help File Builder (http://www.codeplex.com/SHFB), но я никогда им не пользовался, поэтому не знаю, будут ли этим довольны нетехнические пользователи.
Mapcap Flare — лучший коммерческий инструмент.Написано бывшими разработчиками Robodoc
Я создал систему документации под названием Парень убит (Относительно связанные документы Markdown/Html/Javascript/файловые для переносимости), который легко попадет под контроль версий.С частью визуального редактора вам придется разобраться отдельно — я иногда использую HTML-кит который, по крайней мере, имеет функцию предварительного просмотра.
Видеть Как лучше всего хранить документацию по программному обеспечению?
Вот еще один инструмент для проверки: Ксилизе
Мы используем АПТ.Он хорошо интегрируется с CI (стандартным артефактом сборки) и более действенен, чем, например, текстовый документ.При необходимости также можно создавать PDF-файлы и другие форматы.
