%D0%9A%D0%B0%D0%BA %D0%BF%D1%80%D0%BE%D1%81%D0%B8%D1%82%D1%8C %D0%BE %D0%BF%D0%BE%D0%BC%D0%BE%D1%89%D0%B8 %D1%87%D1%82%D0%BE%D0%B1%D1%8B %D1%82%D0%B5%D0%B1%D1%8F %D0%BF%D0%BE%D0%BD%D1%8F%D0%BB%D0%B8 %D0%B8 %D0%BF%D0%BE%D0%BC%D0%BE%D0%B3%D0%BB%D0%B8 - atls/convention GitHub Wiki

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

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

Матфея 7:12

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

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

• Имеет ли вопрос смысл?
• Ясно ли, о чем тебя спрашивают?
• Легко ли его читать и понимать?
• Есть ли какие-то очевидные области, о которых тебе следовало бы спросить, прежде чем давать ответ?

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

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

• Что ты ожидаешь от этого?
• Чего пытаешься достичь?
• Что ты уже пробовал?
• Что произошло в этих попытках?

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

Если это возможно, напиши в начале вопроса своего рода «резюме», а затем более подробное описание.

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

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

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

Для этого обязательно нужно сделать:

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

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

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

А также пользуйся рекомендациями ниже:

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

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

• Пиши реальные слова. Несомненно, существуют некоторые сокращения, которые приемлемы для большинства читателей - IMO, IIRC и т.д. - нет причин переходить на текстовую речь с "gr8", "bcoz", "u" и так далее. Маловероятно, что ты пишешь свой вопрос на телефоне с примитивной клавиатурой. Прояви уважение к читателям, написав правильно. Возможно, это займет у тебя на несколько секунд больше времени, но если ты быстрее получишь ответ, то несомненно, это стоит дополнительных усилий

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

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

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

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

Например, вот так:

Почему я не могу преобразовать выражение типа List<string> в List<object>?

Не имеет никакого смысла, если убрать аргументы типа:

Почему я не могу преобразовать выражение типа List в List?

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

У нас есть примеры как делать нужно и как делать не нужно. Эта секция будет дополняться.

Наглядный пример как хорошо подано, довольно много информации по проблеме. Здесь есть четко разделенные секции: Описание, Материалы Вопрос. Указана причина (была найдена), есть текст с описанием того, как воспроизвести проблему и очень много контекста.

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

Не понятно о какой папке data идёт речь и что в ней находится, так как манипуляции с ней явным образом аффектят работу окружения. Логи предоставлены изображением, при этом в логах пусто Отсутствует информация об окружении - ни версии ноды, ни ярна Нет ссылки ни на коммит ни на ПР.