Как стать техническим писателем

Перевод статьи Ады Ндука Ойом «On Becoming a Technical Writer».

Одна из моих многочисленных примеров для подражания однажды рассказала о причине, по которой она занялась техническим писательством. Для нее это был способ зафиксировать изученное и описать свои находки на пути развития как разработчика программного обеспечения. Также это должно было помочь ей в тех случаях, когда она “терялась, встретив снова ту же самую проблему/баг”.

Писательство является прекрасным способом обучения окружающих, объяснения и разбора логических умозаключений. Но помимо этого оно позволяет вам проявлять свое творческое начало без необходимости выхода на сцену и без связанного с этим стресса.

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

Навыки

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

Хорошие навыки письма и коммуникации

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

Технический опыт / навыки, имеющие отношение к отрасли

Поскольку передача смысла подразумевает понимание и владение предметом статьи, обязательными являются знания и опыт в той сфере, о которой вы пишете. Это подразумевает, что вы в данное время работаете в данной сфере или знаете ее, как свои пять пальцев. Многие технические писатели занимают технические должности в своей отрасли, например, разработчики ПО/инженеры, аналитики по информационной безопасности и т.п. Писательство в сфере, с которой вы хорошо знакомы, имеет большое значение для выпуска прекрасной статьи.

Интерес

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

Навыки поиска

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

Процесс

Написание технической статьи может сильно отличаться от написания обычного рассказа и занять довольно продолжительное время, поскольку в большинстве случаев требует воспроизведения как простых, так и сложных технических шагов для достижения вашей цели. Поэтому, чтобы не допускать существенных изъянов в вашей статье, всегда стоит предпринимать следующие шаги до и во время ее написания.

1. Знакомство с аудиторией.

Технический писатель всегда в первую очередь думает о своем читателе. Знание, для какой категории читателей вы пишете, имеет большое значение для облегчения оставшихся задач. Если при написании статьи для новичков вы будете использовать незнакомые им термины и/или сложный технический язык, это плохо отразится на передаче им смысла сообщения. Ваша аудитория определяет освещаемые темы и стиль подачи информации. Чтобы лучше познакомиться со своей аудиторией, прежде чем приступить к написанию статьи, задумайтесь над следующими вопросами:

• Кто они?
• Что им нужно (узнать из вашей статьи)?
• Где они будут читать вашу статью?
• Почему они будут ее читать?
• Как они будут читать?

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

2. Распланируйте свою статью

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

3. Повторный просмотр

Ни один писатель не является горой знаний, потому ревью и отзывы в техническом писательстве поощряются точно так же, как и среди специалистов в технологиях.

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

4. Креативность контента

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

Выбор слов

Подбирайте слова и включайте побольше деталей, где это необходимо: это сделает вашу статью более понятной.

Пример: Открыть командную строку и выполнить действия XYZ в директории «Документы».

Лучше так: Откройте командную строку, перейдите в директорию «Документы», напечатав «cd Документы», а затем выполните действия XYZ.

Постоянно используйте активный залог

Активный залог в текстах гораздо легче для чтения и понимания, чем пассивный.

Пример: Больше 35 тысяч пакетов содержится в реестре пакетов Node.js npm.

Лучше: Реестр пакетов Node.js npm содержит больше 35 тысяч пакетов.

Структура предложений

Большое значение имеет помещение важной информации в первом предложении.

Пример: Всегда рекомендуется делать бэкап перед осуществлением обновления базы данных. Если вы не будете этого придерживаться, то велика вероятность потери данных.

Лучше: Чтобы избежать потери данных рекомендуется делать бэкап перед осуществлением обновления базы данных.

Избегайте технического сленга/сокращений/жаргона

Довольно легко погрузиться в написание статьи с головой и незаметно для себя начать использовать сокращения, сленг и жаргонизмы, знакомые нам и ограниченному кругу наших друзей или коллег. Если вы пишете статью и намерены использовать незнакомые термины, лучше всего сначала дать их полное определение, а затем использовать сокращения. Не нужно прыгать с места в карьер, оставляя свою аудитории в неведении.

Пример: Шаблон MVC принимается различными фреймворками.

Лучше: Шаблон Model-View-Controller (MVC) принимается различными фреймворками.

Применяйте подход, основанный на выполнении отдельных задач

Большинство технических статей имеют форму руководства для читателя или «сделай сам», поэтому написание вашей статьи в виде шагов может сделать ее более понятной. Проверьте очередность шагов, чтобы ваше повествование было плавным.

Преимущества

В том чтобы быть техническим писателем есть свои преимущества. Например:

1. Постоянное обучение – поскольку вы постоянно старайтесь поспевать за новыми технологиями, улучшать свои навыки чтения и письма, погружаться в новые глубины и получать обратную связь. Это рост все выше и выше.
2. Это ценный и прибыльный навык, поскольку каждый, кому хорошо удается доносить до пользователей технические сложности простыми словами, представляет ценность для организаций. И чтобы получить такого сотрудника, компании всегда готовы щедро платить.
3. Для людей, работающих в сфере технологий, это дополнительный набор навыков, который может содействовать карьерному росту. Связано это с тем, что их начинают воспринимать как способных быстро схватывать и доносить пользователю важность технологии и то, как ее использовать.

Желаем вам удачи в написании технических статей!

[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]