Публикации
Как нанимать технического писателя (часть 5)
23.10.2013
Мы завершаем публикацию статьи с советами о найме технических писателей от канадского эксперта. В заключительной части речь идёт о проверке электронной версии тестового документа и найме неопытных писателей.
Проверьте электронную версию тестового документа
Откройте тестовый документ на своём компьютере. Убедитесь, что отображение всех элементов форматирования включено, как это было, когда вы смотрели на резюме кандидата:
- Нажмите кнопку «Показать/Скрыть».
- Из меню «Таблица» выберите «Показать сетку».
- В меню «Инструменты» выберите «Настройки», а затем выберите вкладку «Вид».
- Под «Знаки форматирования» выберите флажок «Все» и нажмите «ОК».
Как нанимать технического писателя (часть 4)
21.10.2013
В очередной части статьи о том, как нанимать на работу технического писателя, речь идёт о более внимательном рассмотрении тестового документа.
Рассмотрите тестовый документ более внимательно
Теперь вернитесь к оглавлению и для примерно 20% пунктов проверьте, что заголовки записаны точно так же, как заголовки, на которые ссылаются, а также то, что они находятся на указанной странице. Другими словами, если в оглавлении написано, что вы найдёте заголовок «Бизнес-окружение» на пятой странице, откройте страницу 5 и проверьте. Так как все настольные издательские системы генерируют оглавления автоматически, любые отличия между заголовком в оглавлении и страницей, на которую он ссылается, говорит об оглавлении, которое модифицировалось вручную. Это серьёзный недостаток, показывающий, что будут обнаружены и другие серьёзные проблемы с документом. Если вы не сможете учить кандидата использованию текстовых редакторов, не нанимайте этого человека.
Как нанимать технического писателя (часть 3)
18.10.2013
Продолжаем публикацию статьи о том, как нанимать технических писателей. В сегодняшней части речь пойдёт об оценке структуры примеров работ, предоставляемых кандидатами.
Дайте общую оценку примеру документа
Просите кандидатов приносить с собой на собеседование бумажный и электронный варианты примеров их работы. Не отказывайтесь от любых примеров, даже если они «недостаточно технические». Навыки, применяемые для создания документа, который называется, скажем, «Создание превосходного теста» те же, что и применяются для создания документа с заголовком «Настройка сети».
Если бумажный вариант примера документа скреплён степлером в левом верхнем углу, уберите скрепку: вам необходимо иметь возможность переворачивать страницы таким же образом, как если бы вы смотрели в книгу. Проверьте титульный лист. Он не должен быть загромождён большим количеством элементов, а заголовок не должен быть изящным, причудливым или умным. Скорее, он должен указывать на то, что вы найдёте в книге.
Замечание: Прежде чем опробовать следующие инструкции в живом интервью, возможно, имеет смысл сперва попрактиковаться с ними с обычной книгой. Но имейте в виду, что в построении книги и построении технического документа будут некоторые различия.
Как нанимать технического писателя (часть 2)
16.10.2013
Продолжаем публикацию статьи с советами для работодателей, нанимающих технических писателей. В данной части речь идёт о том, как рассматривать резюме технического писателя. Информация будет полезной и соискателям на вакансии технического писателя.
Но как можно узнать, знает ли кандидат, как структурировать документ? Перво-наперво, когда вы публикуете описание вакансии, попросите кандидатов отправить вам их резюме в Microsoft Word. В отличие от PDF- или ASCII-документа, документ Word даст вам множество информации о навыках кандидата по разработке документации.
Начните с просмотра резюме кандидата, независимо от того, в письменном ли оно виде или онлайн, с выключенной разметкой. Чтобы отключить отображение разметки, необходимо сделать следующее:
- Если на странице отображаются знаки форматирования, скройте их, нажав на соответствующую кнопку в меню.
- Если отображается линии сетки для таблиц, скройте их, выбрав «Скрыть сетку» в меню «Таблица».
Как нанимать технического писателя (часть 1)
14.10.2013
Представляем первую часть статьи специалиста канадской компании Docsymmetry с советами для работодателей по найму технического писателя. Несмотря на то, что упор в статье делается на технических писателей из Северной Америки, российские работодатели тоже найдут для себя полезные рекомендации.
Найм технического писателя может быть сложным, даже если вы являетесь одним из них. Где вы можете найти технического писателя? Какие характеристики должны в нём искать? Как можно определить, какой писатель хороший, а какой плохой?
Существует множество сайтов, посвящённых карьере, где вы можете нанять технических писателей. Например, один из них, Elance Find Technical Writers, позволяет писателям получать работу, которую предлагают там работодатели, по модели фриланса. По моему же мнению, однако, проще нанять технического писателя через ваше местное отделение Сообщества для технических коммуникаций (STC). Большинство, если не все, отделения STC имеют банки данных по работе, где вы можете публиковать предложения по трудоустройству. Члены STC в вашем регионе могут затем решить, имеют ли требуемую квалификацию, чтобы устроиться на работу.
Работодатели в Индии могут предпочесть использовать банк данных по работе в организации Технические писатели Индии.
Как писать информацию об авторских правах
11.10.2013
Хорошо построенное руководство пользователя содержит страницу с юридической информацией, на которой содержится информация об авторских правах и торговых марках, относящихся к продуктам вашей компании, а также к сторонним продуктам, упоминаемым в вашем документе.
Начните с упоминания авторских прав на документ, а затем укажите информацию о торговых марках продуктов вашей компании (только тех, которые упоминаются в документе) и имеющих отношения к вашей компании. После этого сделайте упоминание о сторонних продуктах.
Так как многие компании в области написания информации об авторских правах и торговых марках консультируют юристы, убедитесь, что ваше написание этой информации для сторонних продуктов написаны точно так, как трубет третья сторона. Многие компании предоставляют эту информацию на страницах с юридической информацией на своих веб-сайтах; но при этом всё равно часто требуется значительное время на исследование информации об авторских правах. Чтобы оградить других авторов от хлопот по повторому проведению подобного исследования, хорошо создать базу данных информации об авторских правах, тогда авторы смогут просто скопировать эти записи, когда требуется.
Как составлять глоссарии (часть 2)
09.10.2013
Рекомендации по написанию глоссария
Ключевые слова (термины, акронимы и аббревиатуры, используемые в вашем документе) должны появляться в алфавитном порядке. Ключевые слова, начинающиеся с чисел, должны располагаться в глоссарии, как будто бы числа записаны словами. Так, «10Base-T», например, должно быть расположено после «TCP/IP» и перед «time offset» (по-английски 10 – ten, прим. пер.).
Ставьте большие буквы только в тех словах – таких, как Ethernet, например – которые патентованы или должны писаться с большой буквы по другой причине.
Не давайте определения для акронимов и аббревиатур. Вместо этого расшифруйте акроним или аббревиатуру в полный термин и сделайте ссылку к полному термину и определению. Например:
Как составлять глоссарии (часть 1)
07.10.2013
Глоссарии может быть очень сложно составлять, в основном, потому что некоторые определения требуют слишком серьёзного исследования. Тогда как многие определения можно найти онлайн, с другими так не получится. Для них вы должны будете прочитать стандарты, Рабочие предложения (RFC) и книги – куча работы для определения на три или четыре строки!
Не просите специалистов-экспертов (SME) дать определения для глоссария. Во-первых, они спросят вас, зачем давать определение специфическому термину; во-вторых, они попробуют убедить вас в том, что вам не нужно определять термин; в-третьих, они расскажут вам, что все знают, что значит термин. Наконец, после того, как вы вежливо заверите их в том, что вы собираетесь дать ему определение, независимо от того, нравится им это или нет, они окажутся неспособны собрать все свои знания о термине в краткое определение.
Соблазнительно скопировать и вставить определение из онлайн-словаря в свой глоссарий (кто узнает?), но, пожалуйста, не делайте этого. Помимо того факта, что это очень, очень, очень плохо – заниматься плагиатом, некоторые из тех определений написано не сильно хорошо, а некоторые даже неверны. Лучше собрать столько определений, сколько можно и переписать их своими словами.
Редактирование собственного документа
04.10.2013
Данная заметка посвящена тому, каким образом можно редактировать документы, которые вы сами и писали.
Технические писатели подчас заблуждаются в том, что пользователь глуп. Я часто слышу, как технические писатели говорят нечто вроде «ну, если пользователь этого не может понять, то, возможно, он не на той работе!»
Моё же мнение заключается в том, что пользователи не должны ничего понимать. Они читают нашу документацию не для развлечения, и не для того, чтобы расширить собственное сознание, или улучшить свою способность мыслить. На самом деле пользователи вообще бы не читали нашу документацию. Техническая документация – это обычно не более, чем необходимое зло, что-то, что требуется пользователю, чтобы справиться с задачей так быстро и безболезненно, насколько это возможно. Наша работа – создать документацию простой и безболезненной для чтения. Она никогда не должна вызывать моменты замешательства, стресса, беспокойства или раздражения. Пользователь не должен никогда говорить «чего?»
Основная причина непонимания пользователя – небрежное писательство. Вы можете подумать, что это очевидно, но на самом деле я периодически вижу руководства пользователей, в которых есть орфографические, грамматические и пунктуационные ошибки, пробелы в логике, двусмысленности, пропущенные слова, неправильные термины, а также необычное форматирование, которые затрудняет навигацию. Даже лучшие писатели допускают временами такие ошибки.
Эксперты без купюр
02.10.2013
Представляем статью американского эксперта по документированию, посвящённую его личному опыту общения с экспертами, с которыми приходится работать каждому профессиональному техническому писателю.
Допускаю, что я не всё знаю о специалистах-экспертах, или SME. Но я точно знаю, что есть некоторые вещи, которые вы должны избегать спрашивать у экспертов, особенно «Пользователь это уже знает?» и «Должен ли я объяснить это пользователю?»
Проблема с этими вопросами заключается в том, что т.к. эксперты склонны верить, что все знают столько же о технологиях, сколько они, то они обычно отвечают «Да!» на первый вопрос и «Нет!» на второй, а на самом деле всё должно быть наоборот. Метод технического писательства: Нет, пользователь ещё этого не знает и да, вы должны объяснить это пользователю.