Приложение (не язык разметки) для создания руководства пользователя

Ответ 1

Техническое издательское программное обеспечение - Просмотры FrameMaker и его альтернативы

Я выполнил спецификации документов с помощью LaTeX и Framemaker и разработал рабочий процесс Framemaker для поддержки команды из 5 аналитиков, производящих спецификационный документ для системы страхового андеррайтинга. Ожидается, что документ достигнет 2000 страниц или около того. Много лет назад (примерно в 1992-1993 годах) я также коротко работал в качестве наборщика.

Framemaker разработан для технической документации и действительно ли он . Он также имеет функции, предназначенные для поддержки очень больших документов с несколькими авторами - люди используют эту систему для обработки документов с более чем 100 000 страниц. Он также более доступен, чем LaTeX, для пользователей, знакомых с программным обеспечением для обработки текстов.

Основные функции Framemaker:

• Документы, состоящие из нескольких файлы:. Вы можете объединить "Книга" с несколькими подразделами в разные файлы. Документ может также сохраняются в контроле источника.

• Текстовый формат MIF для импорт/экспорт: Импортер несколько тонкий (я обнаружил, что генерация работать LaTeX проще), но вы можете создавать такие элементы, как данные словарей и импортировать их в документ. Файл имеет текстовый якоря (см. ниже), чтобы вы могли создавать перекрестные ссылки, которые будет стабильным в разных странах. я считают, что это ключевая функция для спецификации, поскольку он позволяет перекрестные ссылки для непосредственного связывания с созданными элементами.

• Мощная система тегирования, индексирования и перекрестной ссылки Система: Все основан на тегах в Framemaker и легко применять теги быстро. Это означает, что перекрестные ссылки, индексирование, условный текст и применение стилей en-masse очень простое и просто работает. Вы можете создавать индексы и TOC на основе тегов, поэтому с несколькими специализированными индексами (например, список имен полей данных с экранов или словаря данных) легко сделать. Документ I описанный выше, имел 4 отдельных индексов.

• Стабильный: Framemaker предназначен для профессионалов, поэтому он не второй угадайте, как это слово делает. Он также намного более стабилен на больших документы. Любой, кто пытался написать документ более 50-100 страниц в Word должно быть довольно справедливое представление о том, что это подразумевает.

• Сценарий: У FM есть C API и там это различные скриптовые плагины (FrameScript и FMPython вероятно, наиболее широко используется) который может использоваться для автоматизации рабочих мест в FM. Framemaker 10 добавляет поддержку для скриптового инструмента на основе Javascript называемый Extendscript, предположительно переносится через сценарий в InDesign.

• Single-sourcing: От одного FM документ, вы можете создавать PDF, Справка по Windows (CHM), HTML и печать документов довольно легко. перекрестные ссылки также гиперссылки.

• Элементы управления глобального стиля:. Вы можете легко настроить стили для документа и применять его в целом документ. Это также облегчает верхние и нижние колонтитулы с большая гибкость в их разделы треков, версии, главы и т.д.

Альтернативы Framemaker

• LaTeX/Lout: Вы уже указали что вы не хотите разметки lanaguage, но TeX и Lout системы используются для больших структурированных документов и сделать это хорошо.

• Ventura Publisher: Вероятно, только реальная альтернатива Framemaker если вам нужен такой пользовательский интерфейс без оплаты телесных частей за привилегия. Он имеет сильную поддержку структурированных документы и документ на основе XML обменный формат. Теперь он принадлежит Corel, который по-прежнему, по-видимому, активно продвигает его.
  

  На рынке есть еще несколько технических издательских инструментов: Quicksilver (который раньше назывался Interleaf) и ArborText, Эти два являются мощными инструментами - Interleaf раньше был лидером на рынке в этой области - но довольно дорогостоящим.

