И почему StackOverflow получает от этого прибыль.

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

(Мне очень нравится эта техника допроса "5 причин"! Моя версия несколько глупая 😁 , но я рекомендую попробовать эту технику.)

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

Представьте себе следующий сценарий.

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

Вы довольны своей работой, потребовалась большая координация между отделами. Вы поговорили с DevOps, вы поговорили с Product, вы поговорили со старшими инженерами, вы позаботились обо всех проблемах. Ваш PR, несомненно, будет быстро одобрен. Однако остается сделать одно: вы должны рассказать всем об этом новом способе написания команд. Как ты это делаешь?

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

Все,

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

Спасибо,

Me

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

Но вы уверены, что все готово?

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

Почему никто не читает твои письма

Давайте поменяем точки зрения.

Теперь вы другой разработчик. Еще четверг, четвертый день вашего недельного спринта. У вас остался 1 незавершенный билет. По правде говоря, вы решили и этот последний билет, но надоедливые сквозные тесты терпят неудачу. Вы смотрели на неудачные тесты в течение 1 часа, пытаясь выяснить, как ваше изменение могло вызвать это, возможно, тесты просто ненадежные. Стоит ли вам потратить немного времени и сделать их стабильными? У тебя вообще есть время? Завтра предстоит важная встреча, к которой тебе следует начать готовиться. Хм… о, смотрите, пришло письмо.

Что будет теперь? Прочтет ли этот второй разработчик нашу электронную почту? Прочтет ли она его внимательно?

Конечно, нет.

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

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

Лучшее электронное сообщение

Надо было начать с инструкций. Сначала TL; DR, потом объяснение:

Все,

Пожалуйста, прочтите следующие документы: http: // ....

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

Спасибо,

Me

Поначалу такой стиль письма кажется неестественным. Интуитивно мы сначала объясняли ситуацию, а затем просили людей действовать. Но мы все ежедневно получаем сообщения. Недавно я понял, что мне платят за чтение. Я читаю электронные письма, блоги, документы, спецификации, Slack, Confluence, JIRA, 15five,… Всегда есть что почитать. Логическое следствие - беглый просмотр всего текста. Мы больше не читаем, мы просматриваем в поисках релевантности.

Знайте свою аудиторию. Потому что они будут только беглыми, актуальными и лаконичными.

Какова была бы реакция на приведенное выше сокращенное письмо? Я предполагаю, что 70% его получателей просмотрели бы его, а 20% прочитали бы документы.

Это все? Мы старались изо всех сил? Это лучший из возможных исходов?

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

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

Сообщения секретного агента

Во-первых, нам нужно четко понимать, чего мы хотим достичь. Чего мы на самом деле хотим? Мы хотим, чтобы все будущие команды писались «по-новому».

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

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

Кому нужно будет знать о новом способе написания команд?

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

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

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

Если вы выполните поиск по запросу «команда» в документации, найдете ли вы документы о старом подходе? Измени это. В документах необходимо указать новый подход, удалить старые документы, если это возможно, или добавить большие жирные знаки «Устарело».

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

Оставьте панировочные сухари везде!

Архетип

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

Некоторое время назад я искал инструмент для рисования Git-history. Я наткнулся на GitGraphJS и его потрясающие документы:

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

Печально известный Webpack

Webpack, как известно, сложно настроить и понять. Какую проблему это вообще решает?

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

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

Но, может быть, я несправедлив к Webpack, может быть, Webpack делает такие сложные вещи, что их просто невозможно объяснить. Тот, кто когда-либо использует Webpack, должен просто потратить эти 1–6 месяцев на обучение, прежде чем он сможет продолжить работу над своим собственным проектом. Но опять же, кто эти люди, которым нужно будет вкладывать значительное количество времени в Webpack?

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

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

Одна из таких библиотек-оболочек - Laravel Mix. Чтобы настроить и использовать Laravel Mix, достаточно прочитать его краткое руководство из 350 слов. Попробовала, работает! Документации больше, вы можете углубиться во многие темы, но вам это не нужно, и в этом суть.

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

FAQ, аутсайдер

Почему Stack Overflow так популярен? Потому что большая часть документации не отвечает на вопросы.

Когда у вас есть проблема, как часто вы проверяете официальную документацию и как часто проверяете случайные блоги или переполнение стека? Я должен доверять официальной документации любого продукта больше, чем случайному сообщению в блоге от случайного человека / бота (?) В Интернете. Но я не могу, потому что в документации так редко объясняются наиболее распространенные варианты использования.

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

Обращение ко всем авторам документов

Всем вам, будущим авторам документации. Пожалуйста,

  • напишите короткую и длинную версии ваших документов (раздел tl; dr приветствуется)
  • учитывайте пользовательский опыт ваших читателей
  • включить раздел часто задаваемых вопросов и со временем расширять его.

Спасибо! Мы отплатим вам лайками, репостами и подписками, а также клонированием вашего подхода.

Внешние источники: