БЛОГ
Почему разработчики пишут ужасную документацию
28.10.2013
Сегодняшняя заметка Джеки Сэмюэлс (Jacquie Samuels), консультанта в области технических коммуникаций, DITA, CMS, посвящена причинам, по которым разработчики не должны писать документацию к собственным продуктам.
Мир разработки программного обеспечения может быть стремительно развивающимся и иногда приходится очень сильно напрягаться, чтобы успеть подготовить всё к релизу. Если у компании нет отработанного процесса или отдела технической документации, часто писать документацию на продукт просят разработчиков. Действительно, кто знает продукты так же хорошо, как они?
Даже авторитетная компания может сесть в лужу с документацией, написанной разработчиком. Например, одна компания, разрабатывающая программное обеспечение, обычно пропускающая контент через отдел документирования, напортачила на небольшом, быстром проекте, который был насколько спонтанным, что никто даже и не подумал сказать: «Хорошо бы сказать группе документирования, что ведётся работа над новым продуктом, потому что, знаешь, клиентам как бы нужна документация к продукту». За день до релиза они, наконец, сказали об этом и отправили какой-то разработанный самостоятельно ими контент на быструю вычитку техническим писателем (да, этим писателем была я) в плане правки оформления, орфографии и грамматики – больше времени ни на что не осталось. И в таком виде это отправилось клиенту.
У писателя Джорджа Сондерса выдался замечательный год
25.10.2013
У Джорджа Сондерса (George Saunders) пошла полоса удач.
Писатель и профессор английского языка в Сиракьюсском университете (Syracuse University) на прошлой неделе был признан финалистом Национальной книжной премии за его сборник коротких рассказов «Десятое декабря».
В январе в «Нью-Йорк таймс мэгэзин» (прим. пер.: New York Times Magazine — Воскресное приложение к газете «Нью-Йорк таймс») заголовок гласил: «Джорж Сондерс написал лучшую книгу из тех, что вы прочтёте в этом году».
В апреле он появился в журнале «Тайм» в списке «100 самых влиятельных людей». Автор и коллега по Сиракьюсскому университету Мэри Карр (Mary Karr), пишущая для журнала, назвала Сондерса «лучшим писателем на английском – не «одним из», не «возможно», а Лучшим».
Ранее, в этом месяце, Сондерс получил награду PEN/Malamud 2013 (прим. пер.: PEN – сокращение от International Association of Poets, Playwrights, Editors, Essayists, and Novelists – Международная ассоциация поэтов, драматургов, редакторов, очеркистов и писателей-прозаиков; Malamud Bernard (1914-1986) Маламуд Бернард, Писатель) за «собрание сочинений, которое демонстрирует непревзойдённое мастерство в искусстве написания коротких литературных произведений».
Как нанимать технического писателя (часть 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) дать определения для глоссария. Во-первых, они спросят вас, зачем давать определение специфическому термину; во-вторых, они попробуют убедить вас в том, что вам не нужно определять термин; в-третьих, они расскажут вам, что все знают, что значит термин. Наконец, после того, как вы вежливо заверите их в том, что вы собираетесь дать ему определение, независимо от того, нравится им это или нет, они окажутся неспособны собрать все свои знания о термине в краткое определение.
Соблазнительно скопировать и вставить определение из онлайн-словаря в свой глоссарий (кто узнает?), но, пожалуйста, не делайте этого. Помимо того факта, что это очень, очень, очень плохо – заниматься плагиатом, некоторые из тех определений написано не сильно хорошо, а некоторые даже неверны. Лучше собрать столько определений, сколько можно и переписать их своими словами.