イントロダクション

クックブックとガイド

クックブックはガイドとどう違うのでしょうか？なぜそれが必要なのでしょうか？

• よりフォーカスする: ガイドの中では、基本的にストーリーを語っています。それぞれのセクションは、前のセクションの知識を基にしています。クックブックにおいては、それぞれのレシピはそれ自体が独立しています。つまりレシピは、一般的な Vue の概要を説明するのではなく、Vue の特定の側面に焦点を当てることができます。

• より深くまで: ガイドは長くなりすぎず、それぞれの機能を理解していただくために、可能な限り簡単な例だけを掲載するようにしています。そして次に進みます。クックブックでは、興味深い方法で機能を組み合わせた、より複雑な例を含めることができます。それぞれレシピはまた、それらの例を完全に探求するために、必要なだけ長くて詳細なものにすることができます。

• JavaScript を教える: ガイドでは、少なくとも ES5 の JavaScript の中級程度の知識があることを前提としています。例えば、 Array.prototype.filter がリストをフィルタリングする計算プロパティでどのように動作するかは説明しません。しかし、クックブックでは、必須の JavaScript 機能 (ES6/2015+ を含む) を探索し、より良い Vue アプリケーションの構築にどのように役立つのかという文脈で説明します。

• エコシステムを探求する: 高度な機能については、ある程度のエコシステムの知識を前提としています。たとえば、Webpack でシングルファイルコンポーネントを使用したい場合、Webpack の confing についての Vue 以外の部分を設定する方法については説明しません。クックブックでは、少なくとも Vue 開発者にとって普遍的に有用な範囲でこれらのエコシステムライブラリをより深く探求するスペースがあります。

::: ヒント これらの違いはあるものの、クックブックはまだステップバイステップのマニュアルではないことに注意してください。その内容のほとんどは、HTML、CSS、JavaScript、npm/yarn などの概念を基本的に理解していることが求められます。

クックブックへの貢献

私たちが求めているもの

このクックブックでは、一般的なユースケースや興味深いユースケースを網羅した開発者向けのサンプルを提供したり、より複雑な細かい部分を段階的にに説明していきます。私たちの目標は、単純な入門的な例を超えて、より広く適用可能な概念を示すことと、アプローチの注意点を示すことです。

貢献に興味のある方は、 cookbook idea というタグの下にあなたのコンセプトを書いて issue を提出して、コラボレーションを開始してください。あなたのアイデアが承認されたら、以下のテンプレートにできるだけ従ってください。いくつかのセクションは必須であり、いくつかのセクションは任意です。数字の順番に従うことを強くお勧めしますが、必須ではありません。

レシピは一般的に:

• 特定の一般的な問題を解決しましょう。
• できるだけシンプルな例から始めましょう。
• 複雑なことは1つずつ紹介しましょう。
• 概念を再説明するのではなく、他のドキュメントにリンクしましょう。
• その問題に精通していると前提とするのではなく、問題点を説明しましょう。
• 最終的な結果だけではなく、プロセスを説明しましょう。
• 適切な場合とそうでない場合を含めて、戦略の長所と短所を説明しましょう。
• 関連性がある場合は、代替案に言及しますが、詳細な調査は別のレシピに任せましょう。

下記のテンプレートに従ってください。しかし、説明の分かりやすさや流れのために、どうしてもテンプレートから逸脱する必要がある場合もあると思います。いずれにしても、すべてのレシピでは、このパターンを使った選択のニュアンスを、できれば代替パターンのセクションで説明する必要があります。

基本的な例 必須

1. 問題を1文か2文で明確にしましょう。
2. 最も簡単な問題に対しての解答を1文か2文で説明しましょう。
3. 小さなコードサンプルを表示しましょう。
4. これが何を達成しているのかを文章で説明しましょう。

バリューの詳細 必須

1. 例を見ている間に持っているかもしれない一般的な質問に対処しましょう。(ブロッククオートはこれに最適です)
2. よくある間違いの例を示し、どのように避けることができるかを示しましょう。
3. 良いパターンと悪いパターンの非常にシンプルなコードサンプルを表示しましょう。
4. なぜこれが説得力のあるパターンなのか議論してください。参照用のリンクは必須ではありませんが、それをつけることを推奨します。

実際の例 必須

一般的なユースケースや興味深いユースケースを動かすコードを、以下のいずれかの方法で実行してください。

1. セットアップの簡潔な例をいくつか紹介する。または
2. codepen / jsfiddle の埋め込みの例

後者を選択した場合でも、それが何であり、何をするのかをディスカッションする必要があります。

追加の文脈 任意

このパターンについて、他のどこに適用されるのか、なぜそれがうまく機能するのか、そして、あなたがそうするように少しのコードを実行したり、ここでさらに読み物を人々に与えたりすることについて少し書くのは非常に有用です。

このパターンを回避するケース 任意

このセクションは必須ではありませんが、書くことを強くお勧めします。 状態変化に応じてクラスを切り替えるような非常に単純なものには意味がありませんが、mixins のようなより高度なパターンには不可欠です。開発に関するほとんどの質問に対する答えは ["It depends!"]](https://codepen.io/rachsmith/pen/YweZbG) であり、このセクションではそれを受け入れます。ここでは、そのパターンがどのような時に役立つのか、避けるべき時はどのような時なのか、他の何かがより意味を持つ時はどのような時なのかを率直に見ていきましょう。

代替パターン 必須 回避のセクションに付随する

このセクションは、上記の回避についてのセクションを提供した場合に必要となります。特定の状況で何かがアンチパターンだと言われても、疑問を残さないように、他の方法を模索することが重要です。その際には、ウェブは大きなテントであり、多くの人が異なるコードベースの構造を持ち、異なる目標を解決していることを考慮してください。アプリの規模は大きいのか小さいのか？既存のプロジェクトに Vue を統合しているのか、それともゼロから構築しているのか。ユーザーは1つの目標だけを達成しようとしているのか、それとも多くの目標を達成しようとしているのか？非同期データが多いのか？これらの懸念事項はすべて、代替の実装に影響を与えます。良いクックブックのレシピは、開発者にこのような状況を提供します。

謝辞

ドキュメンテーションに貢献するには時間がかかりますが、この部分に時間をかけてプルリクエストを提出してくれると、感謝の気持ちを込めてやってくれます。