はじめに

最終更新日: 2018年5月8日

⚠️注意: クックブックは随時追加されます。このため、一部のセクションでは翻訳がされず原文ものがあります。現在本着作業中一覧はこちら。本作業中のものついては、お待ち下さい🙏。もし、翻訳のお手伝いをしたい方は、こちらの翻訳ガイドをお読みください。

クックブックとガイド

クックブックとガイドはどのように異なるのでしょうか?なぜクックブックが必要なのでしょうか?

クックブックの貢献

私たちが目指しているもの

クックブックは一般的なものや興味深いユースケースのどちらも進めるための具体例を開発者たちに提供し、より複雑な内容を徐々に説明していきます。私たちの目標は、簡単な入門例を超え、広く適用可能なコンセプトと、そのアプローチに対する注意点を実証することです。

貢献に興味があれば、 cookbook idea タグがついている Issue 上にあなたのコンセプトを提出することによってコラボレーションを開始し、プルリクエストが成功するようにガイドします。 あなたのアイディアが承認されたら、可能な限りテンプレートに従ってください。 一部のセクションは必須で、いくつかは任意です。 数値順にすることが強く推奨されますが、必須ではありません。

レシピは一般的に:

  • 特定の共通の問題を解決します
  • 可能な限りかんたんな例から始まります
  • 一度に1つずつ複雑なものが紹介されます
  • コンセプトを再び説明するのではなく、他のドキュメントにリンクします
  • 精通することよりも問題を示します。
  • 結果だけではなく、プロセスを説明します
  • あなたの方法の長所と短所を、また適切ではない場合を含めて説明します
  • もし該当する場合、代替案を挙げ、別のレシピで学習することができます

以下のテンプレートに従ってください。しかしながら、わかりやすくするために必ずしもフローに沿う必要はありません。どちらの方法でも、すべてのレシピで、このパターンを選び使用したニュアンスを、任意の時点で、好ましくは代替パターンセクションの形で説明する必要があります。

基本例

_必須_

  1. ひとこと、ふたことで問題を明確にしてください。
  2. ひとこと、ふたことで最もかんたんな解決策を説明してください。
  3. 最小のコードサンプルで示してください。
  4. ひとことで達成されたものは何か説明してください。

価値の詳細

_必須_

  1. 例を見ながら、持つかもしれない共通の質問について取り扱ってください。 (ブロッククォートはこれに最適です)
  2. 一般的な失敗例とそれの回避方法を示してください。
  3. とてもシンプルなコードサンプルでグッドパターンとバッドパターンを示してください。
  4. なぜこれが説得力のあるサンプルなのか議論してください。 参照リンクは必須ではありませんが、推奨されています。

実例

_必須_

次のいずれかの方法で、一般的な、または興味深いユースケースを提供するコードを試してください:

  1. いくつかの簡潔なセットアップを済ませる、もしくは、
  2. codepen/jsfiddle でサンプルを実行する

もし後者を選択した場合、それはどんなものか、またどのように動作するかについてしっかりと話す必要があります。

その他のコンテクスト

_任意_

どこに適用するのか、なぜそれがうまくいくのかというパターンについて書くときにとても役立ちます。自分でやるかまたは、人々にここの参考資料を見せてコードを実行してください。

このパターンを避けるとき

_任意_

このセクションは必須ではありませんが、強くお勧めします。 それは状態の変化に基づいてクラスを切り替えるなど非常にシンプルなものを書くには向いておらず、 mixins のようなさらに高度なパターンでは意味を成します。 開発に関するほとんどの質問に対しての答えは “時と場合による!” です。 このセクションではそれを受け入れます。 ここでは、パターンが有用なとき、それを避けるべきとき、また他のものがなにか意味をなすときなどについて、隠すことなく見ていきます。

代替パターン

_必須_

このセクションは、回避に関する上記のセクションを提供したとき必須になります。驚いていないという特定の状況下で人々はアンチパターンを伝えるので、別の方法を探ることは重要です。そうするときには、ウェブは大きな集合体だということや、多くの人々が異なったコードベースを持ち、異なった目標を解決しようとしていることを考慮してください。アプリケーションは大規模または小規模ですか? Vue を既存のプロジェクトに統合していますか?または新しく構築していますか?1つまたはたくさんの目標を解決しようとしていますか?非同期データはたくさんありますか?これらの懸念はすべて代替の実装に影響します。良いクックブックレシピは、開発者にこのコンテクストを提供します。

最後に

このドキュメンテーションに貢献するためにはたくさんの時間が必要です。もしあなたが私たちのドキュメントにプルリクエストを送っていただけたら、感謝します。