Приложение (не язык разметки) для создания руководства пользователя
Кто-нибудь может порекомендовать программу для создания руководств пользователя? Не язык разметки (например, LaTeX или DocBook), а нечто более интерактивное, например Scribus. Поскольку я не единственный, кто будет обновлять руководство, программное обеспечение должно быть удобным для новичка, но все же имеет некоторые дополнительные функции (такие как ссылки в тексте из внешних источников / таблиц, обработка мастер-страниц / тем и т. Д.),
С уважением, Оскар
11 ответов
Техническое программное обеспечение для публикации - взгляды на FrameMaker и его альтернативы
Я разработал спецификации документов с LaTeX и Framemaker, и разработал рабочий процесс Framemaker для поддержки команды из 5 аналитиков, создающих спецификации документов для системы страхового страхования. Ожидается, что документ достигнет 2000 страниц или около того. Много лет назад (около 1992-1993 гг.) Я также недолгое время работал наборщиком.
Framemaker разработан для технической документации и делает это очень хорошо. Он также имеет функции, предназначенные для поддержки очень больших документов с несколькими авторами - люди используют эту систему для создания документов с более чем 100 000 страниц. Он также более доступен, чем LaTeX для пользователей, знакомых с программным обеспечением для обработки текстов.
Ключевые особенности Framemaker:
Документы, состоящие из нескольких файлов: вы можете собрать "Книгу" с несколькими подразделами в разных файлах. Документ также может храниться в системе контроля версий.
Текстовый формат MIF для импорта / экспорта: импортер несколько придирчив (создание рабочего LaTeX проще), но вы можете создавать такие элементы, как словари данных, и импортировать их в документ. Файл имеет текстовые привязки (см. Ниже), поэтому вы можете создавать перекрестные ссылки, которые будут стабильными при импорте. Я считаю, что это ключевая функция для спецификаций, поскольку она позволяет перекрестным ссылкам напрямую ссылаться на сгенерированные элементы.
Мощная система тегов, индексации и перекрестных ссылок: все основано на тегах в Framemaker, и теги легко применять быстро. Это означает, что перекрестные ссылки, индексирование, условный текст и массовое применение стилей легко и просто работает. Вы можете создавать индексы и оглавления на основе тегов, поэтому легко создать несколько специализированных индексов (таких как список имен полей данных на экранах или в словаре данных). Документ, который я описал выше, имел 4 отдельных индекса.
Стабильно: Framemaker предназначен для профессионалов, поэтому он не догадывается, как это слово. Это также намного более стабильно на больших документах. Любой, кто пытался написать документ размером более 50-100 страниц в Word, должен иметь достаточно четкое представление о том, что это означает.
Scriptable: FM имеет C API и существуют различные скриптовые плагины ( FrameScript и FMPython, вероятно, наиболее широко используемые), которые можно использовать для автоматизации заданий в FM. Framemaker 10 добавляет поддержку инструмента сценариев на основе Javascript под названием Extendscript, предположительно перенесенного через средство сценариев в InDesign.
Единый источник: из одного FM-документа вы можете довольно легко создавать PDF, справку Windows (CHM), HTML и печатать документы. Перекрестные ссылки также разрешают гиперссылки.
Глобальные элементы управления стилями. Вы можете легко настроить стили для документа и применить его ко всему документу. Это также облегчает запуск верхних и нижних колонтитулов с большой гибкостью, позволяя им отслеживать разделы, версии, главы и т. Д.
Альтернативы Framemaker
LaTeX / Lout: вы уже указали, что не хотите использовать язык разметки, но системы TeX и Lout используются для больших структурированных документов и делают это хорошо.
Ventura Publisher: Вероятно, единственная реальная альтернатива Framemaker, если вы хотите подобного рода пользовательский интерфейс, не платя физическими частями за привилегию. Он имеет сильную поддержку структурированных документов и формат обмена документами на основе XML. Теперь он принадлежит Corel, который все еще активно продвигает его.
На рынке есть несколько других технических издательских инструментов: Quicksilver (который раньше назывался Interleaf) и ArborText. Эти два мощных инструмента - Interleaf когда-то был лидером рынка в этой области - но довольно дорогой.
Adobe Indesign. Несмотря на то, что Adobe утверждает, что вы можете создавать большие документы с помощью InDesign, перекрестные ссылки и другие функции для работы с крупными документами, как правило, считаются недостатками в Framemaker afficionados. Однако для него существует система ввода текста, называемая InCopy, которая, по-видимому, обладает подобным функционалом и довольно большим набором сторонних плагинов, некоторые из которых поддерживают тегирование и другие подобные средства. InDesign также имеет API сценариев и интерпретатор JavaScript для выполнения сценариев.
Я не использовал Indesign, поэтому я не могу прокомментировать, насколько хорошо он работает на практике.
DocBook: на самом деле это просто стандартный формат для структурированных документов, но его окружает большая экосистема инструментов для написания и рендеринга документов. Если вы не хотите использовать LaTeX, вы, вероятно, не захотите использовать DocBook по тем же причинам. Как указывает Винко Врсалович (+1), эта ссылка ведет на сообщение Stackru от кого-то, кто на практике описывает использование DocBook. Я никогда по-настоящему не использовал DocBook, и я сделал так много правок в этом посте, что теперь он находится в режиме Wiki, поэтому кто-то, знакомый с DocBook, может захотеть уточнить это.
Программное обеспечение для обработки текстов: Word имеет серьезные недостатки в качестве технического средства публикации и не рекомендуется. OpenOffice имеет несколько лучшую структурированную функциональность документации, чем word, и может быть лучшим выбором, если политика или требование использовать.doc в качестве формата обмена документами исключают лучшую альтернативу. Wordperfect также значительно лучше для документации в целом, чем word, и все еще присутствует на нескольких вертикальных рынках, таких как юридические офисы.
Blaze and Flare от Madcap Software: это новые дети, живущие в том же пространстве, что и Framemaker. Компания была основана бывшими сотрудниками eHelp (создатели RoboHelp) и активно развивается, ежегодно выпуская несколько версий. Их предложения значительно расширились за последние два года в ущерб качеству отдельных продуктов. Похоже, что внимание было сосредоточено на выпуске новых продуктов, и, как следствие, в каждом из них есть много проблем с "подгонкой и отделкой". Авторы решили заново изобрести колесо разными способами, что привело к запутанным и часто неработающим реализациям. За исключением часто, вы столкнетесь с необработанными исключениями. Интеграция с системой контроля версий ненадежна. Например, перемещение или удаление группы файлов приведет к одной фиксации управления исходным кодом для каждого удаления файла. Большой PITA, когда у вас есть уведомления по электронной почте контроля источника. Привет 500 писем. Flare может импортировать файлы Word и Framemaker, но импорт далеко не безупречен. Ожидайте сохранить весь ваш контент, но планируйте полностью изменить стиль с нуля. Flare разделяет склонность Word делать слишком много за кулисами и предполагать, что выберет пользователь. HTML выглядит так, как выводит Word при экспорте HTML - множество пользовательских тегов и атрибутов, глубоко вложенные встроенные стили и т. Д. Текстовый редактор сводит с ума, например, его модель курсора отличается от любой другой программы, которую вы когда-либо использовали.
Framemaker vs. LaTeX
Эти две основные системы, которые я использовал для создания больших, презентабельных системных документов, и у меня были хорошие результаты с обеими.
Простота изучения: TeX может дать вам абсолютный контроль, но на самом деле добиться этого в сложном документе LaTeX, не разбивая другие элементы, нетривиально, особенно когда задействовано большое количество макропакетов. Базовый LaTeX не сложен в изучении, но создание модифицированных версий.sty файлов, которые все еще работают, требует некоторого труда, если вы не очень глубокий хакер TeX. Это можно сделать, но будьте готовы потратить довольно много времени на игры.
Framemaker может дать вам хороший контроль над внешним видом документа и не так сложен в освоении. Получить стиль дома и настроить макет (что вам, вероятно, придется сделать) будет проще с Framemaker.
Простота ввода текста: вы можете использовать такие инструменты, как Lyx, чтобы обеспечить подобный текстовому интерфейсу интерфейс LaTeX, и они хорошо работают, если вы хотите писать большие объемы текста. DTP-подобный пользовательский интерфейс Framemaker работает таким образом, который знаком людям, привыкшим к программному обеспечению для обработки текстов. С этой точки зрения мало практической разницы.
Структура документа шаблона: Framemaker позволяет определять структуру документа в виде тегов или схемы XML (если используется Structured Framemaker). LaTeX имеет набор консервированных структурных элементов, которые достаточно гибки, чтобы быть полезными. Добавление дополнительных структурных элементов (например, элемента словаря данных) может быть выполнено в виде макроса, но сделать их автонумерацию немного сложнее, и вам нужно будет потаскать за кулисами. Оба могут сделать это, но гораздо более технически сделать это в LaTeX во всех случаях, кроме тривиальных.
Кроме того, LaTeX не имеет возможности шаблонировать структуру документа так же, как это делает Structured Framemaker. Тем не менее, вы можете добиться этого типа эффекта с DocBook, а затем сгенерировать в LaTeX при желании.
Простота интеграции: создание генератора для нетривиально сложных MIF-файлов оказалось довольно сложным делом. Парсер MIF довольно привередлив в FM и не дает хорошей диагностики. LaTeX выдает гораздо лучшие сообщения об ошибках и немного менее суетлив.
Программное обеспечение для технических публикаций и программное обеспечение для макетов
Программное обеспечение для верстки началось с Pagemaker, и другими основными игроками в этом пространстве были его конкурент Quark Xpess, а теперь InDesign, с которым Adobe по сути пытается отказаться от него и заменить его, и Framemaker. Scribus, о котором вы упоминали ранее, живет в том же пространстве, что и эти продукты.
Если вы создаете руководство объемом менее (скажем) 50-100 страниц, один из пакетов, вероятно, будет работать адекватно. Они действительно предназначены для рекламы и задач макетной публикации, таких как журналы, поэтому их поддержка функций большого документа, таких как в Framemaker, довольно ограничена. Ключевой проблемой этих продуктов является масштабируемость - они плохо работают с большими документами.
Просто для справки я на самом деле набрал 200-страничную книгу (чья-то автобиография), используя Pagemaker. В то время как детальный кернинг и ведущий элемент управления немного помогают при подгонке под копию, выкладывание документа размером с книгу все еще остается очень ручным процессом. В данном случае книга представляла собой простой текст без существенных перекрестных ссылок или структуры, кроме глав. Создание сложного технического документа или руководства такого размера с Pagemaker было бы очень утомительно и, вероятно, практически невозможно было бы сделать правильно без каких-либо ошибок.
Техническая публикация против программного обеспечения для обработки текстов
Это скорее описание основных недостатков MS-Word для документов больших спецификаций. Тем не менее, он проиллюстрирует некоторые из основных функций, необходимых для документации в целом:
Индексирование и перекрестные ссылки: это настоящая рутинная работа в Word и довольно нестабильная. Функции тегов Framemaker и ярлыки LaTeX означают, что вы можете назначить тег или известный ярлык (в предсказуемом формате, если это необходимо). Текстовый формат для якорей тегов представлен в пользовательском интерфейсе и используется для связи. В Word якоря гораздо более непрозрачны и не так легко контролируются таким образом. В сочетании с неуклюжим пользовательским интерфейсом и нестабильностью продукта это делает их неуклюжими и зачастую нестабильными - вам часто приходится их исправлять вручную.
Шаблонные макеты: поддержка стилей в слове довольно проста, а нумерация обычно нестабильна. FrameMaker - это все, что нужно для извлечения из тегов и применения стилей на основе тегов. Глобальные изменения стиля просто работают в Framemaker так, как они не работают в Word.
Большие многофайловые документы: мне никогда не удавалось сделать это хорошо в Word, но это ключевая функция в Framemaker и LaTeX. Опять же, нестабильность Word означает, что вы, как правило, тратите много времени на уборку после него. По мере того, как размер документа увеличивается, доля времени, затрачиваемого на эту работу, увеличивается в квадрате - склонность к поломке пропорциональна n (размер документа) * время исправления пропорционально размеру n (время исправления)
Почему Word так нестабилен: Word много делает за кулисами, чтобы поддержать начинающих пользователей и вмешиваться в макеты. Он также не основывается на фреймах (текстовый поток концептуально отделен от макета документа), но разработчики пытаются реализовать различные фреймоподобные поведения в пользовательском интерфейсе. Когда ИИ угадает вас на сложном документе, он часто поступает неправильно. Framemaker "обращается с пользователем как с взрослым" и ничего не делает, поэтому все остается на месте, где бы вы его ни находили.
Другие текстовые процессоры, такие как Open Office и WordPerfect, не ведут себя так же, как Word, и это одна из причин того, что практически любой текстовый процессор, кроме Word, лучше справляется с технической документацией.
Предварительная проверка : в документации - это процесс проверки правильности сборки файлов для документа (файлов изображений и т. Д.) Перед началом печати. Профессиональные системы будут жаловаться на неправильные вещи, давая вам возможность исправить это. Word просто обретет счастливое лицо и попытается исправить ситуацию за кулисами.
Хорошим примером этого является текстовый файл со связанной графикой. Если вы скопируете файл и графику в другой каталог и обновите одну из графических объектов на месте, Word вполне может прочитать файл по старому пути (я видел, что он это делает), а не по новому, который вы только что обновили. Тем не менее, это поведение не является последовательным и типизирует повсеместное злоупотребление нестабильной эвристикой в этом продукте.
Предпечатная поддержка: система публикации распространяется на допечатную фазу рабочего процесса. Это означает, что он охватывает подготовку к печати. Программное обеспечение для обработки текстов, как правило, не имеет этой функциональности или имеет очень ограниченную форму.
Если не вдаваться в подробности, ключевое отличие состоит в том, что издательское программное обеспечение имеет тенденцию относиться к вам как к взрослому человеку, а не мешать вам, когда вы хотите масштабировать или автоматизировать вещи. Можно использовать программное обеспечение для обработки текстов для крупномасштабной документации, но оно имеет множество проектных решений, адаптированных для обычных пользователей, пишущих короткие документы, мало заботящихся о качестве. Эти адаптации происходят за счет пригодности к работе в крупномасштабной работе по подготовке документов. Основные проблемы, с которыми я сталкиваюсь в документах Word для спецификаций, - это плохая индексация и перекрестные ссылки, а также общие проблемы нестабильности, когда мне всегда приходится возвращаться и что-то исправлять. Тем не менее, политические соображения в большинстве сред (я подрядчик) означают, что один часто застревает с этим.
Некоторые общие комментарии о состоянии программного обеспечения технической документации
Framemaker был бы очевидным выбором, если бы Adobe не продолжала испускать сигналы о том, что они пытаются отказаться от него, и перенести свою пользовательскую базу в InDesign. Тем не менее, FM широко используется в аэрокосмической, программной и инженерной сферах, и руководство Adobe столкнулось бы с толпой линчевателей, если бы они действительно разработали продукт без надежного пути миграции. Судя по тому, что читают в Интернете, приобретение FM компанией Adobe было обусловлено Джоном Уорноком, но он был свергнут, и FM стал жертвой офисной политики. Конечным результатом является то, что он был переведен в режим обслуживания и довольно застойный.
Ventura Publisher также в некоторой степени отнесен к нишевому рынку, но, по крайней мере, у Corel нет двух конкурирующих продуктовых линеек, как у Adobe. Вероятно, это приемлемый заменитель FM и может быть более политически приемлемым для типов PHB, поскольку он продается как система "бизнес-публикаций".
Quicksilver и Arbortext кажутся жизнеспособными продуктами, но они очень дороги. Я тоже не пользовался, так что не могу реально судить об их достоинствах.
Языковые системы разметки бесплатны и очень мощны во многих отношениях. С Lout может быть немного легче работать, так как он не имеет такого уровня традиционного багажа, как LaTeX. DocBook также довольно широко используется и имеет довольно небольшую поддержку инструментов. Эти технологии значительно сокращают долю рынка Framemaker и делают его выгодным для себя - они, вероятно, значительно сократили размер прибыли Adobe за эти годы. Я бы не отмахнулся от этих технологий из рук в руки, но на практике их будет сложнее освоить.
Вы можете попробовать оценить InDesign и выбранный набор плагинов (сконцентрируйтесь на тех, которые используются для тегов и управления перекрестными ссылками / индексами). Наконец, некоторые из программ обработки текста (Wordperfect и OpenOffice) предоставляют вам разумный инструментарий для структурированной документации и работают для этого значительно лучше, чем MS-Word.
PostScript
Да, это каламбур. Я не затрагивал возможности Pre-Press ни одного из этих продуктов. Печать и допечатная подготовка сами по себе являются техническими областями, и объем дорогостоящих ошибок означает, что вам, вероятно, следует оставить это специалистам. Framemaker, InDesign, Ventura, QuickSilver, Arbortext и (предположительно) продукты MadCap поставляются с оборудованием для предпечатной подготовки. По большому счету, программное обеспечение для обработки текста - нет.
Предварительная печать с LaTeX имеет тенденцию включать постобработку вывода PS с помощью программного обеспечения, такого как psutils или рендеринга в PDF, и оттачивание рабочего процесса до печати оттуда. Как правило, большинство типографий могут работать с PDF, поэтому хороший инструмент для написания PDF, такой как Distiller, является лучшим интерфейсом для работы, подготовленной из инструментов, которые не предназначены для допечатной работы. Обратите внимание, что качество вывода из Distiller, как правило, лучше, чем у Ghostscript, таких как PDFCreator.
Обратите внимание, что цветовое пространство RGB монитора не имеет прямой привязки к цветовому пространству CYMK, используемому печатной машиной. На самом деле получение цветов - особенно цветных фотографий - чтобы правильно печататься на прессе, несколько чревато, если у вас нет подходящего набора. Для производства печати обратитесь к специалисту, если у вас нет оснований полагать, что вы знаете, что делаете. Для обычного пользователя я бы порекомендовал это через 15 лет после того, как я был вовлечен в индустрию, так как ошибки очень дороги, чтобы исправить, когда они посвятили себя печати.
Если вы действительно хотите заниматься цветной печатью на месте, вам, вероятно, потребуется откалибровать монитор. Для достижения наилучших результатов вы должны получить высококачественный монитор, подобный этому, от HP. Для калибровки монитора вам также может понадобиться датчик, подобный одному из описанных в этом обзоре, если монитор не поставляется с ним. Большинство профессиональных видеокарт, таких как Nvidia, AMD или Matrox, имеют средства для поддержки гамма-коррекции; многие потребительские тоже. Вам также нужно будет получить данные калибровки для печати, которую вы собираетесь использовать для печати, хотя, вероятно, это сможет сделать типография.
Как указывалось ранее, печатные носители сами по себе довольно технические, их легко ошибиться и их дорого исправить, если они уже напечатаны. Если вы не уверены на 100%, что вы правильно выполнили калибровку, получите цветопробу, например, Chromalin. Это делается из фактического разделения пленки (и, следовательно, довольно дорого), поэтому дает точное представление о фактическом цвете конечного печатного изделия. Выполнение этого для нескольких образцов страниц даст вам точную обратную связь о том, правильно ли настроена ваша калибровка.
Благодарности: Спасибо Aidan Ryan за расширение раздела о продуктах Madcap.
Я бы порекомендовал " Справка и руководство" от EC Software. Вы можете создать печатное руководство, PDF, файл справки Windows (CHM) и веб-справку HTML из одного исходного документа.
Я слышал хорошие вещи о FrameMaker. Я не использовал это сам, но рекомендовал мне именно для такого применения.
Adobe Framemaker действительно является классическим инструментом для написания руководств пользователя. Я использовал его для всех видов длинных документов, и он работает очень хорошо. Слишком плохо, что Adobe оставила это гнить в течение многих лет, прежде чем заметить, что пользователи не будут переключаться.
MSWord потребовалось до 2003 года, чтобы устранить ошибки, связанные с пулями / нумерацией, и я не знаю, удалось ли им наконец-то работать с основным документом.
LaTeX по-прежнему является разумной альтернативой. Формат легко обрабатывается, и вы можете сгенерировать его из вики.
Мы используем "Help & Manual" от EC Software, и он работает довольно хорошо. Наши авторы работают в США, поэтому мы делимся файлами с контентом через размещенный на сервере SVN для управления контролем версий. На каждой рабочей станции мы используем Tortoise SVN для синхронизации. Продукт чрезвычайно прост в использовании и продуктивен.
Если вам нужна совместная работа, то имеет смысл использовать языковой подход (LaTeX был бы моим предпочтением, хотя основанные на XML тоже хороши - Docbook здесь является флагманом) имеет смысл, особенно если вы отслеживаете файлы с помощью системы контроля версий.
Все, что усложняет такие вещи, как любое программное обеспечение в двоичном или проприетарном формате, здесь вам не поможет.
Извините, если это не тот ответ, который вы хотите.
ОЧЕНЬ хорошее объяснение того, что использует О'Рейли (на самом деле те, кто продает все эти книги...):
Это может показаться сложным, но в зависимости от количества страниц, которые вы собираетесь написать, вам, возможно, следует обратить на это внимание.
Я согласен с Олливье в том, что использование DocBook (или LaTEX) - это самый разумный подход, обеспечивающий простое преобразование, нормальное форматирование, хороший контроль версий.
К счастью, вы можете попробовать съесть свой торт и съесть его с помощью редактора DocBook.
Попробуйте те из этого списка и посмотрите, удовлетворяет ли какой-либо из ваших потребностей (я не использовал их).
Word (или ваш любимый текстовый процессор)
Я делаю все свои руководства пользователя (не путать с пользовательскими файлами HELP) в Word. Затем я могу определить, должны ли они быть в PDF, RTF, DOC или даже преобразованы в HTML. Чтобы решить проблему с многопользовательским обновлением, я храню файл в Source Control, который обрабатывает все эти забавные вещи.
Adobe InDesign CS5.5 гораздо лучше справляется с перекрестными ссылками и длинными документами, чем более ранние версии. Это очень мощный и относительно простой в освоении и использовании. Набор функций очень богат, и чем больше вы узнаете о нем, тем больше вы сможете с ним сделать. Он поддерживает очень мощные функции XML и может импортировать и экспортировать XML по мере необходимости. Он также может отображать стили в теги, а теги - в стили, позволяя вам автоматически создавать XML-файлы, если вы просто используете полный набор стилей символов и абзацев. Я использовал программу в течение многих лет и произвел множество проектов от книг до одноразовой рекламы. Это инструмент графического дизайна, но он поддерживает многие аспекты книжного и ручного производства. Я рекомендую его, если вас больше интересует графика, изображения или иллюстрации. InDesign поддерживает широкий спектр форматов импорта и экспорта.
В InDesign CS5.5 добавлена и улучшена поддержка как интерактивного контента, так и экспорта для форматов электронных журналов EPUB (электронная книга) и Adobe Digital Publishing Suite (DPS).
Framemaker - отличный инструмент для книг, инструкций и длинных технических документов. Его немного сложнее освоить, чем InDesign, но он имеет более богатый набор инструментов для создания переменных и запуска верхних и нижних колонтитулов, если у вас есть время и желание научиться их использовать. Он также имеет очень надежный набор функций XML, но я не использовал его лично.
К сожалению, Framemaker страдает от отсутствия поддержки графического дизайна. Цветовая система основана на очень клочковатых и точечных (PMS) цветах, которые трудно определить. Простые вещи, такие как добавление цвета обводки и заливки, в лучшем случае элементарны. Например, вы все еще не можете выбрать цвет обводки, который отличается от цвета заливки объекта. Программа предназначена для вывода на лазерные и струйные принтеры, а не на печатные машины.
Одна отличная особенность - это возможность применять главные страницы на основе стилей абзаца, появляющихся на странице. Нумерация абзацев / иллюстраций в Framemaker превосходит любую другую программу, которую я когда-либо использовал. Но это также трудно учиться и использовать.
Обе программы поддерживают вывод в форматах PDF и PostScript и могут генерировать гиперссылки и интерактивный контент.
Посмотрите блог Fastware Project для более детального обсуждения компромиссов использования DocBook и т. Д. Скотт Мейер испробовал множество возможностей и поделился своими мыслями.