КомпанияУслугиОбучениеСервисы

Рефераты за 2004–2007 гг.

Версия для печати

Рефераты за 2004–2007 гг.

Единый источник в малых проектах

Е. Потапова

10.04.2007

Single sourcing and its applicability to small projects//TechScribe http://www.techscribe.co.uk 2005

http://www.techscribe.co.uk/techw/single_source.htm

Известно, что технология единого источника успешно применяется при разработке значительных объемов технической документации. Целесообразно ли это в небольших проектах? По мнению авторов, единый источник оправдан, во всяком случае, при наличии в проекте нескольких документов, содержащих «пересекающуюся» информацию либо подлежащих переводу и локализации. Правда, отказ от традиционного подхода ведет к потере некоторых преимуществ. Так, при создании файлов контекстной справки утрачивается возможность использования всевозможных полезных приемов форматирования, в частности, т.н. «хотспотов», рисунков с гипертекстовыми ссылками на выделенных областях. К тому же можно назвать ряд «ложных» преимуществ технологии единого источника. Например, считается, что она снижает объем редактирования. Но редактировать единый источник и конечные документы — это разные задачи, первое не заменяет второе.

Плавание на тонущем корабле (Дневник техписа)

Е. Потапова

21.12.2006

Hewitt J. Document Hack (A Technical Writer’s Journal): The Sinking Ship is in Beta//PoeWar.com Writer’s Resource Center http://www.poewar.com 13/7/2005

http://www.poewar.com/archives/2005/07/13/sinking/

В идеальных случаях технические писатели работают над документацией с момента разработки продукта. Возможно те из них, кто постоянно работает в одной компании, действительно встречались с такими ситуациями. Я как писатель-фрилансер с этим не встречался ни разу. Обычно документацию начинают писать программисты или инженеры. Они делают это не очень умело; к тому же написание документации не является для них первоочередной задачей. Кроме того, они не знакомы ни с одной системой разработки документации и пользуются для ее создания текстовым процессором Microsoft Word. Далее, к моменту написания хоть какой-то документации к программному продукту выходит вторая версия этого продукта. Во многих случаях разработкой следующей версии занималась другая группа разработчиков, и они-то пишут следующую версию технической документации. Когда до выпуска третьей версии (и документации к ней) остается несколько недель, обычно приглашают внешнего технического писателя. Так как уже нет времени писать полноценную документацию «с нуля» моя задача взять два предыдущих документа и сделать из них третий, к третьей версии продукта, который при этом все еще дорабатывается. От меня требуются просто чудеса, что же я могу сделать на самом деле? Моя главная задача — это все-таки разработать документ в срок. Только во вторую очередь я могу думать о качестве документа, хотя и делаю в этом направлении все от меня зависящее. Интересно, что те технические писатели, которые работают постоянно в одной компании, периодически пытаются как-то менять эту ситуацию к лучшему. Но они редко достигают успеха на этом поприще. Документация все еще не является важной областью для компаний разработчиков, и эта ситуация не скоро изменится.

Использование стандартов Веб для создания файлов справки в формате HTML

Е. Потапова

10.11.2006

James-Tanny С. Using Web Standards to Create HTML Files// WritersUA Training and information for User Assistance Professionals http://www.winwriters.com 2004

http://www.writersua.com/using_web_standards.htm

Стандартизация играет особую роль для технического писателя, облегчая ему работу в команде, редактирование материалов и многие другие задачи. Справка в формате HTML, сделанная на основе стандартов Веб, будет поддерживаться всеми браузерами, даже созданными после публикации документа. Такой файл справки удобнее обновлять. Его можно применять в программах, разработанных как для традиционных операционных систем, так и для карманных компьютеров, мобильных телефонов или устройств для глухих. Основные используемые в настоящее время стандарты — это разновидности стандарта XHTML. Также удобно применять стандарты стилевых таблиц (CSS, Cascading Style Sheets), которые позволяют отделить содержимое документа от его оформления. Разработка файла справки с использованием стандартов Веб не гарантирует, что он будет выглядеть одинаково во всех браузерах. Внешний вид может частично меняться, но содержимое файла всегда будет отображаться корректно.

Спецификация AECMA S1000D — международная спецификация для технических публикаций

Е. Потапова

20.09.2006

AECMA S1000D: The international technical publication specification//Official home page of the Technical Publications Specification Maintenance Group (TPSMG) http://www.s1000d.org 2005

http://www.s1000d.org

Международные требования к электронной технической документации в оборонных отраслях разрабатываются Европейской авиационно-космической ассоциацией (AECMA) и формулируются в регулярно обновляемой спецификации AECMA S1000D. Эта спецификация является методической основой для подготовки электронной эксплуатационной документации. Она становится базовым международным стандартом на подготовку любой технической документации, и не только технической. Спецификация соответствует требованиям основных стандартов W3C и ISO. Публикация в соответствии с AECMA S1000D базируется на информационных блоках, именуемых модулями данных (Data Modules, DM), которые сводятся в общую базу данных публикации (Common Source Data Base, CSDB). Технически такая CSDB может быть реализована разными способами. В CSDB хранятся DM всех описываемых объектов (их версий, модификаций и т. п.). При подготовке технической документации на определенное изделие из общей базы выбираются необходимые DM и из них составляется готовое руководство в формате SGML (ISO 8879). Этот формат позволяет описать структуру электронного документа при помощи DTD (Document Type Definition).

Управление проектом по созданию информационной системы поддержки пользователя

Е. Потапова

11.08.2006

Ferris T. Software User Assistance Project Management//Klariti.com: Klariti Writing Services Ireland ttp://www.klariti.com 2005

http://www.klariti.com/...shtml

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

Введение в информационный дизайн

Е. Потапова

14.07.2006

Hart G.S. An Introduction to Information Design/Intercom Online: The magazine of the Society for Technical Communication http://www.stc.org/intercom/ February 2006

http://www.stc.org/intercom/PDFs/2006/20062_30-31.pdf

На данный момент в работе технического писателя есть серьезная проблема — отсутствие теоретической базы. Более того, считается, что теория ему и не нужна, он работает в области практических действий. Под информационным дизайном разные специалисты понимают разное, но можно выделить ряд общих важнейших компонент: понимание того, как читатель воспринимает информацию; эмпирические правила, определяющее эффективное размещение текста и изображений; теоретическое понимание, как и почему работают эти правила. Важно, конечно, знать и понимать ту аудиторию, для которой пишется документация, поэтому как теоретический базис можно привлечь когнитивную психологию, юзабилити, социологию. Информационный дизайн — это работа для «адвоката пользователя». Другая важная задача: мы обитаем в мире пиктограмм и пользовательских интерфейсов, поэтому нельзя забывать о визуальной составляющей нашей работы. Вспомним, что графические изображения, это не просто техническая часть нашей повседневной работы. Они имеют свою семантику, свое значение в восприятии пользователя. К статье прилагается список литературы.

Как писать краткое руководство

Е. Потапова

20.06.2006

Fitch K. Writing Procedures/Intercom Online: The magazine of the Society for Technical Communication http://www.stc.org/intercom/ November 2004

http://www.stc.org/intercom/PDFs/2004/2004012_12-13.pdf

Оборудование и программное обеспечение становятся все сложнее, а у пользователя все меньше времени читать документацию. Выходоим из положения может стать разработка краткого руководства. Основные свойства краткого руководства — адекватность, лаконичность и доступность. Адекватность означает, что пользователь может найти в нем информацию о решении конкретных задач. Под лаконичностью подразумевается отсутствие лишних дополнительных пояснений, в руководство должна быть включена сжато изложенная самая необходимая информация. Доступность определяет формы, в которых изложена информация. Для повышения доступности должны использоваться цвета, разделители, заголовки, обозначающие действия, иллюстрации и схемы, а также таблицы, списки и т.д. Также руководство не всегда должно быть книгой или файлом контекстной справки. В случае с оборудованием это может быть ламинированная наклейка на само оборудование. Над форматом печатного руководства тоже нужно подумать: возможно, пользователю удобнее будет карманный формат или наклеенный над рабочим столом постер. Таким образом, пользователю должна быть предоставлена краткая и наглядная памятка об основных действиях с оборудованием или ПО. При написании руководства, как и при полном документировании, необходимо поводить анализ аудитории.

Карьера в области технических коммуникаций

Е. Потапова

01.06.2005

Interested in Technical communication?//The Society for Technical Communication home page http://www.stc.org 2004

http://www.stc.org/interestedTC.asp

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

Из истории стандартов

Е. Потапова

28.04.2006

Gross D. Mark It Well //American National Standards institute http://www.ansi.org/2003

http://www.ansi.org/news_publications/media_tips/mark_well.aspx?menuid=7

В феврале 1947 года инженеры, ученые и технические специалисты послевоенной Европы основали Международную организацию по стандартизации (International Organization for Standardization, ISO). Первый стандарт ISO был выпущен в 1951 году. В 2001 году ISO выпустила 831 стандарт, что вместе со всеми предыдущими составило 13000 за 50 лет существования. Эти стандарты охватывают на сегодня более 200 технических специализаций. Среди стандартов, впервые представленных в 2001 году, был, например 12616 «Управление терминологией для процесса перевода». История стандартов начинается с железной дороги, точнее, с установления в Великобритании в середине XIX века стандартной ширины колеи. Железная дорога и необходимость в точном расписании поездов вызвали еще один шаг в стандартизации — принятие единого Лондонского времени во всей Великобритании. А вот Акт о Стандартном времени (Standard Time Act) в США появился только в 1918 году. Попытки стандартизации европейских языков вошли в историю под названием Эсперанто (Esperanto) — универсального международного языка. Еще одна (удачная, в отличие от Эсперанто) попытка стандартизации — это разработка во Французской академии метрической системы измерений.

Обзор программы LinKit! 4.0

Е. Потапова

21.04.2006

Ellison M. Review of LinKit! 4.0// WritersUA Training and information for User Assistance Professionals http://www.winwriters.com 2005

http://www.winwriters.com/articles/linkit/index.html

Компания Affixion (Дания) выпустила новую версию (4.0) программного средства LinKit!, предназначенного как для разработки справочных систем, так и для привязки программных объектов к разделам справочной системы. Программное средcтво LinKit! предназначено в основном для компаний, в которых используется стандартное программное обеспечение со стандартной справочной системой и которые хотят дополнить эту справочную систему собственными внутренними инструкциями и справками. Так, в компании, cотрудники которой много работают с программой создания презентаций Microsoft PowerPoint, можно встроить дополнительную справку прямо в эту программу. Как правило, разрабатывается обычная справочная система, состоящая из одного или нескольких файлов в формате CHM, а затем с помощью модуля LinKit! Manager осуществляется привязка топиков справочной системы к окнам и формам программного продукта. Ссылки сохраняются в формате XML в специальном файле проекта. Когда требуется сдавать программу заказчику, компилируется база данных со ссылками. Инструментарий LinKit! 4.0 очень удобен при локализации ПО, особенно при необходимости создания мультиязыковой справочной системы.

Дизайн справочных систем в среде Веб

Е. Потапова

14.04.2005

Corbin M. Design Checklists for Online Help//WritersUA Training and information for User Assistance Professionals http://www.winwriters.com 2004

http://www.winwriters.com/articles/checklist/index.html

Многие пользователи не обращаются к справочной системе, так как считают, что время, потраченное на поиск информации, не окупает пользы от ее получения. Чтобы система была более удобна в применении, обратите внимание на следующие составляющие дизайна: контент, формат и представление информации, навигация, доступ к информации. Что касается контента, он должен быть хорошо структурирован и описывать решение конкретных задач. Разделите информацию на несколько различных типов (совет, справка и т.д.), и в каждом топике справочной системы применяйте только один тип информации. Основа дизайна — минимализм оформления и краткость содержимого. При разработке оформления и представления материала не увлекайтесь большим количеством окон и экранов. Вместо параграфов используйте списки с гиперссылками, которые удобно быстро просматривать. Используйте простые шрифты без засечек (sans-serif fonts) и ограничьте количество используемых шрифтов. При создании системы навигации старайтесь избегать форм, требующих применения полосы прокрутки. При использовании гиперссылок не делайте более пяти последовательных ссылок. Желательно минимализировать количество уровней оглавления. Одна из важнейших частей справочной системы — указатель (index). Разработайте подробный указатель с большим количеством синонимов из словарного запаса предполагаемого пользователя. Досуп к справке желательно делать из всех окон и меню информационной системы. Что касается разработки справочной системы в целом, система должна быть динамичной, простой в применении, ориентированной на контекст и решение конкретных задач пользователя. Данные советы базируются на целом ряде современных исследований и учебников (список источников прилагается).

Разработка корпоративного руководства по стилю — человеческий фактор

Е. Потапова

29.03.2006

Johnson S. Social Rules for Creating a Style Guide//Techwhir-l: The Internet forum for technical communicators www.techwr-l.com 2006

http://www.techwhirl.com/..../socialrulesforstyleguide.html

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

Обзор XML-редактора Cladonia Exchanger 3.2

Е. Потапова

26.02.2006

Self T. Review of Cladonia Exchanger XML Editor ver 3.2// WritersUA Training and information for User Assistance Professionals http://www.winwriters.com 2006

http://www.winwriters.com/articles/exchanger/index.html

Технология XML в настоящее время широко применяется при разработке технической документации, поэтому автор статьи рассматривает программный продукт Cladonia Exchanger 3.2 только с точки зрения этой задачи. Данный XML-редактор удобен в использовании и надежен, однако, он не предназначен непосредственно для написания текстов. В нем гораздо удобнее обрабатывать уже написанные тексты, устанавливать связи между документами и т.п. Одна из наиболее важных функций редактора — работа с языком запросов XPath. Другие полезные функции: закладки, выделение тегов и уровней вложенности, форматирование кода. Редактор Cladonia Exchanger 3.2 хорошо приспособлен для работы с документами в форматах DocBook/XML и DITA. В нем имеется возможность конвертации XML-документов в форматы HTML и PDF, правда, начинающие пользователи при обращении к ней могут испытывать сложности.

Редактирование документов для публикации в режиме онлайн

Е. Потапова

17.02.2006

Weber J. H. Editing online materials //Technical Editors Eyrie http://www.jeanweber.com/index.htm 1998

http://www.jeanweber.com/howto/edonline.htm

Документы для публикации в режиме онлайн (online documents) могут быть самыми разными: начиная с файлов контекстной справки и заканчивая публикациями на корпоративном портале или статьями в мультимедийных энциклопедиях. Однако при редактировании всех этих различных материалов требуются общие навыки технического редактирования, знание основ работы с гипертекстовыми документами, знание средств работы с документами, предназначенными для размещения в среде интранет или в Интернете. Статья представляет собой список позиций, по которым нужно проверять документы в процессе редактирования. При редактировании гипертекстовых ссылок нужно обращать внимание на следующее: не слишком ли их много (мало), осмысленные ли они, правильно ли выбран эффект (анимация, всплывающие подсказки)? Нужно проверить те документы, к которым осуществляется переход по ссылкам. Изменение внешнего вида документа: имеет ли пользователь право менять размер шрифта или размер окна, есть ли у него это право? Как организовано разделение на топики: не слишком ли много приходится прокручивать, есть ли отдельные ссылки на определения, детали и т.д.? Правильно ли оформлены таблицы, иллюстрации, списки, отступы: необходимо свести к минимуму прокрутку, при использовании графических изображений оценить время загрузки изображения и т.д. Все ссылки обязательно следует проверять непосредственно в режиме онлайн, желательно это сделать во всех основных операционных системах и программах просмотра, на которые рассчитан документ.

Что такое техническое редактирование?

Е. Потапова

10.02.2006

Wofford T. The Field of Technical Editing//Mercer University Home Page http://www2.mercer.edu/default.htm 2002

http://www.mercer.edu/enginee....ing.pdf

Техническое редактирование (Technical Editing) — это гораздо больше, чем проверка запятых или грамматических ошибок, это целая профессия. Техническому редактору требуются многочисленные специальные навыки, которые люди обычно недооценивают. Специалисты насчитывают от 3 до 9 уровней технического редактирования, включая проверку структуры документа, таблиц, именного указателя, глоссария, оглавления, осмысленности инструкций и т.д. Главная задача технического редактора — гарантировать, что документ соответствует поставленным задачам и отвечает нуждам целевой аудитории. Автор обзора выделяет несколько типов профессии редактора, в частности: известный каждому литературный редактор (copy editor); постановщик задач (developmental или content editor); занимающийся организацией процесса документирования редактор-менеджер (production editor); объединенные функции двух последних выполняет редактор проекта (project editor). Также всем известны научный редактор (scientific editor) и корректор (proofreader). Техническими редакторами обычно становятся люди, обладающие опытом разработки технической документации, бизнес-анализа, научного редактирования. Для тех, кто желает приобрести профессию технического редактора, автор обзора предлагает шесть ступеней мастерства в этой области.

Технология информационных карт — Information Mapping

Е. Потапова

02.02.2006

Unwalla M. Raising the standards//TechScribe http://www.techscribe.co.uk 2005

http://www.techscribe.co.uk/techw/information_mapping.htm

Технология информационных карт (Information Mapping) — это методология подачи информации, ориентированная на удобство пользователя этой информации. Компания-разработчик данной технологии (www.infomap.com) предоставляет специальные шаблоны информационных карт, но методологией можно пользоваться и без шаблонов. Три основных компонента информационных карт — анализ, организация и представление информации. Анализ позволяет разбить информацию на 6 определенных типов (например, процесс или инструкция). Организация позволяет создать структуру информации (например, она делится на небольшие фрагменты и выстраивается иерархически). Представление — это использование различных средств подачи информации (графики, рисунки и т.д.). Методология информационных карт — это удобное средство для технического писателя. Существуют и другие похожие методологии, например, структурное документирование с помощью средства DocuTools (www.p-t-a.com) или основанная на языке разметки XML технология Darwin Information Typing Architecture (DITA).

Чем на самом деле занимается технический писатель?

Е. Потапова

20.01.2006

Walsh I. So what exactly does a Technical Writer do? //Klariti.com: Klariti Writing Services Ireland http://www.klariti.com 2005

http://www.klariti.com/whatwedo.shtml

Когда технический писатель знакомится, например, в гостях, с посторонними людьми, ему иногда приходится долго объяснять, что это за профессия, и чем именно он занимается. Поэтому автор данной статьи описывает ряд выполненных им проектов, представляющих различные направления деятельности технического писателя, среди которых имеются объемные проекты по документированию автоматизированных систем: за четыре месяца автор статьи полностью документировал все автоматизированные процессы работы банка. Также среди них управление процессом документирования: в качестве менеджера по публикации (Publications Manager) автор статьи разрабатывал полный жизненный цикл документирования, включая создание шаблонов документации, руководств по стилю и учебников. Работа над коммерческими предложениями подразумечает создание методологий составления эффективных конкурентноспособных предложений. Еще один вид деятельности — написание статей, разработка учебных примеров (Case Studies) для обучения технических писателей. Другие виды деятельности: консалтинг в области документирования, разработка файлов контекстной справки и разработка контента веб-сайтов. Таким образом, оказывается, что деятельность технического писателя крайне разнообразна. Чем больше заказов он выполняет, не отказываясь ни от небольших локальных задач, ни от масштабных проектов, тем выше квалификация технического писателя.

Нужны ли указатели?

Е. Потапова

13.01.2006

The Future of Indexing? Wright J. //WritersUA Training and information for User Assistance Professionals http://www.winwriters.com 2004

http://www.winwriters.com/articles/checklist/index.html

Компания Microsoft заявляет, что указатели (index) не поддерживаются в новой справочной системе Windows Longhorn Help. По мнению представителей компании Microsoft указатели никому не нужны и ими никто не пользуется. Вместо указателя предлагается использовать автоматизированный поиск. Другой «конкурент» указателям — метаданные, приобретающие всю большую популярность у разработчиков программного обеспечения. Постепенно появляется мнение об избыточности указателей. Это связано с отсутствием подходящего программного обеспечения для разработки указателей и с тем, что их разработка всегда требует участия квалифицированных высокоплачиваемых специалистов. Однако экономить на указателях не стоит. Указатели и каталогизация напрямую связаны с типом мышления и ментальностью авторов каталога или указателя. На этом уровне выявляется важное отличие указателей от автоматизированных поисковых систем и метаданных. Там, где из-за различных нюансов ментальности и разных культур автоматизированная система даст сбой, указатель поможет пользователю найти доступ к нужной информации. Конечно, указатели должны претерпеть определнные изменения в следующем поколении справочных систем. Это требует дополнительных вложений, но они непременно окупятся.

DITA — механика проекта «единого источника»

Е. Потапова

21.12.2005

