Публикации
А вы допускаете эти ошибки? (часть 3)
20.12.2013
Сегодня мы обратим ваше внимание на такую немаловажную деталь, как использование шаблонов при создании документации, о чём зачастую забывают даже опытные технические писатели.
Отсутствие шаблонов
Из множества компаний, с которыми я работал на протяжении многих лет, девять были достаточно крупными и давно работающими, чтобы разработать собственные шаблоны, но лишь две это сделали. Учитывая, как много времени (а в бизнесе время – деньги) экономит использование шаблона, меня очень удивляет, почему компании от них отказываются.
Многие думают, что шаблон включает только стиль абзацев в документе. На самом деле, хорошо продуманный шаблон содержит не только стили, но и макеты для каждого элемента страницы (заголовки, нижние и верхние колонтитулы, таблицы, абзацы, отступы, предупреждающие сообщения, сноски) и каждого элемента книги (передняя обложка, титульный лист, оглавление, главы, глоссарий, задняя обложка и т.д.). Все эти элементы требуют тщательного продумывания и больших временных затрат, а шаблон легко использовать писателям и легко читать пользователям.
А вы допускаете эти ошибки? (часть 2)
18.12.2013
Продолжаем серию статей, призванных помочь начинающим (и не только) техническим писателям оптимизировать работу и избежать самых распространённых ошибок.
Отсутствие плана нумерации документов.
По факту, большинство компаний нумеруют документы, но номера, как например CQZ3391-Y, зачастую бессмысленны. Одна из целей нумерации – максимально упростить своим коллегам процесс сборки продукта и отправки его покупателю, поэтому вам стоит создать план нумерации, который будет иметь смысл. Наиболее интуитивно понятный план нумерации – xxx-yyy-zzz, где:
Читать дальше…
А вы допускаете эти ошибки? (часть 1)
16.12.2013
Мы начинаем цикл статей, посвящённых вопросу возникновения ошибок при работе технического писателя и способах их устранения. Сегодня мы увидим описания четырёх самых распространённых ошибок.
Неопытные технические писатели, как правило, допускают ряд предотвращаемых ошибок, в том числе бездумное повторение за экспертом по предмету (ЭП) и жёсткие перекрёстные ссылки (x-ref). Вот описание ошибок, которых стоит избегать.
Непонимание продукта или приложения
Эта проблема имеет две формы. В первой эксперты по предмету пишут предварительную документацию, а затем писатель её только редактирует (это худший вид писателя и я предполагаю, что, если вы это читаете, то не относитесь к этому типу). Во втором случае писатель сам пишет документ, но при этом дословно цитирует эксперта. Технические писатели могут понять, что именно этим и занимаются, если вдруг обнаружат, что не совсем понимают то, что пишут…
Что делать со старыми инструкциями? (часть 2)
13.12.2013
Представляем вам продолжение письма Тома Джонсона, опубликованного в его блоге. Первая часть тут.
Чтение всех этих руководств неизменно начинается с поздравлений с покупкой продукта. Я уже писал об этих клише в статье Five Ways to Avoid the “Congratulations Clich?. Но теперь я вижу в таких приветствиях реальную цель. Всё, что хочет сказать технический писатель, – это «спасибо, что приобрели этот продукт, без вашей поддержки я остался бы без работы». Это код, который понятен только братству техписов. Как видите, у меня есть доступ к подобным тайнам. «Спасибо, спасибо, что наняли меня» – говорят они.
Я бы хотел, чтобы люди, которые создают инструкции по сборке устройств, добавляли в свои руководства немного юмора, чтобы немножко улучшить моё плохое отношение к сборке чего-либо вообще. Однажды я собирал пару двухъярусных кроватей из IKEA, а к ним шёл такой огромный пакет с гайками, что, клянусь, их туда насыпали лопатами.
Ненавязчивая шутка в начале руководства может неплохо помочь. Как насчёт «Пожалуйста, возьмите и взвесьте в руке здоровенный мешок гаек. Вашей первой мыслью будет: «Боже, сколько гаек!». Мы знаем, знаем, успокойтесь. Через пару часов всё закончится. Ну, если, конечно, вы отлично умеете работать руками. Шучу, наша инструкция вам поможет. Но на самом деле, не теряйте гайки. Вам понадобится все до единой 🙂 ».
Мы работаем и в Новый год!
11.12.2013
Бывают ситуации, когда проект нужно сдать срочно, например, сразу после праздников, или даже ещё до них. Многие проекты к Новому году не то, чтобы даже «горят», — они «полыхают», а мысли… совсем не об отдыхе. И продукт уже готов — не хватает лишь инструкции… Что же делать?
Решение есть!
Команда компании ПроТекст работает и на новогодних каникулах. Обращайтесь к нам, и мы выручим вас в непростой ситуации, подготовив необходимую документацию к сроку.
Желаем вам спокойного отдыха!
Что делать со старыми инструкциями? (часть 1)
Сегодня мы представим вам ответ технического писателя Тома Джонсона на вопрос одного из читателей своего блога.
Привет, Том!
А вы собираете руководства пользователя, листовки, памятки, инструкции и пр., если считаете их неплохим примером, и заимствуете ли оттуда некоторые идеи для вдохновения?
Могли бы вы сказать, что это хорошая тренировка для технического писателя? Как начинающий технический писатель, я считаю, что это действительно помогает, служа источником идей.
Инструкции к электронным гаджетам я храню всегда. Даже если продукта у меня уже нет.
Спасибо
Когда-то я хранил целую коробку инструкций от всевозможных устройств от бытовых приборов до электронного оборудования. То есть от всего, к чему прилагалась инструкция. И я почти никогда ими не пользовался, кроме, разве что, случаев, когда нужно было узнать номер модели, чтобы найти её в интернете. Тем не менее, это не значит, что, читая все эти руководства, вы не сможете почерпнуть что-то ценное.
Эджайл и технические коммуникации: эджайл-процесс глазами руководителя (часть 3)
09.12.2013
В заключительной части статьи речь идёт об эффекте, оказываемом эджайлом на технических писателей.
Воздействие на писателей
Временами фокус на преимуществах высокого уровня и потребностях бизнеса могут затенить отдельные особенности эджайл-процесса. На самом деле иногда команда инженеров (включая писателей) должна выбросить эджайл-процесс через окно, чтобы отвечать более крупным бизнес-потребностям. Также будут моменты, когда будет требоваться сократить процесс производства, и писатели не смогут сделать работу так, как считают должным.
Как могут писатели быть эффективными и успешными в эджайл-процессе, при этом не упуская из виду эти цели верхних уровней, поставленные руководством? Быть гибкими. Знать, что несмотря на то, что эджайл-процесс помогает интегрировать писателей в большую команду, будут моменты, когда ваша команда не будет следовать ему, как вы обычно делаете, и это нормально. Однако, будьте там, чтобы помочь так, как сможете. Научитесь не зацикливаться на мелочах. Иногда вам не требуется писать идеальную документацию. В таких случаях, когда большинство людей гуглят информацию о продукте, достаточно хорошая документация (или обрывочная документация в виде коротких видеороликов, объясняющих новые возможности) часто удовлетворяет всеобщим интересам более эффективно.
Эджайл и технические коммуникации: эджайл-процесс глазами руководителя (часть 2)
06.12.2013
Вторая часть статьи об эджайле с позиции руководителя посвящена, собственно, перечислению преимуществ для сотрудников, занимающих руководящие должности.
Преимущества эджайла для руководителей
Строго говоря, эджайл-процесс не покрывает неинженерные вопросы, касающиеся производства продукции, но руководители видят много преимуществ эджайла, которые помогают бизнесу в целом.
Наиболее очевидное преимущество эджайла – ускоренный процесс производства. Руководители могут легко продолжать сокращать короткие производственные циклы, потому что хотят ещё быстрее выпускать на рынок дополнительные функции, увеличивающие привлекательность продукта. Функции нового продукта с помощью правильного маркетинга переводятся в большее количество новых клиентов и в большие продажи – а это основная цель любого бизнеса. Даже если команда добилась только более быстрых выпусков пакетов обновлений, значит вы своевременно реагируете на проблемы клиента. Эта быстрая реакция делает существующих клиентов счастливыми, что ведёт к повторным заказам от этих клиентов.
Эджайл и технические коммуникации: эджайл-процесс глазами руководителя (часть 1)
04.12.2013
Сегодняшняя статья Алиссы Фокс посвящена технологии эджайл с позиции выгоды для руководителей предприятия. Первая часть статьи посвящена трудностям внедрения технологии эджайл в производственные процессы.
Если говорить о «самой чистой» форме этого процесса, эджайл-разработка втягивает в работу над пожеланиями пользователей посредством множества спринтов, пока их качество не станет достаточным для релиза чего-нибудь для ваших клиентов. Создание этих простых, независимых кусков производит потенциально готовый к отправке код в конце каждого спринта.
Этот процесс, если ему следовать, работает хорошо для тех, кто создаёт продукт и сопроводительную документацию к нему, но что на счёт оставшихся организаций? Как эджайл-процесс разработки вписывается во все производственные процессы? Видят ли руководители преимущества для организации и, в конечном счёте, для получаемого дохода?
Какой набор навыков важен для технического писателя?
02.12.2013
Статья об основных навыках, которыми должен обладать технический писатель, а также о том, как в него добавлялись новые навыки с течением времени.
Как и в случае с любой профессией, становление техническим писателем требует мастерства в определённом наборе навыков. В этот набор, с тех пор как объёмные инструкции для печатной публикации стали стандартом в профессии, обычно входили в качестве основных писательские навыки и способность иллюстрировать материал. Мир коммуникаций и технологий очень серьёзно развился во второй половине XX века и начале нынешнего. Как эта эволюция повлияла на набор навыков, необходимых техническому писателю?
- Писательские навыки. Для технического писателя писательские навыки никогда не могут быть недооценены. Технический писатель всегда должен писать ясно, лаконично и быть способным подать материал так, чтобы он соответствовал разной целевой аудитории.
- Технические навыки. Набор технических навыков технического писателя зависит в основном от того, какие требования предъявляют описываемый предмет, продукт или сервис, к которым требуется документация. Документация к «железу» или к программному обеспечению требуют различных навыков от технического писателя. К тому же, фармацевтика и другие производственные области имеют специфические требования, которые превращаются в знания, которыми обязан обладать технический писатель. Технический писатель, которого попросили написать гайд для разработчиков, должен быть «на ты» со специфическими языками программирования, тогда как технический писатель, задача которого – документирование в области оружейных защитных систем, должен иметь высокую степень компетенции в инженерных вопросах, так же, как и уверенные знания государственных стандартов документирования.