Написание технических статей: ваша инженерная суперсила

Часть II

Написание технических статей: ваша инженерная суперсила

Как хорошо писать

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

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

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

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

Как вести блог

Хотя написание технического блога может показаться сложным, на самом деле есть всего два шага:

1. Выбрать тему.
2. Напиши об этом!

Хорошо, может быть, это не совсем так просто. Давайте разберемся в процессе.

Часто самая сложная задача, с которой вы сталкиваетесь при работе над техническим блогом, - это выбор темы. Одна из стратегий - подумать о чем-то небольшом, чему вы научились, или о концепции, которая недавно пришлась вам по вкусу. Подумайте о любом «ага!» моменты, которые у вас были. Другой вариант - это что-то сложное любого размера, на то, чтобы разобраться с которым вам потребовалось время. Если у вас был трудный день, когда вы пытались решить сложную проблему, если вы много гуглили и не нашли то, что искали, напишите ресурс, который вам нужен. Вы также можете найти вдохновение в своих профессиональных и личных проектах. Изложение того, как вы создали конкретную функцию или проект, станет отличным постом.

Имея тему в руках, вы почти готовы начать писать. Во-первых, вам нужно выбрать платформу для своего блога и настроить ее. Я обычно рекомендую разработчикам выбрать платформу, предназначенную для ведения блогов, например Medium или Dev.to, вместо того, чтобы создавать собственный блог с нуля, используя что-то вроде страниц GitHub и Jekyll. Написать блог - это достаточно сложно. Использование устоявшейся платформы для ведения блогов позволяет вам сосредоточиться на написании статей, а не на ведении блогового сайта.

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

• Сначала напишите план.
• Начните с подробного введения.
• Сначала напишите заключение.

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

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

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

Как написать запрос на слияние

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

• Описательное название.
• Объяснение что, почему и как.

____ Какую проблему решает код?

____ Зачем это решение?

____ Как код решает проблему?

• Дополнительно: все, от инструкций по использованию до информации о тестировании / QA.

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

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

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

Как написать билет

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

Хорошо написанный тикет или проблема GitHub дает ответы на вопросы:

• Какую проблему нужно решить и почему?
• Какую ценность приносит проект, выполняя эту работу?

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

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

Вот пример проблемы с GitHub, которую недавно разработала моя команда:

Опять же, детали не важны. Но вы можете видеть, что проблема имеет четкое название, описывающее, что необходимо сделать, и два ключевых раздела:

• Описание проблемы. Описывает почему нам нужно выполнить эту работу.
• Срок поставки. Точно описывает, что должно быть доставлено по завершении проблемы.

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

Как написать документ по техническому дизайну

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

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

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

Как просить о помощи

Независимо от того, пишете ли вы новую публикацию Stack Overflow или обращаетесь к коллеге за помощью в устранении ошибки, не забудьте быть конкретным. Разбейте проблему, ответив на следующие вопросы:

• Каково текущее поведение? Опишите возникшую ошибку.
• При каких обстоятельствах возникает такое поведение?
• Чем поведение отличается от ожидаемого?

Хотя легко (особенно когда вас расстроила серьезная ошибка) сказать что-то вроде: «Это не работает, когда вы так делаете», но такие расплывчатые утверждения не дают информации, которая нужна людям, чтобы помочь вам. Давайте разберем пример хорошей просьбы о помощи:

Начните с объяснения текущего поведения (ошибки):

Когда песня загружается, отображается индикатор выполнения, но когда песня завершает загрузку, индикатор выполнения не исчезает! Он остается навсегда (или пока мы не обновим страницу).

Затем объясните обстоятельства, при которых возникает ошибка:

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

Наконец, объясните почему это ошибка. Чем это отличается от того, что вы ожидаете?

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

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

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

Вы технический писатель

Итак, теперь, когда я напугал вас всей техникой, которую вы должны выполнять как разработчик, у меня для вас хорошие новости - вы уже являетесь техническим писателем! Вы уже общаетесь о коде в письменной форме почти каждый божий день. Независимо от того, открываете ли вы PR, приглашаете друга за помощью или составляете заявку Jira, вы оттачиваете свои технические навыки письма. Вы уже получаете достаточно практики в техническом письме, просто приходя сюда каждый день.

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

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

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

Если вам понравилась эта статья, ознакомьтесь с этой книгой Софи ДеБенедетто и Брюса Тейта, опубликованной The Pragmatic Bookshelf:

Вы можете сэкономить 35% на версии Programming Phoenix Liveview для электронных книг, введя промокод superpower_35 при оформлении заказа. Код действителен до 30 июля. Промокоды не действительны для предыдущих покупок.

Обязательно ознакомьтесь с обзором авторов Софи ДеБенадетто на DevTalk, где вы можете задать ей вопросы и выиграть бесплатный экземпляр ее книги: