Введение

Книга рецептов vs Руководство

Чем книга рецептов отличается от раздела «Руководство»? В чем её необходимость?

• Бо́льший фокус: В руководстве мы, по сути, рассказываем историю. Каждый раздел основывается на знаниях из предыдущего. В книге рецептов, каждый рецепт может и должен быть независимым. Это значит, что каждый рецепт может сосредоточиться на каком-то одном, конкретном аспекте Vue, а не на том, чтобы предоставить общий обзор.

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

• Изучение JavaScript: В руководстве мы предполагаем, что вы знакомы с JavaScript ES5. Например, мы не будем объяснять, как Array.prototype.filter работает в вычисляемом свойстве, которое фильтрует список. Однако, в книге рецептов основные возможности JavaScript (включая ES6/2015+) можно изучить и объяснить в контексте того, как они помогают нам создавать лучшие приложения Vue.

• Изучение экосистемы: Для продвинутых возможностей предполагается, что у вас есть некоторые знания об экосистеме. Например, если вы хотите использовать однофайловые компоненты с Webpack, мы не станем объяснять как настраивается Webpack. В книге рецептов у нас есть пространство для изучения экосистемы различных библиотек подробнее — по крайней мере, в том виде, в котором это будет полезно для разработчиков Vue.

Обратите внимание, что при всех этих отличиях книга рецептов не является пошаговым руководством. Предполагается, что для большей части содержимого у вас должны быть базовые знания о таких понятиях как HTML, CSS, JavaScript, npm/yarn, и т.д.

Участие в книге рецептов

Что мы ищем

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

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

Рецепт в целом должен:

• Решать конкретную распространённую проблему
• Начинаться с простейшего примера
• Постепенно увеличивать сложность
• Ссылаться на другие документы, вместо повторного объяснения
• Чётко описывать проблему, а не рассчитывать на осведомлённость
• Объяснять процесс, а не конечный результат
• Описывать плюсы и минусы вашего подхода, в том числе случаи, когда он не уместен
• Упомянуть альтернативные решения, если они есть, но описывать подробности в отдельном рецепте

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

Простой пример

обязательно

1. Опишите проблему парой предложений.
2. Объясните простое доступное решение.
3. Покажите небольшой пример кода.
4. Объясните, что выполняет данный код.

Подробная информация

обязательно

1. Обращайтесь к общим вопросам, которые могут возникнуть при просмотре примера (отлично подходят цитаты).
2. Покажите примеры распространённых ошибок и как можно их избежать.
3. Покажите примеры кода с использованием хороших и плохих практик.
4. Обсудите, почему это может быть подходящим шаблоном. Ссылки для справки не требуются, но поощряются.

Реальный пример

обязательно

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

1. Описания кратких примеров настройки
2. Предоставления примера на codepen/jsfiddle

Если вы решите сделать последнее, вы всё равно должны описать, что это и как это работает.

Дополнительно

опционально

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

Когда избегать этого шаблона

опционально

Хоть этот раздел необязательный, но настоятельно рекомендуется его добавлять. Нет смысла писать его для чего-то очень простого, например, для переключения классов, основанных на изменении состояния, но для более продвинутых шаблонов, таких как примеси, это жизненно необходимо. Ответ на большинство вопросов разработки — [«Как посмотреть!»] (https://codepen.io/rachsmith/pen/YweZbG), этот раздел предназначен для этого. Здесь мы будем честно смотреть, когда шаблон полезен и когда его следует избегать, или когда что-то ещё имеет смысл.

Альтернативные варианты

обязательно

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

Спасибо

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