はじめに
最終更新日: 2020年5月16日
⚠️注意: クックブックは随時追加されます。このため、一部のセクションでは未翻訳の箇所があります。現在翻訳作業中一覧はこちらです。作業中の記事についてはしばらくお待ち下さい🙏。翻訳のお手伝いをしたい方は、こちらの翻訳ガイドをお読みください。
クックブックとガイドの違い
クックブックとガイドはどのように異なるのでしょうか？なぜクックブックが必要なのでしょうか？
より焦点を当てて: ガイドというものは、本質的にストーリーを伝えるものです。 各セクションは、前の各セクションの知識を元に成り立っています。 一方でこのクックブックは、各レシピが独立しています。つまり、これが意図することは、一般的な全体像を把握することより、むしろ各レシピが Vue の特定の側面に焦点を当てることができるということです。
より深く: ガイドでは説明が長くなることを避けるために、各機能を理解するのに役立つ最もかんたんな例を使用しています。 クックブックでは、より複雑な例を使用することで、興味深い方法で機能を組み合わせることができます。 それぞれのレシピは、その盲点を完全に学習するために、長くなる可能性もありますが必然的に詳細になります。
JavaScript の学習: ガイドでは、少なくとも ES5 JavaScript に精通している必要があります。 例えば、
Array.prototype.filterがリストをフィルタする算出プロパティでどのように動作するかは説明しません。 対してクックブックでは、JavaScript の重要な機能( ES6/2015+ を含む)を探求し、それがどのように良い Vue アプリケーションの構築に役立つか、ということについて説明します。エコシステムを学習する: 高度な機能については、エコシステムの知識を前提にしています。 例えば、 Webpack で単一ファイルコンポーネントを使用する場合、 Webpack config の Vue 以外の部分の設定については説明しません。 クックブックでは、そのままの場所でこれらのエコシステムやライブラリ群をより深く学習する余裕があります。 - 少なくとも、 Vue 開発者にとって一般的に有用な程度まで。
これらの違いとともに、クックブックはステップバイステップのマニュアル ではない 点に注意してください。その内容の大部分については、HTML や CSS、JavaScript、npm/yarn などについての基本的な知識があることを前提としています。
クックブックへの貢献
私たちが目指しているもの
クックブックは一般的なものや興味深いユースケースのどちらも進めるための具体例を開発者たちに提供し、より複雑な内容を徐々に説明していきます。私たちの目標は、簡単な入門例を超え、広く適用可能なコンセプトと、そのアプローチに対する注意点を実証することです。
貢献に興味があれば、 cookbook idea タグがついている Issue 上にあなたのコンセプトを提出することからコラボレーションを開始してください。私たちがプルリクエストが成功するようにお手伝いします。 あなたのアイディアが承認されたら、可能な限りテンプレートに従ってください。 一部のセクションは必須で、いくつかは任意です。 数値順にすることが強く推奨されますが、必須ではありません。
レシピは一般的に:
- 特定の共通の問題を解決します
- 可能な限りかんたんな例から始まります
- 一度に１つずつ複雑なものが紹介されます
- コンセプトを再び説明するのではなく、他のドキュメントにリンクします
- 精通することよりも問題を示します。
- 結果だけではなく、プロセスを説明します
- あなたの方法の長所と短所を、また適切ではない場合を含めて説明します
- もし該当する場合、代替案を挙げ、別のレシピで学習することができます
また、以下のテンプレートに従ってください。しかしながら、わかりやすくするために必ずしもフローに沿う必要はありません。いずれにせよ、すべてのレシピはある時点で、可能なら下記のパターンを利用したセクションの代替案をもとに、文章表現についての議論を経る必要があります。
基本例
必須
- ひとこと、ふたことで問題を明確にしてください。
- ひとこと、ふたことで最もかんたんな解決策を説明してください。
- 最小のコードサンプルで示してください。
- ひとことで達成されたものは何か説明してください。
価値の詳細
必須
- 例を見ながら、持つかもしれない共通の質問について取り扱ってください。 (ブロッククォートはこれに最適です)
- 一般的な失敗例とそれの回避方法を示してください。
- とてもシンプルなコードサンプルでグッドパターンとバッドパターンを示してください。
- なぜこれが説得力のあるサンプルなのか議論してください。 参照リンクは必須ではありませんが、推奨されています。
実例
必須
次のいずれかの方法で、一般的な、または興味深いユースケースを提供するコードを試してください:
- いくつかの簡潔なセットアップを済ませる、もしくは、
- codepen/jsfiddle でサンプルを実行する
もし後者を選択した場合、それはどんなものか、またどのように動作するかについてしっかりと話す必要があります。
その他のコンテクスト
任意
どこに適用するのか、なぜそれがうまくいくのかというパターンについて書くときにとても役立ちます。自分でやるかまたは、人々にここの参考資料を見せてコードを実行してください。
このパターンを避けるとき
任意
このセクションは必須ではありませんが、強くお勧めします。 それは状態の変化に基づいてクラスを切り替えるなど非常にシンプルなものを書くには向いておらず、 mixins のようなさらに高度なパターンでは意味を成します。 開発に関するほとんどの質問に対しての答えは “時と場合による!” です。 このセクションではそれを受け入れます。 ここでは、パターンが有用なとき、それを避けるべきとき、また他のものがなにか意味をなすときなどについて、隠すことなく見ていきます。
代替パターン
必須
このセクションは、回避に関する上記のセクションを提供したとき必須になります。「特定の状況下でアンチパターンになる」と言われた読者を不安にさせないためにも、別の方法を探ることは重要です。そうするときには、ウェブは大きな集合体だということや、多くの人々が異なったコードベースを持ち、異なった目標を解決しようとしていることを考慮してください。アプリケーションは大規模または小規模ですか？ Vue を既存のプロジェクトに統合していますか？または新しく構築していますか？1つまたはたくさんの目標を解決しようとしていますか？非同期データはたくさんありますか？これらの懸念はすべて代替の実装に影響します。良いクックブックレシピは、開発者にこのコンテクストを提供します。
最後に
このドキュメンテーションに貢献するためにはたくさんの時間が必要です。もしあなたが私たちのドキュメントにプルリクエストを送っていただけたら、感謝します。