はじめに

最終更新日: 2019年4月27日

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

クックブックとガイドの違い

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

これらの違いとともに、クックブックはステップバイステップのマニュアル ではない 点に注意してください。その内容の大部分については、HTML や CSS、JavaScript、npm/yarn などについての基本的な知識があることを前提としています。

クックブックへの貢献

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

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

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

レシピは一般的に:

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

また、以下のテンプレートに従ってください。しかしながら、わかりやすくするために必ずしもフローに沿う必要はありません。いずれにせよ、すべてのレシピはある時点で、可能なら下記のパターンを利用したセクションの代替案をもとに、文章表現についての議論を経る必要があります。

基本例

_必須_

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

価値の詳細

_必須_

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

実例

_必須_

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

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

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

その他のコンテクスト

_任意_

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

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

_任意_

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

代替パターン

_必須_

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

最後に

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