Техническое письмо для начинающих - Руководство по основам ведения технических блогов

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

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

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

Содержание

В этой статье мы рассмотрим:

  • Что такое технический текст
  • Преимущества технического письма
  • Необходимые навыки технического писателя
  • Процесс технического написания
  • Платформы для публикации ваших статей
  • Курсы технического письма
  • Форумы и сообщества по техническому письму
  • Несколько замечательных технических писателей, которым стоит следовать
  • Заключительные слова и ссылки

Что такое техническое письмо?

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

А технический писатель - это тот, кто пишет эти инструкции, также известные как техническая документация или руководства. Это могут быть руководства пользователя, статьи онлайн-поддержки или внутренние документы для программистов / разработчиков API.

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

Преимущества технического письма

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

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

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

Вы также можете зарабатывать деньги как технический писатель, внося свой вклад в организации. Вот некоторые организации, которые платят вам за то, чтобы писать для них, например Smashing Magazine, AuthO, Twilio и Stack Overflow.

В дополнение ко всему этому вы можете вносить свой вклад в сообщества с открытым исходным кодом и участвовать в платных программах с открытым исходным кодом, таких как Google Season of Docs и Outreachy.

Вы также можете заняться написанием технических вопросов в качестве профессии на полную ставку - многим компаниям нужен кто-то с такими навыками.

Необходимые навыки технического писателя

Разберитесь в правильном английском

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

Умейте объяснять вещи ясно и просто

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

Чтобы быть хорошим учителем, вы должны проявлять чуткость, уметь преподавать или описывать термины способами, подходящими для вашей целевой аудитории.

Если вы не можете объяснить это шестилетнему ребенку, вы сами этого не понимаете. Альберт Эйнштейн

Обладать письменными навыками‌‌

Я считаю, что писателями создаются, а не рождаются. И вы можете научиться писать, только написав на самом деле.

Вы можете никогда не узнать, что у вас есть желание писать, пока не возьмете ручку за бумагу. И есть только один способ узнать, есть ли у вас письменные навыки, - это письмо.

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

И, конечно же, иметь некоторый опыт в технической сфере - огромное преимущество.

Процесс технического написания

Проанализируйте и поймите, кто ваши читатели

Самый важный фактор, который следует учитывать при написании технической статьи, - это ваша предполагаемая / ожидаемая аудитория. Это всегда должно быть в центре вашего внимания.

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

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

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

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

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

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

Чтобы понять своего читателя, прежде чем начать писать, задайте себе следующие вопросы:

  • Кто мои читатели?
  • Что им нужно?
  • Где они будут читать?
  • Когда они будут читать?
  • Почему они будут читать?
  • Как они будут читать?

Эти вопросы также помогут вам подумать об опыте читателя при чтении вашего письма, о чем мы поговорим сейчас подробнее.

Подумайте о пользовательском опыте

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

Теперь, когда вы знаете свою аудиторию и ее потребности, вспомните, как сам документ удовлетворяет их потребности. Так легко игнорировать то, как читатель на самом деле будет использовать документ.

Когда вы пишете, постоянно отступайте и просматривайте документ, как если бы вы читали. Спросите себя: доступно ли это? Как ваши читатели будут его использовать? Когда они будут его использовать? Легко ли ориентироваться?

Цель состоит в том, чтобы написать документ, который был бы полезен и пригоден для использования вашими читателями.

Спланируйте свой документ

Помня, кто ваши пользователи, вы можете концептуализировать и спланировать свой документ.

Этот процесс включает в себя ряд шагов, которые мы сейчас рассмотрим.

Проведите тщательное исследование по теме

Планируя свой документ, вы должны исследовать тему, о которой пишете. Есть множество ресурсов, которые вы можете использовать только в поиске Google, и получить более подробные сведения.

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

Как можно больше используйте Google, получайте факты и цифры из исследовательских журналов, книг или новостей и соберите как можно больше информации по своей теме. Затем вы можете начать делать набросок.

Сделайте набросок

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

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

Получите соответствующую графику / изображения

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

И вам будет намного проще писать, если вы будете держать эту графику под рукой.

Пишите в правильном стиле

Наконец-то можно начинать писать! Если вы выполнили все эти шаги, писать станет намного проще. Но вам все равно нужно убедиться, что ваш стиль письма подходит для технического документа.

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

Использовать активный голос

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

Активный залог означает, что субъект предложения активно выполняет действие глагола. Пассивные голоса означает , что субъект является получателем глагола действия .

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

