Каковы ключевые навыки для нового технического писателя?

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

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

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

Чего следует избегать:

Я заметил, что многие разработчики программного обеспечения используют такие слова, как «тривиально», «очевидно» и другую неприятную лексику, когда пишут технические материалы. Это плохо. Вы не проводите математических доказательств; в технической связи нет КЭД. Никому нет дела до того, насколько вы умны или как легко вам было найти решение. Я дошел до того, что просто закрываю вкладку браузера, если вижу слишком много этого.

Перфекционизм – еще одна ловушка. Техническое письмо должно быть достаточно хорошим. Это не должно быть идеально. Ты не пытаешься быть Джеймсом Джойсом. Техническая коммуникация — это выполнение задачи, а не получение Пулитцеровской премии. (Не то чтобы вы не должны активно пытаться стать лучше в своем ремесле!)

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

Избегайте устройств, которые отвлекают от вашего сообщения. Если вы рассказываете кому-то, как настроить часы на его видеомагнитофоне (хе-хе), вам не нужно рассказывать это в форме истории. Мне смешно даже упоминать об этом, но я видел, как это делается (!).

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

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

Предполагая, что вы пишете другие вещи (то есть, предполагая, что у вас есть легкость письменного выражения), есть четыре навыка, которые нужно оттачивать, которые применимы ко всем техническим письмам.

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

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

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