Baril F. DITA - The mechanics of a single sourcing project// Aggregated Proceedings for the Extreme Markup Languages® Conferences (2001-2005) http://www.mulberrytech.com/Extreme/Proceedings 2004

http://www.mulberrytech.com/Extreme....01.html

Статья представляет собой характеристику проекта по документированию с использованием технологии DITA и единого источника. Планировалось создать документацию, в окторой как можно больше фрагментов используется в разных документах несколько раз. Поэтому было решено применить технологию Darwin Information Typing Architecture (DITA) — универсальную XML-технологию создания, выпуска и распространения технической документации. Базовой структурной единицей в DITA является топик. Вся информация по проекту легко делилась на виды информации, применяемые в технологии DITA: топик-задача, топик-концепция или топик-справка. Также разработчики документации воспользовались заложенной в технологии DITA возможностью создавать собственные категории топиков. Во всей широте использовались так называемые карты DITA: для создания документов, связывания их, организации навигации. Также задача разработчиков была облегчена тем, что в DITA включены компоненты DTD и примеры таблиц стилей XSL. С помощью технологии единого источника была разработана (графические схемы прилагаются) конечная документация трех видов: система контекстной справки, справочная система с веб-интерфейсом, руководства и учебники в формате PDF.

Что кроется за упрощенным английским языком?

Е. Потапова

14.12.2005

Beyond Plain English//TechScribe http://www.techscribe.co.uk 2005

http://www.techscribe.co.uk/techw/se.htm

Упрощенный английский — средство повышения качетсва технической документации. В последнее время эта тема становится все более популярной. Организаторы кампании за простой (Plain English) английский язык (http://www.plainenglish.co.uk/campaign.html), утверждают, что это язык, который должен быть понятен каждому с первого раза. Организаторы кампании предоставляют руководства по стилю, помогающие освоить простой и ясный стиль изложения. Профессиональные писатели и журналисты высоко оценивают эти руководства. Однако чтобы избегать неяснотей, необходим контролиуемый стиль изложения. Примером такого стиля может быть разработанный в Европейской ассоциации авиационной и оборонной промышленности (ASD, Aerospace and Defense Industries Association of Europe) упрошенный технический английский язык (ASD Simplified Technical English, ASD-STE100). ASD-STE100 — это спецификация, содержащая набор грамматических правил и словарь. В словаре для каждого синонимического ряда предусмотрено только одно слово. Правила регулируют длину предложений, принадлежность слова к той или иной части речи (одно и то же слово не может быть несколькими разными частями речи), количество времен глагола и т.д. По мнению авторов статьи, ASD-STE100 удобен в той документации, где однозначность толкований имеет решающее значение, и неуместен в деловых и маркетинговых текстах. К статье прилагается список программных средств по редактированию и стилистической правке.

Советы по разработке оглавления

Е. Потапова

08.12.2005

Weber J.H. Hints for developing a table of contents//Technical Editors Eirye: Resources for technical editors http://www.jeanweber.com 1998

http://www.jeanweber.com/howto/tochints.htm

Тщательное планирование всего проекта еще до начала работ — один из залогов успеха в области технических коммуникаций. Разработка оглавления документации — одна из составляющих такого планирования. При этом оглавление — это не просто перечень тем, а краткое содержание и одновременно план, по которому нужно разрабатывать документацию. Ошибкой было бы считать, что оглавление и логическую структуру документа можно слепить в последний момент, когда вся документация уже написана, особенно если над ней работает несколько человек одновременно. Для начала определите ожидания заказчика по отношению к будущему документу, цель создания документа и предполагаемую область применения. Опишите для себя будущего пользователя документации, оцените степень его подготовки, а также его отношение к создаваемому документу. Далее организуйте «мозговой штурм» (желательно с привлечением коллег) и постарайтесь составить список того, что должны знать в конечном счете пользователи (на этом этапе еще не требуется точная структура и правильно сформулированные заголовки). Затем составьте примерное оглавление и продумайте, какие вопросы возникнут у пользователей по поводу оглавления и документа в целом. Составьте новое оглавление с учетом этих вопросов. Продумайте окончательную формулировку заголовков. Покажите оглавление нескольким потенциальным пользователям и примите во внимание их вопросы. Таким образом, перед вами окажется первая редакция оглавления, которая одновременно является и планом написания документации.

Создание справочных систем для карманных компьютеров

Е. Потапова

28.11.2005

Natarajan P. Designing Online Help for Pocket PCs //STC's Special Interest Groups http://www.stcsig.org 2005

http://www.stcsig.org/usability/newsletter/0404-pocketpc_help.html

В связи с увеличивающейся популярностью и расширением сферы применения портативных компьютеров растет количество устанавливаемого на них ПО, следовательно, возникает необходимость создания справочных систем к этому ПО. В статье рассматриваются проблемы и перспективы создания справочных систем для устройств с операционной системой Windows CE. Существуют значительные отличия справочных систем для карманных ПК от таковых для персональных компьютеров: отсутствие самостоятельной справочной системы (есть только контекстная справка), соответственно отсутствие указателей, полнотекстового поиска, всплывающих окон и т.д.; ограниченные возможности графики. Все эти ограничения накладывают отпечаток и на содержание справочной системы. Так, размер топиков справки не может превышать 50-70 слов, объем справочной системы в целом также ограничен. Поэтому техническому писателю при написании текста справочной системы придется ограничить как концептуальную, так и собственно справочную информацию. Поэтому необходимо очень четко понимать стоящие перед пользователям задачи и описывать шаги по их решению. Информация в таких справочных системах всегда представлена линейно. Допускается только один уровень гиперссылок. Система поиска менее функциональна по сравнению со справочными системами для персональных компьютеров, поэтому технический писатель должен быть особенно внимателен при подборе и структурировании материала, чтобы облегчить, а не затруднить пользование справочной системой. Создание справочных систем для карманных компьютеров — это новая область технических коммуникаций, которая продолжает развиваться.

Применение принципа «единого источника» в издательской системе Adobe FrameMaker

Е. Потапова

18.11.2005

Marques M. Single-sourcing with FrameMaker //Techwr-l: Information in Focus, Inc www.techwr-l.com 2005

http://www.raycomm.com/techwhirl/magazine/technical/singlesourcing.html

Многие технические писатели интересуются принципом «единого источника», дающим возможность использовать одно и тоже содержимое документации при ее публикации в разных форматах, не хотят тратить время и средства на освоение соответствующих технологий, например, XML. Для них есть более простое решение — применение этого принципа в уже освоенной ими издательской системе Adobe FrameMaker. Принцип единого источника рассматривается в данной статье на двух примерах: публикация документации по одному продукту, у которого есть ряд модельных модификаций, и публикация в рамках одной документации комплекта документов, рассчитанных на разную целевую аудиторию. Для решения первой задачи можно использовать целый ряд функций программы, например, «условный текст» (conditional text). С помощью этой функции технический писатель задает, в каком именно руководстве нужно печатать те или иные главы или отрывки. Для решения второй задачи может потребоваться изменение порядка фрагментов документации. Это можно сделать с помощью функции «вставка» (text insets), используя которую технический писатель импортирует в свой документ текст из внешнего источника посредством ссылки на него. В зависимости от того, начинается ли в компании новый проект, или переводится «на новые рельсы» уже существующий, переход к работе по принципу единого источника займет от нескольких часов до нескольких недель.

Советы техническому писателю: как писать руководство пользователя

Е. Потапова

11.11.2005

User Guides Online Tutorial//Klariti.com: Klariti Writing Services Ireland ttp://www.klariti.com 2004

http://www.klariti.com/technical-writing/User-Guides-Tutorial.shtml

Руководство пользователя — это документ, в котором в доступных среднему пользователю словах объясняется, как пользоваться тем или иным программным обеспечением. Как явствует из названия, руководство пользователя рассчитано на пользователя, то есть на человека не обязательно владеющего техническими знаниями. Потому, прежде чем приступить к написанию документа, продумайте, кто и с какой целью будет его читать, какая степень детализации требуется, нужны ли иллюстрации и какие? Учтите, что пользователи читают руководство, когда хотят выполнить с помощью программного обеспечения определенные функции. Ваша задача — коротко и ясно ему то объяснить. Учтите, что перед разными пользователями стоят разные задачи. Поэтому следует либо последовательно описать все их функции в одном документе, либо написать ряд документов для разных групп пользователей. Руководство пользователя состоит из следующих частей: заглавная часть (обложка, сведения об авторских правах, оглавление, предисловие) и основная часть (описание процедур работы с ПО). В основной части информацию необходимо делить на небольшие разделы, в зависимости от конкретных функций или окон программы. Используйте конструкцию «если... то» в том случае, если пользователю надо делать выбор. Для разветвленных процедур, рисуйте схемы и диаграммы. Следующая часть руководства — справочные материалы (опции запуска программы, список «горячих клавиш», список сообщений об ошибках, список возможных проблем, часто задаваемые вопросы и т.д.). Заключительная часть обязательно содержит глоссарий и предметный указатель.

Создание системы управления контентом на основе технологии единого источника и языка разметки XML

Е. Потапова

03.11.2005

Sapir R. An Overview of Single Sourcing with an XML Content Management System //KeyContent.org www.keycontent.org 2005

http://www.keycontent.org/tiki-index.php?page=XML+CMS

Создать систему управления контентом на основе технологии XML для публикации технических документов с помощью единого источника на самом деле достаточно просто. Основные преимущества системы управления контеном на основе XML — это: легкое получение метаданных, описывающих контент; структура документов, ориентированная именно на контент; создание сложных запросов для получения конкретной информации. Первый шаг в создании такой системы — конвертация всех имеющихся типов данных (текстовые файлы, таблицы, презентации, диаграммы) в формат XML. Необходимо выбрать описание типа документа (DTD), например, DocBook или DITA. Также нужно включить в файлы метаданные, например, название программного продукта, имя автора документа, номер версии. Всю имеющуюся информацию желательно поделить на минимальные значимые единицы — топики. Второй шаг — хранение и управление контентом. Вся информация должна храниться в единственном формате — XML. Даже некоторые графические форматы (SVG, VML) можно конвертировать в формат XML. Если весь контент хранится в базе данных в одном формате, легко создавать и выполнять даже самые изощренные запросы. Также в базе данных должна существовать система контроля версий для того, чтобы фиксировать каждое изменение элементов контента. Последний шаг — публикация контента. С помощью различных запросов можно выбирать информацию из БД по любому принципу, создавать документы и публиковать их. Для этого используется расширяемый язык стилей — XSLT (Extensible Style Language Transformation).

Ролевой подход к документированию

Е. Потапова

24.10.2005

Persona based documentation/InfoSourcing Web solution and documentation outsourcing http://www.info-sourcing.com 2005

http://www.info-sourcing.com/Persona_Documentation_Approach.htm

У документации вслед за программным продуктом есть свои самые разные типы пользователей — начинающие, высококвалифицированные, случайные и т.д. При подготовке к разработке программного продукта менеджеры исследуют каждый тип конечного пользователя, создавая те или иные роли пользователя. Разные роли пользователей должны быть учтены при разработке технической документации. С первого дня разработки программного продукта технические писатели должны изучать роли пользователей и планировать документацию на основе полученных данных. Роль в данном случае состоит из двух компонент — того, какие задачи выполняет пользователь, и уровня его подготовки. В зависимости от этих двух факторов нужно описывать действия пользователя при работе с программным продуктом. При описании каждой операции нужно немного «забегать вперед» и показывать перспективы и возможности той или иной функции программного продукта. Это простимулирует интерес пользователя к документации и программному продукту. После написания документации желательно организовать фокус-группу, состоящую из пользователей с разными ролями, для тестирования документации. Когда продукт выпущен и документация опубликована, желательно провести среди пользователей ряд опросов об удобстве работы с документацией и ее информативности.

Кто такие технические специалисты, и как с ними бороться

Е. Потапова

19.10.2005

SMEs in a Nutshell //Docsymmetry http://www.docsymmetry.com 2005

http://www.docsymmetry.com/SMEs.html

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

Путешествие в мир ISO 9000 и ISO 14000

Е. Потапова

10.10.2005

The Magical Demystifying Tour of ISO 9000 and ISO 14000//International Organization for Standardization http://www.iso.ch 2005

http://www.iso.ch/iso/en/iso9000-14000/understand/basics/general/basics_1.html

ISO (International Organization for Standardization) разрабатывает стандарты с 1947 года, однако, большинство узнает о ней только когда сталкивается со стандартами ISO 9000 и ISO 14000. Причина в том, что все остальные стандарты ISO — узко специальные в каких-либо технических областях, их хорошо знают инженеры и технические специалисты. В свою очередь, ISO 9000 и ISO 14000 — это универсальные стандарты на организацию управления, которые задают предприятию эффективную модель управления, помогают повысить производительность и снизить убытки. Стандарты серии ISO 9000 обеспечивают управление качеством (quality management), т.е. соответствие требованиям заказчика и нормам качества для того или иного продукта или услуги. Cтандарты серии ISO 14000 определяют управление экологическими требованиями (environmental management), т.е. помогают организации снизить вредное воздействие производства на природу. При этом оба стандарта контролируют не конечный результат деятельности компании, а сам процесс ее функционирования. Поэтому ни один из этих стандартов не является стандартом на продукт, хотя при надлежащем устройстве производства компания получит соответствующее качество продукции. При внедрении стандартов ISO возможны следующие формы участия: сертификация (независимая организация подтверждает соответствие стандарту), регистрация (независимая организация записывает факт соответствия в реестр) и аккредитация (организация по аккредитации дает право организации самостоятельно проводить сертификацию в той или иной области). При этом все эти операции осуществляет не ISO, а независимые лаборатории и аудиторские компании, ISO — это только разработчик стандартов.

Технология DocBook: часто задаваемые вопросы

Е. Потапова

20.09.2005

Pawson D. DocBook Frequently Asked Questions//Dave Pawson's Home page http://www.dpawson.co.uk 2005

http://www.dpawson.co.uk/docbook/

Материал представляет собой чрезвычайно полный сборник часто задаваемых вопросов по всем аспектам технологии DocBook. Вопросы делятся на ряд основных групп, включая: Основы DocBook и справочная информация; Разметка в технологии DocBook; Средства работы с технологией DocBook; Каталоги и технология DocBook; таблцы стилей DocBook XSL; таблицы стилей DocBook DSSSL. В каждом разделе содержится порядка 50-60 ответов на вопросы. В каждый ответ в случае необходимости включены конкретные примеры тегов. В раделе посвященном разметке, содержатся вопросы, касающиеся организации всех видов ссылок, условного текста, включения в документ DocBook программного кода, элементов языка разметки MathML, разметки глоссария, примечаний, протоколов, указателей, указания языка и многих других проблем. В разделе Средства работы рассматриваются проблемы, связанные со средствами разработи файлов в формате XML. В частности рассматриваются такие вопросы, как конвертация файлов XML в формат PDF; использование технологии DocBook в операционной системе Mac OSX; просмотр DTD в файлах формата HTML; выбор конвертора FO; конвертация файлов в формате Microsoft Word в файл DocBook; применение продукта OpenOffice в проектах DocBook и многие другие.

Мир тесен: условия работы технического писателя

Е. Потапова

20.09.2005

Doulton M.G. Small World: Workplace Survey of Technical Writers//Intercom Online: The magazine of the Society for Technical Communication http://www.stc.org/intercom/ Septemer 2005

http://www.stc.org/intercom/PDFs/2005/200509_14-17.pdf

Профессия технического писателя обеспечивает известную гибкость в отношении условий и форм работы. Однако на нас в любом случае оказывают влияние такие вещи, как трудовое законодательство, локальная и корпоративная культура, личные ситуации, профессиональная этика. В этой статье систематизируются результаты опроса технических писателей из 5 регионов (Австралия, Европа, Индия, Израиль, Северная Америка) на заданную тему. Результаты этого исследования представляют интерес для всех организаторов проектных групп, состоящих из технических писателей, особенно при работе с писателями из разных стран. Также сами писатели могут понять с помощью данной статьи, являются ли их требования к условиям работы нормой для их региона, что им ждать при переезде в другую страну или при работе с коллегами из других стран. Были замечены многочисленные общие черты в работе технических писателей по всему миру. Например, все указали, что работают самостоятельно с минимальной помощью редакторов, иллюстраторов, специалистов по созданию указателей и т.д. Также почти все отметили, что примерно треть всего рабочего времени в рамках проекта уходит на внесение изменений, связанных с изменением описываемого предмета. При этом почти все технические писатели отметили, что работа их в высшей степени удовлетворяет; в Израиле и Индии 93% специалистов чрезвычайно довольны своей работой. Был составлен также портрет среднего технического писателя. Как правило, это человек с высшим образованием. Одна треть опрошенных работает в этой области менее 5 лет, одна четверть — от 5 до 10 лет, треть — от 11 до 20, остальные — более 20 лет. Большинство работает в области IT в компаниях-разработчиках ПО. 80% технических писателей на постоянной основе работают в компаниях, в которых 50% из них оказываются единственным сотрудником этого профиля. При этом большинство опрошенных чаще редактируют и обновляют имеющуюся документацию, а не пишут новую.

Плавание на тонущем корабле (Дневник техписа)

Е. Потапова

13.09.2005

Hewitt J. Document Hack (A Technical Writer’s Journal): The Sinking Ship is in Beta//PoeWar.com Writer’s Resource Center http://www.poewar.com 13/7/2005

http://www.poewar.com/archives/2005/07/13/sinking/

В идеальных случаях технические писатели работают над документацией с момента разработки продукта. Возможно, те из них, кто постоянно работает в одной компании, действительно встречались с такими идеальными ситуациями. Я (пишет автор — прим. ред.) как писатель-фрилансер с этим не встречался ни разу. Обычно документацию начинают писать программисты или инженеры. Они делают это не очень умело; к тому же написание документации не является для них первоочередной задачей. Кроме того, они не знакомы ни с одной системой разработки документации и пользуются для ее создания текстовым процессором Microsoft Word. Далее, к моменту написания хоть какой-то документации к программному продукту выходит вторая версия этого продукта. Во многих случаях разработкой следующей версии занимается другая группа разработчиков, и они-то пишут следующую версию технической документации. Когда до выпуска третьей версии (и документации к ней) остается несколько недель, обычно приглашают внешнего технического писателя. Так как уже нет времени писать полноценную документацию «с нуля» моя задача взять два предыдущих документа и сделать из них третий, к третьей версии продукта, которая при этом все еще дорабатывается. От меня требуются просто чудеса, что же я могу сделать на самом деле? Моя главная задача — это все-таки разработать документ в срок. Только во вторую очередь я могу думать о качестве документа, хотя и делаю в этом направлении все от меня зависящее. Интересно, что те технические писатели, которые работают постоянно в одной компании периодически пытаются как-то менять эту ситуацию к лучшему. Но они редко достигают успеха на этом поприще. Документация все еще не является важной областью для компаний разработчиков и эта ситуация не скоро изменится.

Использование возможностей мультимедиа при создании справочных систем

Е. Потапова

07.09.2005

Bradford A. N. Determining When to Use Show-Me Helps and Demos// WritersUA Training and information for User Assistance Professionals http://www.winwriters.com 2005

http://www.winwriters.com/articles/showme/index.html

В наши дни технический писатель может воспользоваться большим количеством мощных и одновременно простых средств разработки мультимедийного контента. Использование мультимедийных технологий при разработке документации позволяет сделать ее значительно интереснее для пользователя. Существует несколько видов мультимедийной документации: мультимедийные учебники (tutorial) — специальные программы-учебники по продуктам и технологиям; демонстрационные ролики (demonstration или demo) — визуальные ролики, чаще рекламного характера; «виртуальные туры» (guided tour) — что-то среднее между двумя первыми. Предлагается создать новую разновидность — наглядную справочную систему (show-me help). По объему она должна быть сравнительно небольшой и не очень интерактивной (как «тур» или демо-ролик), но при этом информативной. Кроме того, наглядная справочная система, как и большинство справочных систем, должна быть внедрена непосредственно в программный продукт. Как и у любой новой технологии, у наглядной справочной системы есть свои преимущества и недостатки, но затраты на освоение окупаются удобством пользователей. Для разработки подобных справочных систем известны три основных программных продукта: TechSmith Camtasia Studio, Macromedia Robohelp 5 и Qarbon ViewletBuilder. По мнению автора последнее средство разработки является наиболее эффективным и удобным в использовании. Чтобы разработать качественную наглядную справочную систему, нужно стараться привлечь внимание пользователя, сделать ее яркой и красочной, включить аудио материалы, наполнить ее хорошо написанным содержимым.

Проект LaTeX3 — что это такое?

Е. Потапова

07.09.2005

Mittelbach F. Rowley C. The LaTeX3 Project//LaTeX project site http://www.latex-project.org 1999

http://www.latex-project.org/guides/ltx3info.pdf

Система обработки текста LaTeX3 планируется как смена системе LaTeX. В системе LaTeX3 будут значительно расширены возможности обоработки самых разных документов, будут в большей степени выполняться требования для типографской публикации. Идеологическая близость языка разметки TeX к современным развивающимся языкам разметки, таким, например, как XML, позволяет системе LaTeX3 автоматизировать конвертацию одних файлов в другие. Сближение с технологией XML — одна из задач разработки новой системы. Так, пользовательский интерфейс LaTeX3 должен обеспечить поддержку концепций «сущности» (entity), «атрибутов» (attributes) и пр., которые присущи XML, но отсутствуют в базовой системе LaTeX. В системе LaTeX3 предполагается интерфейс дизайнера, выполняющий двойную функцию. С одной стороны, будут реализованы все существующие типографские требования к публикации документа, с другой, будет осуществляться связь общей разметки документа с форматированием. Эти две функции интерфейса совершенно независимы, поэтому можно разрабатывать разные макеты для одного DTD. Интерфейс открывает перспективы прямого использования DTD и других XML-документов путем определения соответствующего интерфейса TeX. Интерфейс дизайнера будет поддерживать спецификации DSSSL и идеологию таблиц стилей, применяемых в технологиях XML и HTML. Пользовательский интерфейс будет поддерживать различные типы форматирования (например, форматирование, принятое в технической документации, в академических научных исследованиях, в химических формулах и т.д.) В 1999 г. был представлен релиз LaTeX 2e, в котором воплощена в жизнь большая часть пунктов программы по созданию LaTeX3. Сам проект LaTeX3 является долговременным, для его поддержки создан фонд проекта LaTeX3.

«Живая документация»: будущее технической документации

Е. Потапова

02.09.2005

J. Hewitt Living Documentation: The Future of Technical Writing//PoeWar.com Writer’s Resource Center. http://www.poewar.com 2004

http://www.poewar.com/archives/2005/03/04/living-documentation/

Автор статьи предлагает новую концепцию разработки и производства технической документации. Особенность технической литературы в том, что ее редко читают целиком «от корки до корки». Часто не только пособия по какому-либо программному продукту, но и эксплуатационная документация на него должна быть сдана и «сдается» еще до того, как дописан программный код, что влечет за собой неточности в документации. Эти и другие проблемы разработки технической документации автор статьи предлагает решить с помощью собственной методики, названной «живая документация» («Living documentation»). «Живая документация» разрабатывается параллельно с разработкой порграммного продукта, все изменения сразу же вносятся в файлы контекстной справки и электронную документацию. Компания-производитель отслеживает обращения пользователей к электронной документации, на основе чего обнаруживаются наиболее проблемные элементы программного продукта и самой документации. Документация должна существовать в следующих формах. 1) Файлы в формате PDF, которые пользователь распечатывает по мере необходимости. Также у пользователей должна быть возможность распечатать эту документацию «print-on-demand books» в книжном магазине. 2) Файлы электронной документации с многочисленными средствами отслеживания обращений. 3) Файлы контекстной справки.

Перспективы управления контентом на основании технологии единого источника

Е. Потапова

17.08.2005

Mescan S. Single-Source Content Management Can Take You Further//Techwhir-l: The Internet forum for technical communicators www.techwr-l.com 2005

http://www.techwr-l.com/techwhirl/magazine/technical//sscm_overview.html

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

Технический писатель как независимый субподрядчик

Е. Потапова

12.08.2005

Torres B. Third- Party contracting as a lone writer/Intercom Online: The magazine of the Society for Technical Communication http://www.stc.org/intercom/ June 2005

http://www.stc.org/intercom/PDFs/2005/200506_18-21.pdf

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

Нужен ли фрилансеру свой веб-сайт?

Е. Потапова

05.08.2005

A Wayman. Do Writers Need Websites? // Freelance Writers http://freelancewrite.about.com. 2004

http://freelancewrite.about.com/od/marketyourwritingyou/a/websites.htm

По мнению автора статьи у каждого писателя-фрилансера должен быть собственный веб-сайт. Можно привести следующие аргументы в защиту этого мнения. Во-первых, заказчики ищут писателей любого профиля «авторов статей, копирайтеров, технических писателей» в Интернете. Автор подтверждает этот факт примерами из собственной практики. Во-вторых, этот один из самых недорогих способов рекламы своей кандидатуры. Для тех, кто решил обзавестись своим веб-сайтом, автор статьи дает несколько рекомендаций. В качестве названия веб-сайта можно выбрать свое имя, как это сделала автор статьи «www.AnneWayman.com», или одно-два ключевых слова, относящихся к той разновидности текстов, которые вы пишете. Еще одна рекомендация — дизайн веб-сайта должен быть максимально простым. Информационное наполнение должно быть небольшим по объему, но содержательным. Например, ваше краткое резюме и отрывки из ваших текстов разной направленности. Для разработки веб-сайта можно пользоваться простейшим редактором веб-страниц типа WYSIWYG, например редактором Microsoft FrontPage. Последний шаг — зарегистрировать сайт в поисковых системах в Интернете. Технология открытого источника в редакторе RoboHelp X5: практические рекомендации.

Процесс документирования на целлюлозно-бумажном предприятии

Е. Потапова

27.07.2005

Salonen T. Technical documentation processes in paper mill life cycle //VTT Industrial Systems http://www.pim.vtt.fi 2004

http://pim.vtt.fi/paperixi/public/D1_1.pdf

Проект PaperIXI (разработан рядом крупных финских целлюлозно-бумажных предприятий) среди прочего определяет производство, публикацию и внутрикорпоративное распространение технической документации, связанной со всем жизненным циклом целлюлозно-бумажного предприятия. Особое внимание уделяется совместной работе разных подразделений при разработке технической документации. Для организцации производства, хранения и распространения технической документации используется моделирование бизнес-процессов (Business Process Modeling, ВРМ). Для того чтобы определить пути реорганизации процесса документирования и документооборота, предлагается описать текущее состояние с помощью диаграмм IDEF0, а затем проанализировать его. Затем можно разрабатывать идеальный процесс документирования и документооборота на производстве. При создании единой системы производства и хранения документации нужно учитывать такие атрибуты каждого документа, как язык, версия, формат, структура данных и т.д. Чтобы избежать несовместимости форматов, рекомендуется хранить всю документацию в формате XML. В статье приведены многочисленные примеры диаграмм IDEF0. В приложении содержится библиография по вопросам моделирования бизнес-процессов, подробное рассмотрение методологии IDEF0.

Выбор редактора для документов в формате XML

Е. Потапова

09.07.2005

van den Broek T. Choosing an XML editor. - ed. by Y. Berglund//Arts and Humanities Data Service http://ahds.ac.uk/index.htm 2005

http://ahds.ac.uk/creating/information-papers/xml-editors/

Существует несколько типов редакторов XML: специализированные редакторы XML (предназначенные только для редактирования текстов в формате XML), редакторы кода XML, редакторы XML типа WYSIWYG, текстовые редакторы, имеющие функциональность редактирования файлов XML, и текстовые процессоры, позволяющие среди прочего редактировать документы формата XML в режиме WYSIWYG. Оценивать редакторы текстов в формате XML нужно исходя из того, какие именно функции нужны конкретному пользователю. В статье перечисляется 30 функций: от валидации файла в формате XML до наличия встроенных процессоров XSLT и XSL-FO. В статье приводится ряд сравнительных таблиц функций для почти всех известных редакторов: Authentic, Cooktop, Emacs, Epic Editor, Exchanger XML, jEdit, Microsoft Office, Morphon, NoteTab, Open Office, Oxygen, Serna 1.51, Serna 2.0b, TextPad, TurboXML, UltraEdit, VIM, Xmetal, XML Mind, XML Writer. Для каждого редактора в статье есть отдельное описание с информацией о компании-разработчике, цене, поддерживаемой операционной системе и языке описания схемы. Также в кратком описании приводятся особенно выраженные преимущества и недостатки редактора и даются советы, как справиться с теми или иными недостатками. В заключение проводится некоторая оценка редакторов, например, лучшими редакторами кода XML признаются программные средства Emacs, Exchanger и Oxygen.

«Конвейерное производство на заказ» технической документации

Е. Потапова

27.06.2005

Rombauts Y. Applying "mass customisation" manufacturing principles to solve technical communication problems //Cherryleaf http://www.cherryleaf.com 2005

http://www.cherryleaf.com/news-masscust1.htm

Большинство компаний и подразделений, работающих в области технических коммуникаций, сталкиваются со следующей проблемой: необходимо разрабатывать документы, отвечающие сиюминутным нуждам конкретного заказчика и отдельных групп пользователей, и вместе с тем одну и ту же информацию приходится публиковать многократно. Эту проблему можно решить, если воспользоваться опытом промышленных предприятий. Например, в автомобильном производстве одни и те же детали производятся для машин самых разных моделей и отличия между моделями проявляются на самом последнем этапе производства. Это возможно благодаря стандартизации. Аналогично, в сфере технических коммуникаций информацию можно делить на сравнительно небольшие универсальные модули и использовать один и тот же модуль много раз в разных контекстах. Управление этими модулями может осуществляться средствами языка разметки XML, определяющим условия, при которых то или иное содержание включается в документ или исключается из него. На основе универсальных модулей можно разрабатывать системы технических коммуникаций (technical communication system, TCS). Такая система должна осуществлять управление репозиторием на основе технологии единого источника, контроль версий, документооборот, управление публикациями и т.д.

Обзор программного обеспечения для снятия снимков экрана

Е. Потапова

20.06.2005

Review of Screen Capture Tools

Ellison M. //WritersUA Training and information for User Assistance Professionals http://www.winwriters.com 2005

http://www.winwriters.com/articles/capturetools/index.html

Снятие снимков экрана является неотъемлемой составляющей разработки технической документации. Многие разработчики документации используют известную комбинацию <Alt>+<Print Screen> для получения снимка активного окна, а затем кропотливо обрабатывают изображение в графическом редакторе. В данной статье приводится обзор 5 наиболее распространенных программ для снтия снимков экрана. Параметры сравнения — удобство интерфейса, количество функций, возможности снятия снимков выбранных областей экрана, возможности редактирования изображения. При запуске программы FullShot 8.5 (Inbit Inc.), ее меню добавляется к меню активного на данный момент окна или программы. Благадаря функции настроек это программное средство позволяет полностью автоматизировать процесс обработки и сохранения изображений в нужном формате. Программное средство HyperSnap-DX 5 (Hyperionics Technology) также обладает функцией настроек обработки изображения. Расширены возможности выделения и обработки отдельных областей экрана, хотя нет возможностей выделять абсолютно произвольные области. Программа Paint Shop Pro 9 (Corel Corporation) — это многофункциональный графический редактор с встроенным средством снятия снимков экрана. Однако это довольно громоздкий редактор. Программ SnagIt 7.2 (TechSmith Corporation) обладает наибольшими возможностями из всех перечисленных средств по снятию снимков экрана. Интересная функция — возможность редактирования текста на снимках экрана. Программа TNT Screen Capture 2 (EC Software) обладает самым простым инерфейсом. Однако в ней нет функций снятия снимков отдельных кнопок и ниспадающего меню. Для удобства выбора конкретного средства к статье прилагается сравнительная таблица функций.

Планирование пользовательской документации — руководство для менеджеров проектов

Е. Потапова

28.05.2005

Johnston J. Planning user documentation - a guide for software project managers//Cherryleaf http://www.cherryleaf.com 2005

http://www.cherryleaf.com/planningarticle1.htm

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

Интеграция технологии XML и издательской системы Adobe FrameMaker

Е. Потапова

25.05.2005

Integrating XML and FrameMaker//Scriptorium Publishing Services http://www.scriptorium.com 2004

http://store.scriptorium.com/.../White_Papers

Издательская система Adobe FrameMaker предназначена для создания технической документации большого объема и сложной структуры. Система эффективно справляется со сложными задачами благодаря таким средствам, как автоматическая нумерация страниц, глав и абзацев, редактор таблиц, автоматическое создание указателей и оглавления, поддержка перекрестных ссылок. Издательская система Adobe FrameMaker 7 может работать в качестве структурированной или неструктурированной среды разработки в зависимости от задач пользователя. Две эти различные функциональности реализованы в двух разных интерфейсах. Неструктурированная среда разработки позволяет конвертировать текстовые файлы в файлы формата XML с одноуровневой иерархией. Если нужна более сложная иерархия, необходимо пользоваться структурированной средой разработки. Основные составляющие структурированной среды это: документ, определяющий элементы (Element definition document, EDD), файл-шаблон, определение типа документа (Document type definition, DTD), файлы с правилами чтения и записи (Read/write rules files). EDD определяет требуемую структуру всех файлов формата Adobe FrameMaker и содержит данные о формате каждого элемента. DTD выполняет ту же функцию по отношению к файлам формата XML. Файл-шаблон используется при импорте файлов формата XML в издательскую систему Adobe FrameMaker. Файлы с правилами чтения и записи определяют настройки импорта и экспорта файлов в формате XML.

Жизненный цикл технической документации

Е. Потапова

25.05.2005

Donn Le Vie, Jr. Developing a Project Life Cycle for Technical Publications//STC Society for Technical Communications http://www.stc.org 2005

http://www.stc.org/ConfProceed/2003/PDFs/STC50-005.pdf

Как правило, технические писатели участвуют в создании продукта только на стадии его выпуска или внедрения. Понимание особенностей деятельности технических писателей поможет разработчикам оценить целесообразность их вовлечения в проект на протяжении всего жизненного цикла продукта (Product Life Cycle, PLC). Целесообразно выделять в жизненном цикле продукта уровни относительных усилий (Relative Levels of Effort, RLOE) и задействовать технических писателей на тех стадиях, для которых значение этого показателя максимально (схема прилагается). Параллельность развития жизненных циклов продукта и документации значительно повышает качество последней и упрощает внедрение ее жизненного цикла. При этом организациям или сотрудникам, разрабатывающим техническую документацию, не нужно оправдывать перед разработчиками свое желание включиться в жизненный цикл продукта с самого начала. Вместо этого лучше создать и внедрить отдельный жизненный цикл технической документации и разъяснить разработчикам его преимущества, соотнеся с принятыми у них жизненными циклами продуктов. Необходимо внушить разработчикам: чем раньше технические писатели возьмутся за дело (желательно, на стадии предпроектного исследования), тем меньше сил и времени разработчики потратят на совещания с ними, и тем качественнее получится документация. Следует настаивать на участии технических писателей в работе еще на стадии ее обсуждения, даже если разработчики будут считать это напрасной тратой времени (схема прилагается).

Интерфейс и справочная система: Повороты на пути в Longhorn

Е. Потапова

20.05.2005

Chandler R. UI & UA Changes on the road to Longhorn//The Helpware group http://helpware.net 2004

http://www.helpware.net/longhorn/review1.htm

Статья посвящена изменениям в дизайне интерфейса пользователя и справочной системе в ожидаемой операционной системе Windows Longhorn. Идеологическая основа этих изменений — повседневный опыт пользователя, который хочет сделать интерфейс более интуитивно понятным, а справочную систему более релевантной. Техническим писателям предлагается новая среда разработки — MAML (Microsoft Assistance Markup Language) XML, работа в которой сильно отличается от всего, к чему они привыкли. MAML включает элементы разметки для разработки справочных систем формата Windows Longhorn. По всей вероятности разработчики средств создания справочных систем будут выпускать на рынок программы, основанные на технологии MAML XML. Технология Longhorn Help предполагает и другие новшества. Единая справочная панель (Help Pane), совместно используемая всеми приложениями, предоставляет совмещенную точку входа в справочную систему. Активное содержимое служит для отображения справочной информации, связанной с текущим состоянии компьютера пользователя. В ближайшей перспективе операционной системой Windows Longhorn будут поддерживаться хелп-файлы формата CHM и WinHelp, однако, дальнейшая их судьба неизвестна.

Дневник техписа: Маркетинг и технический писатель

Е. Потапова

17.05.2005

Hewitt J. Document Hack (A Technical Writer’s Journal): Marketing and the Technical Writer//PoeWar.com Writer’s Resource Center, www.poewar.com 4/12/2005

http://www.poewar.com/...technical-writer/

Для технического писателя очень важно сотрудничество с отделом маркетинга, так как документация в известной степени — это инструмент маркетинга. В отделе маркетинга есть доступ к отзывам пользователей о программных продуктах и документации к ним: рекламациям, жалобам в звонковый центр (call canter) и т. д. Это обеспечивает обратную связь для разработчиков и технических писателей, так как сами они обычно не располагают такой информацией. Еще одна особенность совместной работы с отделом маркетинга — то, что на разработку программного продукта маркетологи смотрят с точки зрения его реализации на рынке. Их советы на начальной стадии разработки помогают избежать многих ошибок. Вообще, сотрудничество с отделом маркетинга помогает определить цели проекта по разработке программного продукта, сформулировать стиль документации к нему, определить перспективы реализации программного продукта, оценить отношение пользователей к программному продукту. Техническим писателям рекомендуется поддерживать постоянный контакт с отделом маркетинга, знакомиться с рекламными материалами о тех продуктах, к которым он пишет документацию и соотносить с тиль и содержание документации с рекламными материалами. Даже для фрилансера желательно сотрудничать с отделом маркетинга — ведь это значительно повышает качество документации.

Есть ли будущее у RoboHelp?

Е. Потапова

11.05.2005

Welinske J. The Future of RoboHelp?// WritersUA Training and information for User Assistance Professionals http://www.winwriters.com 2004

http://www.winwriters.com/articles/rh/index.html

Cредство разработки справочных систем RoboHelp существует на протяжении 13 лет, что составляет большой срок для программного продукта. Ему принадлежит 2/3 продаж на рынке средств разработки справочных систем. В 2003 году этот программный продукт приобрела компания Macromedia — крупный производитель программного обеспечения для среды Веб, заплатив за него 65 млн. долл. Однако автор статьи прогнозирует для этого средства разработки справочных систем потерю лидирующего положения, а затем вообще исчезновение с рынка. Этот прогноз строится на личном общении с некоторыми ключевыми сотрудниками компании Macromedia. От них автор статьи узнал, что в компании Macromedia сокращается отдел разработки средства RoboHelp, снижается интерес к сфере технических коммуникаций в целом. Одна из возможных причин — то, что компанией Microsoft разрабатывается новая справочная система Windows Longhorn Help. Попытка адаптировать средство разработки справочных систем RoboHelp к новой системе потребует огромных финансовых затрат. Кроме того, возможно вместо дальнейшего усовершенствования средства RoboHelp компания Macromedia будет усовершенствовать один из его элементов — средство разработки модулей электронного обучения Captivate. Официальное интервью, взятое автором статьи у Мириам Геллер (Miriam Geller), директора по продукции компании Macromedia, не внесло ясность в будущую участь средства RоboHelp. Его исчезновение с рынка будет большой потерей для разработчиков технической документации.

Справочная система с дружественным интерфейсом: условный контент

Е. Потапова

22.04.2005

D. Gash Creating "Smart Help" with Conditional Content// WritersUA Training and information for User Assistance Professionals. http://www.winwriters.com 2005

http://www.winwriters.com/articles/smart_help/index.html

Система контекстной справки должна обладать дружественным интерфейсом: информация должна быть правильно структурирована, необходима возможность пользовательских настроек, дизайн системы должен нравится пользователю. Существует три метода выполнения этих требований для файлов контекстной справки в формате HTML. Первый метод основан на информации, сообщаемой пользователем (User-Provided Data). С помощью нескольких групп кнопок выбора (radio button) пользователь настраивает интерфейс файла справки —, начиная от внешнего вида и заканчивая типом требуемой информации (программный код с подробными пояснениями и ссылка на файл-пример прилагается). Второй метод строится на системной информации (System–provided Data). Содержание файла контекстной справки может зависеть от времени обращения пользователя — месяц, день недели, час и т.д. Информация об этих данных содержится в веб-браузере пользователя, нужно только уметь ей воспользоваться (программный код прилагается). Третий метод базируется на информации, расположенной на самой веб-странице контекстной справки (Page-Determined Data). Когда пользователь обращается к справочной системе, открывается не тот файл, который использовался в прошлый раз, а тот, к которому пользователь обращается чаще всего (программный код и пример прилагаются). Разработка подобной справочной системы значительно облегчит пользователю работу с файлами контекстной справки.

Turbo Demo Professional

С. Иванова

15.04.2005

http://www.programurl.com/turbodemo.htm. – 2005

http://www.programurl.com/turbodemo.htm

Turbo Demo Professional 6.0 от компании Bernard D&G можно использовать для создания демонстраций работы программного обеспечения, интерактивных учебников, презентаций. Turbo Demo Professional 6.0 поддерживает такие технологии, как Java, Flash, Exe, Jif (для интернет-фильмов), Own Player, Avi и Microsoft ASF. Для созданных с помощью Java или Own Player средств интерактивного обучения нет ограничений по объему. В файлах Flash можно создавать не более 16000 кадров. Для создания интерактивных учебников не требуется навыков программирования. Благодаря использованию технологии сжатия данных в Turbo Demo Professional 6.0 создаются файлы небольшого размера. Загрузить демо-версию продукта можно на сайте http://www.turbodemo.com/eng/index.htm.

Моделирование программы с целью обучения пользователя

С. Иванова

15.04.2005

William Horton. Stairway to Expertise – Show me, coach me, test me, let me, congratulate. – 2005.

http://www.winwriters.com/articles/stairway/index.html

В настоящее время область моделирования работы программного обеспечения для пользователя является недостаточно развитой. Большинство интерактивных учебников (tutorials) демонстрируют функции программного обеспечения, а не обучают пользователей работе с ним. Демонстрация часто полезна для продвинутых пользователей, которым необходимо ознакомиться с новыми функциями предлагаемого программного обеспечения. Автор предлагает разделить моделирование работы программного обеспечения (software simulation) для пользователей на несколько уровней. Отдельно выделяется уровень тренировки, когда пользователь выполняет задание на эмуляторе программного обеспечения, следуя подсказкам, и уровень тестирования, когда пользователь выполняет задание на эмуляторе без подсказок. На данном уровне при неправильных действиях пользователя выдаются информативные сообщения об ошибках. Последним уровнем является выполнение задания на реально работающем программном обеспечении.

Средства создания указателей

С. Иванова

15.02.2005

http://www.asindexing.org. – 2005.

http://www.asindexing.org/site/software.shtml

Средства для создания указателей в книгах и технических документах можно разделить на несколько групп по принципу их функционирования. Наиболее известны средства, позволяющие разрабатывать указатели по уже написанному и набранному тексту, а также технологии разметки указателя в процессе написания документа (встроенное индексирование - embedded indexing). Размечать указатели по ходу работы над документом позволяют такие известные средства, как Microsoft Word, Adobe FrameMaker, PageMaker. Встроенное индексирование поддерживется во многих языках разметки, включая HTML, TeX и языки, основанные на XML. Особняком стоят средства класса tagging indexing, позволяющие встраивать дополнительный указатель в уже готовый с помощью вставляемых в файл тегов. На веб-сайте Американского общества индексаторов перечислены наиболее известные средства разработки указателей.

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

Е. Потапова

28.03.2005

M. Ellison Tips and Techniques for Single-sourcing with RoboHelp X5//Writers UA. Nraining and Information for User Assistance Professionals. http://www.winwriters.com. – 2005.

http://www.winwriters.com/articles/robohelp_ss/index.html

Система RoboHelp традиционно рассчитана на разработку систем контекстной справки. Ее возможности в плане создания текстовых документов и конвертации в другие форматы всегда были крайне ограничены. Тенденции последних лет к применению технологии единого источника нашли свое отражение и в последней версии системы: RoboHelp Х5. Теперь в ней предусмотрены функции, позволяющие подготавливать документы к публикации на основании единого источника. К таким функциям относятся: условные композиционные теги «Conditional build tags», условные композиционные выражения «Conditional Build Expressions», произвольное формирование структуры документа, соответствие между стилями редактора RoboHelp X5 и стилями текстового процессора Microsoft Word, исключение гиперссылок из печатного документа, произвольное форматирование, пакетный выпуск документов. Условные композиционные теги применяются в том случае, когда отдельные элементы документа-единого источника нужно маркировать для включения/исключения из печатных документов. Условное композиционное выражение — это булево выражение, определяющее, какие из элементов в условных композиционных тегах включаются в печатный документ. Система RoboHelp X5 содержит ряд шаблонов форматирования для создания документов различных форматов (HTML Help, WebHelp, Print Document и т.д.), пользователь может также создавать собственные шаблоны. Если необходимо сформировать все требуемые документы за один раз, используется функция пакетного выпуска документов.

DITA — XML-решение от IBM для разработки тех. документации

С. Иванова

25.03.2005

Don R. Day, Michael Priestley, David A. Schell. Introduction to the Darwin Information Typing Architecture. – 2003.

http://www-106.ibm.com/developerworks/xml/library/x-dita1/

Darwin Information Typing Architecture (DITA) — это универсальная XML-технология создания, выпуска и распространения технической документации. Она была создана в корпорации IBM в 2000 году. В основу DITA заложен ряд принципов построения тематических модулей и их использования в различной технической документации. Базовой структурной единицей в DITA является тема (topic), формат которой подчиняется определению типа документа topic DTD. Тема — эта единица информации, описывающая задачу, концепцию или связь. Другая особенность DITA - возможность расширять главные темы до новых информационных типов и на уровне словаря используемых элементов, а также использовать один элемент в разных контекстах.

Как писать техническое задание, если нет информации

С. Иванова

25.03.2005

Karl E. Wiegers. Requirements When the Field Isn’t Green. – 2001.

http://www.processimpact.com/articles/reqs_not_green.html

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

Будущее технических писателей

С. Иванова

12.03.2005

Joe Welinske. Trends and Opportunities in Software User Assistance. – Part 1. – 2005.

http://www.winwriters.com/articles/trends/index.html

В статье обсуждаются перспективы профессии технического писателя в США. В последнее время в США упал спрос на технических писателей: около 400 000 человек потеряли работу в период 2001-2004 годов. Это связано с тем, что средние компании избегают держать технических писателей в штате. Чаще всего сотрудники, создающие техническую документацию, совмещают это с другими обязанностями. В статье также перечисляются навыки, которым должен обладать хороший технический писатель: помимо собственно умения писать понятный текст, необходимо быть аналитиком, уметь корректировать и издавать документацию и создавать грамотный индекс. Интересно, как автор разбирает небольшое сообщение для пользователей веб-сайта с позиции качества документации.

MIFDoclet

С. Иванова

12.03.2005

http://java.sun.com/j2se/javadoc/mifdoclet/index.html

Для того чтобы из комментариев к исходному коду приложения, написанного на языке Java, разработать API документацию в формате MIF (формат Adobe FrameMaker) или PDF, можно использовать функции MIFDoclet. MIFDoclet – это расширение JavaDoc, инструмента разработки документации к Java-приложениям, от компании Sun Microsystems Inc. Помимо MIFDoclet для генерации MIF или PDF-файлов необходимо установить на компьютер Adobe FrameMaker и специальную программу пакетной обработки данных. Используя MIFDoclet, можно конвертировать несложные HTML-файлы в те же форматы, что полезно для добавления дополнительных текстов к API документации.

DocBook для начинающих

С. Иванова

04.02.2005

David Rugge, Mark Galassi, Eric Bischoff. Writing Documentation Using DocBook. A Crash Course.-2004.

http://opensource.bureau-cornavin.com/crash-course/index.html

В учебнике по языку разметки технической документации подробно излагается, как разработать документ в формате DocBook. Начинающим полезно почитать вступление для понимания того, что такое DocBook. Перечисленный в учебнике инструментарий для работы с DocBook подходит только для пользователей Unix. Наиболее интересными в учебнике являются главы о структуре документа DocBook, об использовании включений (includes) других файлов в создаваемый документ, подробный перечень тегов для выделения ссылок на элементы интерфейса. Документ DocBook может представлять сразу несколько версий одного текста. Существуют разные способы для создания документа сразу в нескольких версиях. Об этих способах рассказывают авторы учебника.

LaTeX в Windows

С. Иванова

04.02.2005

http://www.toolscenter.org/front_content.php?idcat=26

В качестве системы создания файлов формата TeX часто используется система LaTeX, работающая в среде Linux. Для работы в среде Microsoft Windows можно применять интегрированную среду разработки TeXnicCenter. Все необходимые для разработки файлов LaTeX инструменты собраны в одном приложении. Для того чтобы скомпилировать файл после написания текста, в предоставляемом редакторе необходимо выбрать просто пункт меню. Просмотр скомпилированного файла можно инициировать, выбрав нужный пункт меню, после чего откроется приложение для просмотра. TeXnicCenter является свободно распространяемым продуктом.

Руководство по стилю гипертекстового документа

С. Иванова

04.02.2005

Tim Bl. Style Guide for online hypertext. 1992-1998.

http://www.w3.org/Provider/Style/Overview.html

Данное руководство написано в эпоху начала всеобщего распространения гипертекста, тем не менее, оно может быть полезно как для начинающих, так и для состоявшихся технических писателей. Первое, о чем или о ком нужно помнить при разработке гипертекстового документа, это его будущий читатель. Читатель может иметь представление о той информации, которую вы хотите представить на своем сайте, или быть новичком в этой области. В зависимости от этого информация должна быть организована в разные структуры: пошаговый учебник для начинающих или справочная система для профессионалов. Автор рекомендует использовать несколько структур одновременно, если информация предназначена для нескольких групп пользователей. Вторым вопросом является объем гипертекстового документа: каждый отдельный текст внутри гипертекста не должен превышать 5 страниц формата А4. Для ссылок в документе автор рекомендует использовать четкие названия частей, на которые указывает ссылка. В ином случае читатель может быть не уверен, что перешел к нужной информации.

В помощь пользователям Microsoft Word

С. Иванова

21.01.2005

http://www.techwr-l.com/techwhirl/magazine/technical/wordresources.html

Keith Soltys. Essential Resources for Word Users

Много интересной информации об особенностях текстового редактора Microsoft Word, а также различные программные средства и учебники можно найти на сайте the Microsoft Word MVP (Most Valued Professional) FAQ Site - http://word.mvps.org/index.html. Этот сайт организован добровольцами для решения многочисленных проблем, возникающих при работе с Microsoft Word. Самым полезным разделом сайта является страничка FAQ (Frequently Asked Questions), где можно получить ответ практически на любой вопрос по Microsoft Word. На сайте http://woodyswatch.com существует подписка на новости о Microsoft Office и Windows. Считается, что создатель сайта Вуди Леонхард является одним из самых опытных пользователей Microsoft Word в мире. Другие интересные ссылки для пользователей Microsoft Word приведены в статье.

Искусство переговоров

С. Иванова

21.01.2005

Anne Wayman. Freelance Writers and the Art of Negotiation

http://freelancewrite.about.com/cs/negotiating/a/negotiate.htm

Автор статьи рассуждает о том, как необходимо вести себя техническому писателю с работодателем (в статье – издатель) при заключении контракта. Обычно при получении предложения от работодателя начинающий технический писатель не ставит никаких условий. Автор статьи советует согласиться с первым предложением и попросить прислать договор. Начинающему техническому писателю следует внимательно прочитать договор и в случае несогласия попытаться начать переговоры. Перед переговорами необходимо составить список того, что вы хотите от будущей работы. В качестве темы переговоров может быть большая стоимость слова в тексте, повышение авторского гонорара, плата за маленькие сроки выполнения работы.

Adobe Acrobat 7.0 для Linux

С. Иванова

14.01.2005

http://www.pdfzone.com/news/2079-PDFzone_news.html

Новая версия Adobe Acrobat может функционировать под управлением операционных систем семейства Linux. Компания Adobe Systems Inc. объявляла о поддержке Linux еще для пятой версии этого программного продукта, однако даже Adobe Acrobat 6.0 под Linux так и не заработал. Предприятиям выгоднее использовать LiveCycle Policy Server – это интегрированное с Adobe Acrobat 7.0 и Adobe Reader 7.0 J2ЕЕ-приложение, которое может функционировать на таких платформах, как Windows, Linux, Macintosh. LiveCycle Policy Server является системой управления доступом к документации, как внутри предприятия, так и со стороны внешних пользователей. Подробней о LiveCycle Policy Server можно прочитать на сайте http://www.adobe.com/products/server/main.html.

Able2Extract - инструмент для распаковки PDF, HTML и текстовых документов

С. Иванова

14.01.2005

http://www.documentiq.com/...

Able2Extract от компании Investintech.com Inc. является мощным средством просмотра и конвертации PDF, HTML и текстовых файлов в таблицы Excel, документы Word, файлы в формате HTML и txt. Able2Extract выполняет четыре основных операции: конвертация, экспорт файлов, выделение и передача данных. В качестве примера использования Able2Extract можно привести случай, когда из большого файла в формате PDF требуется выделить определенные данные, например таблицы, и конвертировать их в Excel. Интересной особенностью является то, что для работы с PDF-файлами не требуется Adobe Acrobat. Демонстрационную версию можно скачать на сайте компании-разработчика http://www.investintech.com/a2edownload99.html.

Навигация в гипертексте

С. Иванова

24.12.2004

Diane M. Borgwardt. Providing Sequencing Cues for Non-Linear Text

http://www.stc.org/confproceed/...

Основным отличием гипертекста от линейного текста можно считать значительную свободу навигации внутри первого. В гипертексте читателю предоставлено больше инструментов для быстрого поиска нужной информации. Глоссарий, индекс и колонтитулы принадлежат преимущественно нелинейному тексту, хотя могут применяться и в линейном. Автор статьи провела исследование с целью выяснить методику чтения гипертекста, имеющего различные средства навигации. В исследовании участвовали 11 человек. Более 55% участников использовали специальные навигационные кнопки, расставленные автором для эффективной навигации внутри текста. Остальные пользовались оглавлением. Навигационными кнопками чаще пользовались люди, знакомые с тематикой текста. Интересно, что никто не использовал индекс.

HTML Help COM Assistant

С. Иванова

24.12.2004

http://www.devcomponents.com/comassistant/

HTML Help COM Assistant – это средство создания справочных систем для COM и ActiveX компонентов, разработанное компанией DevComponents.com. HTML Help COM Assistant анализирует COM-компоненты и создает полную версию документации по объектам, свойствам и методам. При этом в документацию включается MIDL Help String атрибут, стандартный способ документирования объектов и свойств COM-компонента. Приложение использует стандартные HTML файлы в качестве шаблонов, что позволяет их менять при необходимости. Бесплатно скачать полную версию программы можно на официальном сайте компании.

OmniPage Pro 14: преобразование PDF-документов в другие форматы

С. Иванова

17.12.2004

http://www.scansoft.com/omnipage/features.asp#formatting

OmniPage Pro 14. Key Features

Вышла новая версия программного средства обработки PDF-файлов OmniPage Pro 14 Office от компании ScanSoft Inc. В OnmiPage Pro 14 появилась возможность конвертировать PDF-файлы в файлы Microsoft Word 2003, XML, HTML, ODMA. Упрощен процесс работы с документами. Если необходимо выполнять постоянный набор операций с текстом, в OmniPage Pro 14 есть инструмент, запоминающий этот набор операций и упрощающий работу до нажатия одной кнопки. OmniPage Pro 14 поддерживает 119 языков при распознавании текста. Высокая точность при распознавании изображений позволяет конвертировать PDF-файлы в другие форматы практически без ошибок. Интересной особенностью новой версии OmniPage является возможность превратить электронный документ в аудио файл (формат wav), пригодный для прослушивания или записи на CD. Скачать пробную версию продукта можно на официальном сайте компании.

Word или FrameMaker — что лучше?

С. Иванова

17.12.2004

http://www.techwr-l.com/techwhirl/magazine/technical/wordframe.html

Word vs. Frame

В статье перечисляются преимущества и недостатки текстовых редакторов Microsoft Word и FrameMaker при создании больших документов и конвертации файлов в другие форматы. Опыт технических писателей показывает, что лучше использовать FrameMaker от компании Adobe Systems Incorporated. FrameMaker качественно конвертирует файлы в PDF и HTML, поддерживает длинные нумерованные списки и большое количество нумерованных графических изображений. В Microsoft Word подобные опции работают некорректно, с ошибками. Использование большого количества перекрестных ссылок в документе Microsoft Word часто приводит к тому, что часть ссылок перестает работать в отличие от ссылок, созданных в документе FrameMaker. Основным недостатком FrameMaker является непривычный интерфейс для пользователя Microsoft Windows, что требует дополнительных усилий для обучения работы с приложением. Помимо этого во FrameMaker непредсказуемо работает опция проверки орфографии и отсутствует опция проверки грамматики.

Управление большими текстами в Microsoft Word

С. Иванова

10.12.2004

Alison Reeves. Creating and Managing Large Documents in Word

http://www.plainwords.co.uk/WWword_large_docs.pdf

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

Что такое Web Works Publisher

С. Иванова

22.11.2004

David A.Knopf. WebWorks Publisher 2003: True Single Sourcing for Word and FrameMaker Users

http://www.winwriters.com/articles/webworks/index.html#Intro

Web Works Publisher – это приложение от компании Quadralay, конвертирующее файлы редакторов Microsoft Word и Adobe FrameMaker в 11 различных форматов. Web Works Publisher поддерживает форматы HTML 3.2, XHTML 1.0 с CSS, форматы справочных систем WinHelp, HTML Help 1.x, JavaHelp, а также XML и Microsoft Reader. Для конвертации файла создается специальный проект, основанный на шаблоне. Шаблоны определяют внешний вид страницы выходного файла, элементы форматирования страницы, включая заголовки, таблицы, рисунки, а также соответствие стилей исходного документа стилям Web Works Publisher. Шаблоны могут быть изменены пользователем. Приложение поддерживает использование условного текста для создания различных вариантов документации из одного источника.

Новый Adobe Acrobat 7

С. Иванова

22.11.2004

Don Fluckinger. Acrobat 7 announced

http://www.pdfzone.com/news/1900-PDFzone_news.html

Компания Adobe Systems Incorporated объявила о выпуске программного пакета Adobe Acrobat 7 в конце этого года. В новой версии Acrobat разработчики стремятся удовлетворить потребности как крупных корпораций, использующих серверные приложения, так и обычных частных пользователей. К широкому набору функций Acrobat добавится возможность создания PDF из файлов Visio, Microsoft Access и Microsoft Publisher. Запуск конвертации в PDF-файл будет состоять из нажатия на одну кнопку вместо установки большого количества настроек. В Acrobat 7 появится новый инструмент для создания, просмотра и увеличения трехмерных объектов. Комментарии для сгенерированного из Microsoft Word PDF-файла можно будет экспортировать в исходный документ. Стоимость лицензионного продукта будет равна примерно 299 долларам США.

XML-редактор

С. Иванова

12.11.2004

http://www.oxygenxml.com

XML Editor 5.0 от компании SyncRO Soft Ltd. является подследней версией редактора файлов XML и одновременно отладчика XSLT. Редактор поддерживает XML, XSLT, XML Schema, Relax NG , DTD и NRL схемы. Большинство этих схем проверяются средствами . В редакторе реализована функция просмотра структуры XML документа в виде дерева элементов. Комментарии DTD поддерживаются как аннотации вместе с аннотациями XML Schema. Документы Docbook могут быть конвертированы в HTML и PDF без необходимости дополнительной конфигурации, просто следует выбрать один из сценариев конвертации. Единственным важным недостатком этого редактора можно считать то, что не поддерживается русский язык.

Что такое FlashHelp

С. Иванова

12.11.2004

http://www.macromedia.com/software/robohelp/productinfo/flash_help

FlashHelp – это основанный на технологии Flash формат файлов справочных систем или Help файлов. FlashHelp может использоваться в любом приложении, включая созданные в среде разработки Visual Studio .Net. Создавать файлы FlashHelp можно только с помощью программного средства Macromedia RoboHelp X5. Интересным преимуществом FlashHelp следует назвать вертикальную конфигурацию справочной системы, что позволяет ее встроить непосредственно в интерфейс приложения. При использовании Macromedia RoboHelp X5 вам не нужно знать технологию Flash для создания справочной системы. Наиболее важным критерием при выборе справки FlashHelp служит красочность и оригинальность ее интерфейса.

Форумы технических писателей

С. Иванова

12.11.2004

Chuck Martin. Online Communities for User Assistance Professionals

http://www.winwriters.com/articles/community/index.html#bio

В статье Чака Мартина дается обзор он-лайновых коммуникаций технических писателей. На известном портале Yahoo пользователи объединяются в дискуссионные группы и общаются в он-лайн режиме на различные темы, в том числе и на тему технической документации. Группа, где обсуждают вопросы по документированию, называется The Help Authoring Tools and Techniques (HATT). С 1993 года существует рассылка для технических писателей TECHWR-L. Подписка на эту рассылку осуществляется на сайте http://www.raycomm.com. Другие интересные адреса форумов технических писателей, а также подробные объяснения, как присоединиться к форуму, представлены в этой статье.

© «Философт», 2008–2017

+7 (499) 500-44-77

mail@philosoft.ru

SpyLOG