А вот пример активного голоса : каждый веб-разработчик должен читать эту документацию 6 раз в год.

Тщательно выбирайте слова

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

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

Избегайте чрезмерного жаргона

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

Вам также следует избегать использования сокращений, которые вы ранее не объясняли.

Вот пример :

Менее ясно: PWA действительно считаются будущим мультиплатформенной разработки. Их доступность как на Android, так и на iOS делает их приложением будущего.

Улучшение: Прогрессивные веб-приложения (PWA) действительно будущее многоплатформенной разработки. Их доступность как для Android, так и для iOS делает PWA приложением будущего.

Используйте простой язык

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

Визуальное форматирование

Стену текста трудно читать. Даже самые четкие инструкции могут быть потеряны в документе с плохим визуальным представлением.

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

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

Людям также нравятся визуальные эффекты, поэтому помогает вставлять их в нужные места. Рассмотрим изображения ниже:

Во-первых, вот фрагмент блога без визуальных элементов:

Вот фрагмент того же блога, но с визуальными элементами:

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

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

Сделайте тщательный обзор

Хорошее письмо любого типа не должно содержать орфографических и грамматических ошибок. Эти ошибки могут показаться очевидными, но их не всегда легко обнаружить (особенно в объемных документах).

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

Существует ряд бесплатных инструментов, таких как Grammarly и приложение Hemingway, которые можно использовать для проверки грамматических и орфографических ошибок. Вы также можете поделиться черновиком своей статьи с кем-нибудь для проверки перед публикацией.

Где публиковать свои статьи

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

Dev.to - это сообщество тысяч технических специалистов, в котором писатели и читатели могут активно взаимодействовать и делиться идеями и ресурсами.

Hashnode - это моя платформа для ведения блогов с потрясающими привилегиями, такими как отображение настраиваемых доменов и интерактивное сообщество. Создать блог на этой платформе также легко и быстро.

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

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

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

У Hackernoon более 7000 авторов, и он может стать отличной платформой для вас, чтобы начать публиковать свои статьи для более чем 200000 ежедневных читателей в сообществе.

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

Курсы технического письма

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

Курс технического письма поможет вам разобраться во всем, что вам нужно изучить, а также придаст вам уверенности в себе, чтобы начать свое письменное путешествие.

Вот несколько курсов технического письма, которые вы можете посетить:

  • Курс технического письма Google (бесплатно)
  • Курс технического письма Udemy (платный)
  • Учебный курс по техническому написанию Hashnode (бесплатно)

Форумы и сообщества технического писателя

В одиночку мы можем сделать так мало, вместе мы можем сделать так много ~ Хелен Келлер

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

Вот несколько сообществ и форумов, к которым вы можете присоединиться:

  • Hashnode
  • Dev.to
  • Технический мир письма
  • Форум технических писателей
  • Напишите форум Документов

Некоторые удивительные технические писатели, которым нужно следовать

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

Это писатели, которых я уважаю и считаю виртуальными наставниками по написанию технических текстов. Иногда они бросают советы по написанию технических работ, которые я считаю полезными и на которых я многому научился.

Вот некоторые из этих авторов (с гиперссылками на их твиттер):

  • Куинси Ларсон
  • Эдидионг Асикпо
  • Каталиновая яма
  • Виктория Ло
  • Боладжи Айодеджи
  • Амрута Ранаде
  • Крис Бонгерс
  • Колби Фэйок

Заключительные слова

Вам не нужна степень технического писателя, чтобы начать выпускать технический контент. Вы можете начать писать в своем личном блоге и общедоступных репозиториях GitHub, одновременно создавая свое портфолио и получая практический опыт.

Действительно - просто начни писать.

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

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

Вы учитесь писать, читая и думая о том, как писатели создавали своих персонажей и придумывали свои рассказы. Если вы не читатель, даже не думайте о писательстве. - Жан М. Ауэль

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

Конечно, хорошие писатели - тоже ненасытные читатели. Если вы просматриваете часто читаемые или часто используемые документы, ваше собственное письмо определенно улучшится.

Не могу дождаться, чтобы увидеть ваши технические статьи!

Ссылки

Введение в техническое письмо‌‌

Как структурировать техническую статью‌‌

Понимание вашей аудитории, почему и как

‌‌ Шаблон технического письма

Я надеюсь, что это было полезно. Если да, подпишитесь на меня в Twitter и дайте мне знать!