• Adobe Indesign: Хотя Adobe заявить, что вы можете делать крупные документы с InDesign, перекрестная ссылка и другие функции большого документа как правило, не хватает Фрейммейкер. Там есть, однако для него система ввода текста называемый InCopy, который, по-видимому, имеет такой вид функциональности и вполне большое количество сторонний плагины, некоторые из которых поддержка тегов и другие подобные объекты. InDesign также имеет API сценариев и интерпретатор JavaScript для выполнения скрипты.

  Я не использовал Indesign, поэтому я не могу прокомментировать, как хорошо работает на практике.

• DocBook: Это действительно просто стандартный формат для структурированных документов, но имеет большую экосистему инструментов, окружающих его для написания и рендеринг документов. если ты не хотите использовать LaTeX, вы будете вероятно, не хотят использовать DocBook для аналогичные причины. Как Винько Врсалович указывает (+1), Эта ссылка идет в StackOverflow сообщение от кого-то, описывающего использование DocBook на практике. Я никогда не использовал DocBook, и я сделал так много изменений для этого сообщения, что теперь он находится в режиме Wiki, поэтому кто-то, кто знаком с DocBook, может хочу рассказать об этом.

• Программное обеспечение для обработки текстов: Word имеет серьезные недостатки как технический инструмент публикации и не рекомендуемые. OpenOffice имеет несколько лучше структурированный функциональности документации, чем слова и может быть лучшим выбором, если политика или требование использовать .doc в качестве формата обмена документами исключить лучшую альтернативу. Wordperfect также значительно лучше для документация в большом, чем слово и все еще присутствует на нескольких вертикальных рынках таких как юридические офисы.

• Программное обеспечение Madcap Blaze и Flare: Эти новые дети на блоке и живут примерно в том же пространстве, что и Framemaker. Компания была основана бывшим Сотрудники eHelp (создатели RoboHelp) и активно развивается, с несколькими выпусками ежегодно. Их за последние два года значительно расширились предложения, в ущерб качеству отдельных продуктов. Кажется, что основное внимание уделяется разработке новых продуктов и по последнему слову, существует множество проблем с "пригодностью и отделкой" в каждый. Авторы решили изобрести колесо разными способами, что приводит к запутыванию и часто нарушению реализации. Сохраняйте часто, вы столкнетесь с необработанными исключениями. Интеграция управления версиями является шелушащимся. Например, перемещение или удаление группы файлов приведет к один фиксатор источника для каждого удаления файла. Большой PITA, когда у вас есть уведомления об элементах управления электронной почтой. Привет, 500 писем. Flare может импортировать файлы Word и Framemaker, но импорт далека от бесшовности. Ожидайте сохранить весь свой контент. но планируют полностью переделать с нуля. Flare разделяет многие тенденции Word, чтобы сделать слишком много сцены и предположить, что пользователь будет выбирать. HTML выглядит как то, что Word выводит при экспорте HTML - множество пользовательских тегов и атрибуты, глубоко вложенные встроенные стили и т.д. Текст редактор сходит с ума, например, его модель курсора отличается чем любое другое программное обеспечение, которое вы когда-либо использовали.

Framemaker vs. LaTeX

Эти две основные системы, которые я использовал для создания больших презентабельных системных документов, и у меня были хорошие результаты с обоими.

• Простота обучения: TeX может дать вам абсолютный контроль, но на самом деле достижение этого на сложном LaTeX документ без нарушения других предметы не тривиальны, особенно где большое количество макросов пакеты. Basic LaTeX нетрудно учиться, но измененные версии .sty файлов, которые все еще работа требует немного возиться если вы не очень глубокий TeX Хакер. Это можно сделать, но готовы потратить немало тайм-аут.

  Framemaker может дать вам хорошую степень контроля над внешним видом документа и не так уж трудно учиться. Получение стиля дома и настройка макета (что вам, вероятно, придется делать) будет проще с Framemaker.

• Простота ввода текста: Вы можете использовать такие инструменты, как Lyx, чтобы обеспечить wordprocessor-like передняя часть LaTeX, и они хорошо работают, если вы хотите написать большие тексты. Framemaker DTP-подобный пользовательский интерфейс работает знакомым людям которые используются для словесного программного обеспечения. С этой точки зрения мало практических разница.

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

  Кроме того, LaTeX не имеет средство для структуры документа таким образом, чтобы Структурированный Framemaker. Однако вы можете достичь этого типа эффекта с DocBook, а затем при необходимости сгенерируйте LaTeX.

• Простота интеграции: Я нашел создание генератора для нетривиального сложных MIF файлов неудобный. Парсер MIF вполне pernickety в FM и на самом деле не дать хорошую диагностику. Латекс дает гораздо лучшие сообщения об ошибках и довольно немного суетливый.

Техническое издательское программное обеспечение и программное обеспечение макета

Программное обеспечение макета страницы начиналось с Pagemaker, а другие основные игроки в этом пространстве были его конкурентом Quark Xpess и теперь InDesign, с помощью которого Adobe по существу пытается осудить и заменить ее и Framemaker. Scribus, о котором вы говорили ранее, живет в том же пространстве, что и эти продукты.

Если вы создаете руководство с размером менее 50-100 страниц, один из пакетов, вероятно, выполнит соответствующую работу. Они действительно предназначены для рекламных и макетных задач публикации, таких как журналы, поэтому их поддержка функций большого документа, найденных в Framemaker, довольно ограничена. Ключевой проблемой этих продуктов является масштабируемость - они не работают хорошо на больших документах.

Только для справки я действительно набираю 200-страничную книгу (кто-то автобиографию) с помощью Pagemaker. В то время как мелкозернистый кернинг и ведущий элемент управления немного помогают в копировании, все же очень ручной процесс выкладывания документа с размером книги. В этом случае книга была просто прямым текстом без существенных перекрестных ссылок или структуры, отличной от глав. Выполнение сложного технического документа или руководства такого размера с помощью Pagemaker было бы очень неудобно и, вероятно, почти невозможно было бы получить право без каких-либо ошибок.

Техническая публикация против программного обеспечения для обработки текстов

Это скорее описание ключевых недостатков MS-Word для больших спецификационных документов. Тем не менее, это иллюстрирует некоторые основные функции, необходимые для документации в целом:

• Индексирование и перекрестные ссылки: Это настоящая работа в Word, и довольно неустойчивый. Framemaker-х функции тегов и ярлыки LaTeX означает, что вы можете назначить тег или (в предсказуемом формате если необходимо). Текстовый формат для анкеров тегов пользовательский интерфейс, и используется для связь. В Word, якоря гораздо более непрозрачны, а не легко контролируемым таким образом. В сочетании с неуклюжим пользователем интерфейс и нестабильность продукта, это делает сохранение эти неудобные, часто неустойчивые - вам часто приходится вручную их исправлять вверх.

• Templated Layouts: Поддержка стиля в слове довольно проста и нумерация имеет тенденцию быть несколько неустойчиво. FrameMaker - это все о вождение от тегов и применение стилей на основе тегов. Глобальный изменения стиля просто работают в Framemaker таким образом, чтобы они не в Word.

• Большие многофайловые документы:Я никогда не мог сделать эту работу хорошо в Word, но это ключ в Framemaker и LaTeX. Опять же, нестабильность Word означает, что вы, как правило, тратите много времени убирать после него. Поскольку документ растет, доля времени, затраченного на это работа растет квадратично - склонность к потере пропорциональности до n (размер документа) * время до фиксировать пропорционально размеру n (время для исправления)

• Почему Word настолько нестабилен: Word делает много за кулисами поддерживать начинающих пользователей и вмешиваться в макетах. Это также не очень основанный на кадрах (текстовый поток концептуально отдельно от макета документа), но разработчики пытаются реализовать различные кадровые поведения в пользовательском интерфейсе. когда A.I. вторгается на вас сложный документ часто делает неправильная вещь. Framemaker 'рассматривает пользователя как взрослого ", и ни один из это так, что вещи остаются там, где вы их.

  Другие текстовые процессоры, такие как Open Office и WordPerfect не неправильно вести себя так же, как Слово, которое является одной из причин что почти любое слово процессор, отличный от Word, сделает лучшая работа технических документов.

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

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

• Поддержка пре-печати: Издательская система распространяется на предварительную печать фазы рабочего процесса. Это означает он охватывает подготовку к печати. Программное обеспечение для обработки текстов имеет тенденцию не иметь эту функциональность или это в очень ограниченной форме.

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

Некоторые общие замечания о состоянии программного обеспечения технической документации

Framemaker был бы очевидным выбором, если бы Adobe не переставала выдавать сигналы о том, что они пытаются обесценить ее и переместить свою базу пользователей в InDesign. Тем не менее, FM широко используется в аэрокосмических, программных и инженерных кругах, и руководство Adobe столкнутся с lynch mob, если они на самом деле EOL'd продукта без надежный путь миграции. Из того, что читается в Интернете, приобретение Adobe FM было вызвано Джоном Уорноком, но он был свергнут, а FM стал жертвой офисной политики. Конечным результатом является то, что он перемещен в режим обслуживания и довольно застой.

Издатель Ventura также в какой-то степени отнесен к нишевому рынку, но, по крайней мере, у 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. Это делается из фактического разделения пленки (и, следовательно, довольно дорого), поэтому он дает точное представление о фактическом цвете окончательной печатной статьи. Выполнение этого для нескольких примеров страниц даст вам точную информацию о правильности настройки вашей калибровки.

Благодарности: Благодаря Айдан Райан для расширения раздела о продуктах Madcap.

Ответ 2

Я бы порекомендовал " Справка и руководство из программного обеспечения EC. Вы можете создать печатное руководство, PDF файл справки Windows (CHM) и HTML-справочную систему HTML из одного исходного документа.

Ответ 3

Я слышал хорошие вещи о FrameMaker. Я не использовал его сам, но рекомендовал ли я его для такого приложения.

Ответ 4

Adobe Framemaker действительно является классическим инструментом для написания руководств пользователя. Я использовал его для всех видов длинных документов, и он работает очень хорошо. Жаль, что Adobe оставила его гнить в течение многих лет, прежде чем замечать, что пользователи не переключатся.

MSWord занял до 2003 года, чтобы получить ошибки пули/нумерации, и я не знаю, получили ли они наконец рабочий документ.

LaTeX по-прежнему является разумной альтернативой. Формат легко обрабатывается, и вы можете сгенерировать его из вики.

Ответ 5

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

Все, что усложняет такие вещи, как любое программное обеспечение с двоичным или проприетарным форматом, не поможет вам здесь.

Извините, если это не тот ответ, который вы хотите.

Ответ 6

Я согласен с Ollivier в том, что использование DocBook (или LaTEX) - это самый надежный подход для легкого преобразования, нормального форматирования, хорошего управления версиями.

К счастью, вы можете попробовать получить торт и съесть его с помощью редактора DocBook.

Попробуйте использовать этот список и посмотрите, удовлетворяет ли ваши потребности (я не использовал их).

Ответ 7

Мы используем "Справка и руководство" из EC Software, и это работает очень хорошо. Наши авторы распространяются через США, поэтому мы передаем наши файлы контента через размещенный сервер SVN для управления контролем версий. На каждой рабочей станции мы используем Tortoise SVN для синхронизации. Продукт чрезвычайно прост в использовании и продуктивности.

Ответ 8

ОЧЕНЬ приятное объяснение того, что O'Reilly (на самом деле те, кто продает все эти книги...) использует:

O'Reilly Toolchain

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

Ответ 9

Слово (или ваш любимый текстовый процессор)

Я делаю все мои руководства пользователя (не путать с пользовательскими файлами HELP) в Word. Затем я могу определить, должны ли они быть в формате PDF, RTF, DOC или даже конвертированы в HTML. Чтобы решить проблему многопользовательского обновления, я храню файл в Source Control, который обрабатывает все эти забавные вещи.

Ответ 10

Смотрите блог Fastware Project для углубленного обсуждения компромиссов с использованием DocBook и т.д. Скотт Мейер опробовал множество возможностей и делится тем, что он думает.

Ответ 11

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 и могут создавать гиперссылки и интерактивный контент.