Как описать свою техническую проблему

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

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

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

Это поможет вам понять проблему

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

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

• контекст, в котором это происходит
• что привело вас сюда
• что вы пробовали до сих пор.

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

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

Это неизбежно, если вы собираетесь работать в этой отрасли.

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

Вам это понадобится, чтобы попросить о помощи

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

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

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

Вам придется обращаться с запросами в другие проекты

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

Вам придется объяснять компромиссы

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

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

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

Вам придется сообщать об ошибках

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

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

Форма для заполнения

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

Чего вы пытаетесь достичь

Главный вопрос — какова ваша цель? Он служит двум целям:

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

Что вы делаете & чего вы ожидаете

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

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

Что вы получаете

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

Как это можно объяснить

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

Пример

Как может выглядеть такое описание?

Я вычисляю общую площадь нескольких квадратов по массиву длин их сторон.

Мой расчет выглядит следующим образом:

const sizeList = [1, 2, 4];

const totalSize = sizeList.reduce((value) => {
  value *= value;
}, 0);

Я ожидаю, что после вычисления totalSize будет равен 21, но вместо этого я получаю undefined.

Я понятия не имею, что здесь происходит. Я проверяю документацию по reduce, и буквально делаю то же самое. Это либо мой браузер устарел — но, согласно caniuse, это не так. Либо мой код проклят.

Или

Я работаю над экраном настроек пользователя.

Я пытаюсь сохранить изменения, выполняя POST-запрос к /user/settings:

{“data”:{“roundPrices”: false}}

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

Это похоже на:

• бэкенд просто сломан
• API бэкенда был изменен, но документация не была обновлена.
• Я сделал что-то не так — в таком случае, приветствуется обратная связь с API.

Как вы можете использовать это описание

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

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

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

У вас есть готовый вопрос, который можно задать коллеге или наставнику

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

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

У вас есть данные для нового билета

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

Практика синтеза идей

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

Пишите. Это. Вниз.

Я повторюсь, чтобы избежать недопонимания — я говорю об упражнении по написанию; то есть, когда вы закончите, будет доступен какой-то текстовый вывод. Это не обдумывание проблемы и не мечтания о том, что вы могли бы написать.

Например, для такого текста, как этот, мне требуется около 2~3 часов от того, чтобы понять, что я хочу сказать, до того, чтобы получить текст, которым я могу поделиться. На что уходит так много времени? Собственно работа по прояснению и уточнению идей. Нет способа обойти это; единственными вариантами являются:

• сделать работу и получить результат
• оставить все незавершенным

Поделитесь этим в комментариях!

Хотите попробовать этот процесс? Опишите в комментариях свою текущую техническую проблему! Возможно, кто-то из читателей сможет ответить на ваш вопрос.