Техническое письмо для разработчиков

HTML, CSS, JavaScript, Python, PHP, C++, Dart — существует так много языков программирования, что вы даже можете совершенно свободно владеть некоторыми из них! Но по мере того, как мы стремимся писать больше и лучше кода, то, как мы пишем и общаемся на повседневном языке, становится все более и более важным… и, возможно, даже игнорируется.

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

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

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

Техническое письмо повсюду

В прошлом году команда разработчиков популярного клиента Mac Git, Tower, опросили более 4,000 разработчиков и обнаружили, что почти 50% из них тратят от 3 до 6 часов в день на написание кода.

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

Это может включать:

• демонстрация новой функции,
• документирование этой новой функции,
• обновление рабочего билета, связанного с этой новой функцией, или
• отложенная работа для поддержки этой новой функции.

Конечно, всегда есть время для перерывов в ванной и Wordle тоже.

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

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

Это техническое письмо 101.

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

Что такое хорошая грамматика?

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

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

Позвольте мне дать вам краткое изложение языка.

Английский синтаксис

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

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

Подумайте об этом как UI компоненты: это модульные части, которые вы можете перемещать, чтобы построить законченное и надежное предложение, точно так же, как вы могли бы собрать воедино законченное и надежное предложение. UI. Все ли компоненты должны быть там все время? Конечно нет! Соберите предложение из частей, необходимых для завершения опыта, так же, как вы делаете это с интерфейсом.

Голос и тон

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

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

1. Мне нравится программировать.
2. I такое как программирование! :)

Легко спутать голос с тоном и наоборот.

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

Одно и то же сообщение, написанное двумя разными голосами:

• Развлечения: «Расширьте свою социальную сеть и будьте в курсе того, что сейчас в тренде».
• Серьезный: «Найдите работу в одном из крупнейших приложений для социальных сетей и на онлайн-рынке вакансий».

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

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

Активный и пассивный голос

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

Актер занимает первое место в активный залог. Например: «CSS рисует фон».

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

С пассивный залог, актер идет последним. (Видите, что я там сделал?) Это означает, что наш актор — в данном случае CSS — приходит в конце так: «Фон рисуется с помощью CSS».

Читатели обычно преобразуют пассивный залог в активный в своей голове, что приводит к увеличению времени обработки. Если вы когда-либо слышали, что писать в активном залоге лучше, обычно это и есть причина. Технические писатели в большинстве случаев предпочитают активный залог, за очень немногими исключениями, такими как цитирование исследований: «Было высказано предположение, что…»

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

Как избежать ошибок

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

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

Но если вы ищете универсальный инструмент для изучения грамматики на все случаи жизни, Grammarly является одним из наиболее широко используемых инструментов. Я не получаю откат за это или что-то еще. Это просто отличный инструмент, который многие редакторы и писатели используют для написания чистого и ясного контента — аналогично тому, как вы можете использовать Emmet, eslint или любой другой линтер для написания чистого и понятного кода.

Написание комментариев к коду

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

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

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

Вместо этого используйте комментарии, предоставляющие дополнительную информацию:

red *= 1.2 // Apply a 'reddish' effect to the image

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

Комментарии должны добавлять ценность

Прежде чем мы рассмотрим, что делает комментарий кода «хорошим», вот два примера ленивых комментариев:

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

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

Комментарии должны отражать текущий код

Устаревшие комментарии — не редкость в крупных проектах; осмелюсь сказать в самых проектов.

Давайте представим Дэвида, программиста и классного парня, с которым приятно проводить время. Дэвид хочет отсортировать список строк в алфавитном порядке от А до Я, поэтому он делает очевидное в JavaScript:

cities = sortWords(cities) // sort cities from A to Z

Затем Дэвид понимает, что sortWords() на самом деле сортирует списки от Z до A. Это не проблема, поскольку он может просто инвертировать вывод:

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

К сожалению, Дэвид не обновил свой комментарий к коду.

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

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

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

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

Комментарии должны объяснять унидиоматический код

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

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

Это полезно, верно? Если вы отвечали за проверку этого кода, у вас могло возникнуть искушение исправить его без комментария, объясняющего, в чем дело.

Комментарии могут идентифицировать будущие задачи

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

// TODO: use a more efficient algorithm
linearSort(ids)

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

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

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

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

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

Написание пулл-реквестов

Запросы на вытягивание (PRs) являются фундаментальным аспектом любого проекта. Они лежат в основе код-ревью. А проверка кода может быстро стать узким местом в работе вашей команды без хорошей формулировки.

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

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

Избегайте расплывчатых PR позиций

Пожалуйста, избегайте заголовков, которые выглядят так:

• Исправить сборку.
• Исправить ошибку.
• Добавьте патч.

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

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

Вот несколько хороших примеров:

• Поддержка пользовательских атрибутов srcset в NgOptimizedImage
• Конфигурация изображения по умолчанию для качества изображения 75%
• Добавьте явные селекторы для всех встроенных ControlValueAccessors.

Избегайте длинных PRs

Большой PR означает огромное описание, и никто не хочет просматривать сотни или тысячи строк кода, иногда просто для того, чтобы в конечном итоге отбросить все это!

Вместо этого вы можете:

• общаться с командой через Темы,
• Составьте план,
• разбить проблему на более мелкие части или
• работать над каждым произведением отдельно своим PR.

Разве сейчас не намного чище?

Сообщите подробности в PR тело

В отличие от PR название, тело домен место для всех деталей, в том числе:

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

Сообщение об ошибках

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

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

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

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

Собирать скриншоты

Зафиксируйте проблему с помощью системная утилита для съемки экрана.

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

Возможно, вам потребуется записать фактическое взаимодействие, чтобы продемонстрировать проблему. Если это так, попробуйте записывать GIF-файлы с помощью инструмента для записи экрана.

Как воспроизвести проблему

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

Рассмотрим пример:

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

Предложить причину

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

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

Общение с клиентами

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

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

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

Задайте правильные вопросы

Начните с того, что убедитесь, что вы и клиент находитесь на одной странице:

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

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

• Согласны ли вы с этим, даже если это связано с дополнительными затратами на производительность?
• Помогает ли перемещение компонента нам лучше достичь нашей цели?
• Отлично, а кто будет поддерживать это после запуска? 
• Знаете ли вы навскидку, соответствует ли контраст между этими двумя цветами стандартам WCAG AA?

Вопросы гораздо более невинны и поощряют любопытство, а не враждебность.

Продать себя

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

• Кто ты
• Что ты делаешь
• Почему вы подходите для этой работы
• Ссылки на соответствующую работу, которую вы сделали

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

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

Написание микрокопии

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

Возможно, поэтому мы иногда видим такие ошибки:

Error: Unexpected input (Code 693)

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

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

Большинство людей не знают, что такое сервер, в то время как 100% программистов знают. Вот почему нередко можно увидеть необычные термины, написанные в сообщении об ошибке, например API или «исполнение тайм-аута».

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

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

Никогда не обвиняйте пользователя

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

Несмотря на то, что мысль о том, что это сообщение является враждебным, кажется драматичной, я подсознательно чувствую себя глупо. Микрокопия говорит, что нельзя винить пользователя. Попробуйте изменить свое сообщение на что-то менее прямолинейное, как этот пример, адаптированный из логина Mailchimp: «Извините, эта комбинация электронной почты и пароля неверна. Мы можем помочь вам восстановить вашу учетную запись».

Я также хотел бы добавить, что важно избегать ВСЕХ ЗАГЛАВНЫХ и восклицательных знаков! Конечно, их можно использовать для передачи волнения, но в микротексте они создают ощущение враждебности по отношению к пользователю.

Не перегружайте пользователя

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

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

Mailchimp говорит об этом хорошо:

[D] не изо всех сил шутите — вынужденный юмор может быть хуже, чем его полное отсутствие. Если вы не уверены, сохраняйте серьезное лицо.

(Акцент мой)

Написание доступной разметки

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

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

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

Вещи как:

Энди Белл предлагает несколько относительно маленькие вещи, которые вы можете сделать, чтобы сделать контент более доступным, и это стоит вашего времени, чтобы проверить их. И, просто для пинков, Джон Рея демонстрирует несколько изящных приемов редактирования это возможно, когда мы работаем с семантическими элементами HTML.

Заключение

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

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

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

Если вас интересует техническое письмо:

Если вас интересует копирайтинг:

Если вас интересует микрокопия:

Если вы заинтересованы в использовании профессионального руководства по стилю для улучшения своего письма:

Если вы заинтересованы в написании для доступности: