diff options
Diffstat (limited to 'files/ja/mdn')
124 files changed, 14749 insertions, 0 deletions
diff --git a/files/ja/mdn/about/index.html b/files/ja/mdn/about/index.html new file mode 100644 index 0000000000..561a45fbbf --- /dev/null +++ b/files/ja/mdn/about/index.html @@ -0,0 +1,146 @@ +--- +title: MDN Web Docs について +slug: MDN/About +tags: + - Collaborating + - Community + - Copyright + - Documentation + - Guide + - Licenses + - MDN Meta + - ガイド + - コミュニティ + - ドキュメント + - ライセンス + - 著作権 +translation_of: MDN/About +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubNav("/ja/docs/MDN")}}</div> + +<p>MDN Web Docs (以前は MDN — Mozilla Developer Network と呼ばれていました) は進化し続ける学習プラットフォームであり、下記に挙げるようなウェブ技術とウェブを支えるソフトウェアについて学ぶことができます。</p> + +<ul> + <li><a href="/ja/docs/CSS" title="/ja/docs/CSS">CSS</a>、<a href="/ja/docs/HTML" title="/ja/docs/HTML">HTML</a>、<a href="/ja/docs/JavaScript" title="/ja/docs/JavaScript">JavaScript</a> などのウェブ標準</li> + <li><a href="/ja/docs/Apps" title="/ja/docs/Apps">オープンなウェブアプリの開発</a></li> + <li><a href="/ja/docs/Mozilla/Add-ons" title="/ja/docs/Add-ons">Firefox のアドオン開発</a></li> +</ul> + +<h2 id="Our_mission" name="Our_mission">我々のミッション</h2> + +<p>MDN のミッションは単純です。開発者が<a href="/ja/docs/Web">オープンなウェブ</a>上でプロジェクトを簡単に構築できるようにする情報を提供することです。ウェブ上で公開されているオープンなテクノロジーであれば、どんなものでも私たちは文書化したいと考えています。</p> + +<p>また、<a href="/ja/docs/Mozilla">Mozilla の製品</a>に関するドキュメントや、<a href="/ja/docs/Mozilla">Mozilla プロジェクトをビルドしたり、プロジェクトに協力する</a>方法に関するドキュメントも提供します。</p> + +<p>もしあるトピックを MDN に含めるべきか、自信を持って判断できないときは、<a href="ja/docs/MDN/Contribute/Guidelines/Does_this_belong_on_MDN">これは MDN に含まれますか？</a> のページを読んでみてください。</p> + +<h2 id="How_you_can_help" name="How_you_can_help">協力する方法</h2> + +<p>MDN を手助けるには、プロのコーダーやライターになる必要はありません。文書の意味が通るかを確認する編集レビュー、ちょっとした文章の寄稿、サンプルコードの追加など、いろいろな方法があります。実際にとても多くの方法があるため、私たちは <a href="/ja/docs/MDN/Getting_started">MDN を始めよう</a> ページを用意しています。あなたがどんなことに興味があるか、またどれだけ使える時間があるのかによって、自分にピッタリのタスクを見つけて貢献してみてください。</p> + +<p>また、あなたのブログやウェブサイトで <a href="/ja/docs/MDN/About/Promote">MDN の宣伝をする</a> ことも私たちの助けになります。</p> + +<h2 id="The_MDN_community" name="The_MDN_community">MDN コミュニティ</h2> + +<p>私たちのコミュニティはグローバルなコミュニティです。世界中に様々な言語で作業をするすばらしい協力者の皆さんがいます。私たちについてもっと知りたい、あるいは MDN に関する助けが必要な場合は、<a href="https://discourse.mozilla-community.org/c/mdn">ディスカッションフォーラム</a>に参加してください。英語のでのコミュニケーションになります。<a href="http://twitter.com/MozDevNet">@MozDevNet</a> の Twitter アカウントをフォローして最新情報を追いかけることもできます。何かの間違いを見つけたりフィードバックしたり (感謝したり) したい場合、ライターや貢献者にツイートすることもできます。</p> + +<h2 id="Using_MDN_Web_Docs_content" name="Using_MDN_Web_Docs_content">MDN Web Docs の使用</h2> + +<p>MDN のコンテンツは無償で、オープンソースライセンスの下に利用できます。</p> + +<h3 id="Copyrights_and_licenses" name="Copyrights_and_licenses">著作権とライセンス</h3> + +<p>MDN のコンテンツはオープンソースライセンスの下で完全に利用できます。この節はどんな種類のコンテンツがあり、それぞれがどんなライセンスが有効かを網羅します。</p> + +<h4 id="Documentation_and_articles" name="Documentation_and_articles">文書と記事</h4> + +<p><strong>MDN の wiki 文書</strong>は、 Mozilla Foundation の内外のライターの協力により作成されています。特に明記されていない限り、コンテンツは <a class="external text" href="https://creativecommons.org/licenses/by-sa/2.5/" rel="nofollow">Creative Commons: Attribution-Sharealike license</a> (CC-BY-SA), v2.5 もしくはそれ以上のバージョンの条件の下で利用可能です。</p> + +<p>MDN コンテンツを再利用するときは、2 つのことを確認する必要があります。</p> + +<ol> + <li> + <p>帰属は元のコンテンツに与えられます</p> + + <p>"Mozilla Contributors" を属性とし、ソースとなるコンテンツの特定の Wiki ページへのハイパーリンク (オンラインの場合) または URL (印刷物の場合) を含めてください。たとえば、この記事の帰属を示すには、次のように書くことができます。</p> + + <blockquote> + <p><a href="https://developer.mozilla.org/ja/docs/MDN/About">About MDN</a> by <a href="https://developer.mozilla.org/ja/docs/MDN/About$history">Mozilla Contributors</a> is licensed under <a href="https://creativecommons.org/licenses/by-sa/2.5/">CC-BY-SA 2.5</a>.</p> + </blockquote> + + <p>この例では、"Mozilla Contributors" が引用ページの履歴にリンクしていることに注意してください。詳しい説明は<a href="https://wiki.creativecommons.org/wiki/Best_practices_for_attribution">帰属のベストプラクティス</a>を参照してください。</p> + </li> + <li> + <p>あなたの再利用はオリジナルのコンテンツと同じライセンスの下で公開されています。つまり CC-BY-SA v2.5 またはそれ以降のバージョンです</p> + </li> +</ol> + +<h4 id="Code_samples_and_snippets" name="Code_samples_and_snippets">コードサンプルとスニペット</h4> + +<p>2010 年 8 月 20 日以降に追加されたコードサンプルは、<a class="external" href="https://creativecommons.org/publicdomain/zero/1.0/">パブリックドメイン</a> (<a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>) にあります。ライセンス通知は必要ありませんが、必要な場合は、"すべての著作権はパブリックドメインに帰属します。http://creativecommons.org/publicdomain/zero/1.0/" を使用できます。</p> + +<p>2010 年 8 月 20 日より前にこの wiki に追加されたコードサンプルは <a class="external" href="https://opensource.org/licenses/mit-license.php">MIT ライセンス</a>の下で利用可能です。次の帰属情報を MIT テンプレートに挿入する必要があります。"©<Wiki ページの最終改訂日> <Wiki に掲載した人の名前>"</p> + +<p>コードサンプルがどのライセンスで利用可能かを判断することができます。履歴を表示するには:</p> + +<ol> + <li>記事のヘッダーにある <strong>Wiki で編集</strong> ボタンをクリックします。これで、<a href="https://wiki.developer.mozilla.org">編集可能な、MDN Web Docs の Wiki バージョン</a>に移動します (しかし、実際に編集モードに入っているのではありません)。</li> + <li>Wiki 記事の右上にある歯車アイコンをクリックし、表示されたメニューで <strong>履歴</strong>を選択します。</li> + <li><strong>すべて見る</strong>をクリックし、2010 年 8 月 20 日以前の最新のリビジョンを見つけます。</li> + <li>リビジョンの日付をクリックしてその日の記事のバージョンを確認します。</li> +</ol> + +<p>サンプルがある場合は、ライセンスが変更される前に追加されたものであり、MIT ライセンスの条件で利用可能です。サンプルがないか、2010 年 8 月 20 日以前のリビジョンがない場合、変更後に追加されたものであり、パブリックドメインです。</p> + +<h4 id="Contributions" name="Contributions">貢献</h4> + +<p>この wiki に協力したい場合は、Attribution-ShareAlike ライセンス (または編集中のページで既に指定されている代替ライセンス) でドキュメントを公開し、<a href="https://creativecommons.org/publicdomain/zero/1.0/">Creative Commons CC-0</a> (パブリックドメインの献身) でコードサンプルを公開する必要があります。この wiki に追加することは、あなたの協力がそれらのライセンスの下で利用可能になることにあなたが同意することを意味します。</p> + +<p>一部の古いコンテンツは、前述以外のライセンスで利用可能になりました。これらは<a class="internal" href="/Archive/Meta_docs/Examples/Alternate_License_Block">代替ライセンスブロック</a>によって各ページの下部に示されています。</p> + +<div class="warning"> +<p>新しいページをその他のライセンスで作成してはいけません。</p> +</div> + +<p><strong>ユーザーから提供された資料の著作権については、著作者がそれを第三者に譲渡しない限り、著作者に帰属するものとします。</strong></p> + +<p>ここに記載されている内容について、質問や懸念事項があれば、<a class="external" href="mailto:mdn-admins@mozilla.org?subject=MDN%20licensing%20question" rel="nofollow" title="mailto:eshepherd@mozilla.com">MDN 管理者</a> までご連絡ください。</p> + +<h4 id="Logos_trademarks_service_marks_and_wordmarks" name="Logos_trademarks_service_marks_and_wordmarks">ロゴ、商標、サービスマーク、ワードマーク</h4> + +<hr> +<p>Mozilla Foundation の商標、ロゴ、サービスマークの権利、およびこのウェブサイトの操作画面や{{訳語("操作感","look and feel")}}は、Creative Commons: Attribution-Sharealike license ライセンスに基づいて提供されるものではなく、それらが (ロゴや画像デザインといった) 著作物である限り、上記の条件に基づいて許諾される著作物には含まれません。あなたが文書のテキストを利用する場合、上述の権利を行使しようとする場合、またはこのサイトにおける私たちのライセンス条件について、その他の質問がある場合は、Mozilla Foundation の窓口 <a class="external text" href="mailto:licensing@mozilla.org" rel="nofollow" title="mailto:licensing@mozilla.org">licensing@mozilla.org</a> までご連絡ください。</p> + +<h3 id="Linking_to_MDN" name="Linking_to_MDN">MDN にリンクするには</h3> + +<p>リンクを張るときは、ガイダンス記事 <a href="/ja/docs/MDN/About/Linking_to_MDN">MDN にリンクするには</a>に従うのがベストプラクティスです。</p> + +<h2 id="Downloading_content" name="Downloading_content">コンテンツをダウンロードするには</h2> + +<h3 id="Single_pages" name="Single_pages">単一ページのダウンロード</h3> + +<p>単一ページのコンテンツについては、ダウンロードしたいフォーマットを <a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters#URL_parameters">URL パラメーター</a>に追加することで、取得することができます。</p> + +<h3 id="Third-party_tools" name="Third-party_tools">サードパーティ製のツールを使ったダウンロード</h3> + +<p>MDN のコンテンツは、<a href="http://kapeli.com/dash">Dash</a> (macOS 用) や <a href="http://zealdocs.org/">Zeal</a> (Linux および Windows用) などのサードパーティ製のツールを使っても読むことができます。</p> + +<p><a href="https://kapeli.com/">Kapeli</a> も <a href="https://kapeli.com/mdn_offline">オフラインで使用できる MDN 文書</a> を公開しており、HTML、CSS、JavaScript、SVG、XSLT が含まれます</p> + +<h2 id="Reporting_problems_with_MDN_Web_Docs" name="Reporting_problems_with_MDN_Web_Docs">MDN Web Docs の問題を報告する</h2> + +<p><a href="/ja/docs/MDN/Contribute/Howto/Report_a_problem">MDN の問題を報告する</a> を読んでください。</p> + +<h2 id="History_of_MDN_Web_Docs" name="History_of_MDN_Web_Docs">MDN Web Docs の歴史</h2> + +<p>MDN Web Docs (かつては Mozilla Developer Network (MDN)、その前は Mozilla Developer Center (MDC) として知られ、また <em>Devmo</em> としても知られていた) プロジェクトは、2005年初頭、 <a class="external" href="https://foundation.mozilla.org">Mozilla Foundation</a> が AOL からオリジナルの Netscape <a href="https://web.archive.org/web/*/devedge.netscape.com">DevEdge</a> のコンテンツの使用ライセンスを取得した時点から始まりました。 DevEdge のコンテンツの中からまだ使える素材が探し出され、更新と維持が楽になるよう、ボランティアによって wiki に移されました。</p> + +<p>2017年7月に名前が MDN Web Docs に変更されました。この決定の背景となる理念については <a href="https://blog.mozilla.org/opendesign/future-mdn-focus-web-docs/">The Future of MDN: A Focus on Web Docs</a> をご覧ください。</p> + +<p>さらに詳しい MDN の歴史については、私たちのページ <a href="https://developer.mozilla.org/ja/docs/MDN_at_ten">MDN は 10 周年を迎えました</a>を参照してください。当時の関係者から聞き取った内容も含まれています。</p> + +<h2 id="About_Mozilla" name="About_Mozilla">Mozilla について</h2> + +<p>私たちがどんな組織なのかもっと知りたい、どうすれば <em>Mozilla</em> の一員になれるのか知りたい、あるいは単に私たちがどこにいるのか知りたい。そう考えているあなたは、正しい場所に来ています。何が私たちを動かしているのか、そして他の組織とは違ったものにしているのか、そうしたことを知りたければ、私たちの<a href="https://www.mozilla.org/ja/mission/">ミッション</a>のページを訪れてみてください。</p> diff --git a/files/ja/mdn/about/linking_to_mdn/index.html b/files/ja/mdn/about/linking_to_mdn/index.html new file mode 100644 index 0000000000..c7b7e87623 --- /dev/null +++ b/files/ja/mdn/about/linking_to_mdn/index.html @@ -0,0 +1,88 @@ +--- +title: MDN にリンクするには +slug: MDN/About/Linking_to_MDN +tags: + - Documentation + - Guide + - MDN +translation_of: MDN/About/Linking_to_MDN +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary">MDN にリンクするガイドラインやそもそもリンクして良いのか聞かれることがありますが、もちろん<strong> OK です。MDN にリンクして頂いて構いません。</strong>その際のガイドラインやベストプラクティスが必要であれば続けて読んでください。</span></p> + +<h2 id="MDN_にリンクして良いですか？">MDN にリンクして良いですか？</h2> + +<p><strong>はい！</strong>是非どうぞ！ハイパーテキストリンクは Web の本質的な機能であるだけでなく、ユーザに価値あるリソースを指し示す方法であると共に、私たちのコミュニティの成果に対する信頼を示すことでもあります。</p> + +<p>ですから、MDN のコンテンツへのリンクは是非遠慮なくしてください。<a href="/">MDN のフロントページ</a>、あるいは必要に応じて MDN 内の特定ページにリンクしてください。リンク先ページ選択のベストプラクティスは以下の通りです。</p> + +<h2 id="どのページにリンクすべきですか？">どのページにリンクすべきですか？</h2> + +<p>リンクすべき特定のページは決まっていません。<strong>あなたの読者に役立つのがどのページか</strong>というのが大事です。</p> + +<ul> + <li>MDN 自体について書かれている時はメインページにリンクしていただけます: <a href="/">https://developer.mozilla.org/</a></li> + <li>特定領域や技術について言及される場合は特定のトピックについて目次や索引となる<strong>ランディングページ</strong>と呼ばれるページにリンクするのが良いでしょう。例えばこのようなページです: + <ul> + <li>HTML: <a href="/ja/docs/Web/HTML">https://developer.mozilla.org/ja/docs/Web/HTML</a></li> + <li>HTML5: <a href="/ja/docs/Web/Guide/HTML/HTML5">https://developer.mozilla.org/ja/docs/Web/Guide/HTML/HTML5</a></li> + <li>CSS: <a href="/ja/docs/Web/CSS">https://developer.mozilla.org/ja/docs/Web/CSS</a></li> + <li>CSS3: <a href="/ja/docs/Web/CSS/CSS3">https://developer.mozilla.org/ja/docs/Web/CSS/CSS3</a></li> + <li>DOM: <a href="/ja/docs/Web/API/Document_Object_Model">https://developer.mozilla.org/ja/docs/Web/API/Document_Object_Model</a></li> + <li>JavaScript: <a href="/ja/docs/Web/JavaScript">https://developer.mozilla.org/ja/docs/Web/JavaScript</a></li> + </ul> + </li> + <li>特定のページや技術などについて書かれている場合は個別のページにリンクするのが良いでしょう。例えば: + <ul> + <li>HTML の要素について説明しているなら、HTML 要素リストページ (<a href="/ja/docs/Web/HTML/Element">https://developer.mozilla.org/ja/docs/Web/HTML/Element</a>) や {{HTMLElement("colgroup")}} など個別要素のページ</li> + <li>同様に CSS についても CSS リファレンス (網羅的な目次ページ: <a href="/ja/docs/Web/CSS/Reference">https://developer.mozilla.org/ja/docs/Web/CSS/Reference</a>) や {{cssxref("list-style-type")}} といった特定プロパティのページ</li> + </ul> + </li> +</ul> + +<p><strong>いずれにしても、リンク元ページや読者にとって最適なページにリンクしてください。</strong>リンクや私たちではなく、読者こそが大事なのですから。</p> + +<h2 id="良いリンクの仕方は？">良いリンクの仕方は？</h2> + +<p>リンクの仕方は自明ですが、良いリンクの仕方は少々難しいこともあります。リンクの仕方はいくつかあります:</p> + +<h3 id="テキスト内でのリンク">テキスト内でのリンク</h3> + +<p>これが最も便利なリンク方法です。特定の話題に対して読者に更なる情報をリンクで提供するのです。多くの場合、このようなリンクはユーザを個別の関連情報ページにリンクするもので、Web サイトのホームページにリンクするものではありません (例外もありますが)。</p> + +<blockquote> +<p>… <a href="/ja/docs/IndexedDB">IndexedDB</a> API を使えば、ローカルのデータベースにデータを格納できます…</p> +</blockquote> + +<p>このようなリンクはワンクリックでより詳しい情報が得られるユーザにとっても、的確な文脈で紹介してくれたことで気に入ってもらえるだろう MND にとっても、両方にとってとても価値あるものです。私たちのミッションは読者にできる限り速やかに必要な情報を届けることで、これは明らかにステキなやり方です。</p> + +<h4 id="テキスト中のリンクで避けるべきこと">テキスト中のリンクで避けるべきこと</h4> + +<p>テキスト中のリンクはステキで便利なものですが、留意すべき事がいくつかあります:</p> + +<ul> + <li><strong>リンクしすぎないこと。</strong><a href="/en-US/docs/Web/JavaScript/Reference/Statements/do...while" title="do...while">す</a> <a href="/en-US/docs/Web/CSS/:not" title=":not()">べ</a> <a href="/en-US/docs/Web/CSS/:link" title=":link">て</a> の単語、あるいはほぼすべての文字にリンクをつけるのは目障りです。文章の中で大事な部分だけをしっかり選んでそこだけリンクするか、読者が既に知っていそうな事についてまでリンクしないようにすること。</li> + <li><strong>同じ用語について何度も繰り返しリンクしない。</strong> 例えば CSS アニメーションについて各場合、「アニメーション」という単語がでてくるたびに <a href="/en-US/docs/Web/CSS/animation"><code>animation</code> CSS プロパティ</a> にリンクする必要はありません。読者はそれについて知らなければ、最初にでてきたときに関連情報へのリンクをクリックします。それ以降の部分では、以前から知っていたか前出時にリンク先を見て知ったかに関わらず、すでに知っている前提で書き進めることができます。読者がリンク先を参照するためにページをスクロールせずに済むように、同じ用語について何度か (多くとも数段落毎に一度) リンクするのは構いません。</li> + <li><strong>フォーラムやブログコメントでリンクするときにはご注意を。</strong>具体的な質問や問題に対して適切な情報源に関連リンクを示すのはステキだし歓迎されます。Web 上のあちこちに MDN へのリンクを無闇に書きまくるのは不適切です。サイトの管理者や読者は速やかにあなたをスパマーとして認識し、MDN の評価が傷つけられます。私たちは価値あるリソースを作ることに努めておりそのような行為によって私たちの努力の成果が損なわれることは望んでいません。適切な数だけ関連するリンクを紹介してください。</li> +</ul> + +<h3 id="バナーや画像をサイトに追加するには">バナーや画像をサイトに追加するには</h3> + +<p>本文中からのリンク以外に、例えばサイドバーの画像から MDN にリンクしていただくこともできます。テキスト中のリンクはあなたが読者に情報を保管する目的でリンクするものですが、この場合は意味合いが異なります。サイドバーなどにリンク画像を追加するのは、あなたの MDN プロジェクトへの支援を表明するものであったり、MDN を宣伝するものであったり、総合的な情報源として MDN を紹介するものになります。</p> + +<p>支援を表明するのに遠慮しないでください。<a href="/docs/MDN/Promote">MDN を宣伝するには</a> ページであなたのサイトに合わせたボタンを作ってください。ランディングページなど他のページへのリンクにしていただくのも自由です。</p> + +<h3 id="WordPress_から_MDN_に自動リンクするには">WordPress から MDN に自動リンクするには</h3> + +<p>ブログポストから用語を選んで MDN の適切なページに自動的にリンクする <a href="/docs/MDN/Promote#WordPress_plugin">WordPress plugin</a> を用意しています。このプラグインでは上記のガイドラインに沿ったかたちでリンクしながら Web 技術についてブログを書るよう助けてくれます。試しにインストールしてみて、良ければご利用ください。</p> + +<p>ご支援ありがとうございます！</p> + +<article> +<h2 id="Cross-Origin_Resource_Sharing">Cross-Origin Resource Sharing</h2> + +<p>私達はMDNの公開する全てのデータで <a href="https://developer.mozilla.org/docs/HTTP/Access_control_CORS" title="/docs/HTTP/Access_control_CORS">CORS</a> を有効にしているつもりです。これにはほぼ全てのものが当てはまるはずです。もしあなたがなにか<a href="https://developer.mozilla.org/docs/HTTP/Access_control_CORS" title="/docs/HTTP/Access_control_CORS">cross-origin requests</a>が使えない状態を発見したら、それは<a href="https://bugzilla.mozilla.org/form.mdn">修正すべきバグ</a>です。</p> +</article> + +<article> +<header> </header> +</article> diff --git a/files/ja/mdn/community/conversations/index.html b/files/ja/mdn/community/conversations/index.html new file mode 100644 index 0000000000..2ed336eecc --- /dev/null +++ b/files/ja/mdn/community/conversations/index.html @@ -0,0 +1,53 @@ +--- +title: MDN コミュニティでの対話 +slug: MDN/Community/Conversations +tags: + - Community + - Guide + - MDN Meta +translation_of: MDN/Community/Conversations +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">MDN での"作業"は MDN のサイトで行われますが、"コミュニティ" はまた、(非同期の) ディスカッションと(同期的な) オンラインチャット、ミーティングも行っています。</p> + +<h2 id="Asynchronous_discussions" name="Asynchronous_discussions">非同期のディスカッション</h2> + +<p>情報を共有し、ディスカッションを行うため、<a href="https://discourse.mozilla-community.org/c/mdn">Mozilla Discourse forum に専用のカテゴリー ("MDN") があります</a>。ドキュメントのコンテンツ作成・翻訳・メンテナンス、MDN プラットフォームの開発、計画、目標設定、進捗管理といった、MDN に関するすべてのトピックでこのカテゴリーを使用します。</p> + +<ul> + <li>Mozilla の Discourse に参加するには、<a href="https://discourse.mozilla-community.org/t/signing-up-and-logging-in/16017">Signing up and logging in</a> をご覧ください。Mozilla LDAP アカウントを持っている場合は、"Login with email" の代わりにそちらを使用できます。</li> + <li>MDN カテゴリーを購読するには、<a href="https://discourse.mozilla-community.org/t/subscribing-to-categories-and-topics/16024">Subscribing to categories and topics</a> をご覧ください。</li> + <li>(任意) 主に電子メールで Discourse とやりとりしたい場合は、<a href="https://discourse.mozilla-community.org/t/mailman-mode/15279">Set up a mailing list experience for yourself</a> をご覧ください。<a href="mailto://mdn@mozilla-community.org">mdn@mozilla-community.org</a> に電子メールを送信することで、Discourse でのディスカッションを開始できます。電子メールで Discourse を使用する場合は、受信した通知メールに返信することで、メッセージに返信できます。返信内にインラインでコメントを挿入したい場合は、インラインの部分の前後にキャリッジリターンを 2 つずつ入れてください。このようにすると、Discourse が正しく処理できます。</li> +</ul> + +<h3 id="Historical_archives" name="Historical_archives">歴史的なアーカイブ</h3> + +<p>2017 年 6 月より前は MDN 関連のディスカッションを、Google グループを経由して保存されていたメーリングリストで行っていました。これら過去のディスカッションを検索したい場合は、Google グループで対応する古いメーリングリストを閲覧できます。(はい、これらの名前が重複していて混乱を招いていることは承知しています。歴史的アクシデントによるものです。申し訳ございません。)</p> + +<dl> + <dt><a href="https://groups.google.com/forum/#!forum/mozilla.dev.mdc">mozilla.dev.mdc</a> 別名 <strong>dev-mdc</strong></dt> + <dd>このメーリングリストは MDN 上のドキュメントについて議論する場でした。</dd> + <dt><a href="https://groups.google.com/forum/#!forum/mozilla.dev.mdn">mozilla.dev.mdn</a> 別名 <strong>dev-mdn</strong></dt> + <dd>このフォーラムは <a href="/ja/docs/Project:MDN/Kuma">Kuma</a> プラットフォームを支えている MDN での開発作業についての議論を行うところでした。</dd> + <dt><a href="https://groups.google.com/forum/#!forum/mozilla.mdn">mozilla.mdn</a> 別名 <strong>mdn@</strong></dt> + <dd>これは MDN ウェブサイトや関連した取り組みに対する、ハイレベルな計画と優先順位についての議論のためのフォーラムでした。</dd> +</dl> + +<h2 id="Synchronous_chat" name="Synchronous_chat">同期のチャット</h2> + +<p>Mozilla のリアルタイムで議論を行うためののプラットフォームは <a href="https://matrix.org/">Matrix</a> で、 <a href="https://chat.mozilla.org/">Mozilla 自身がサーバーを持っている</a>チャット手法です。</p> + +<p><a href="https://chat.mozilla.org/#/room/#mdn:mozilla.org">MDN Web docs のチャットルーム</a>は、 MDN のコンテンツを議論するための主要なチャンネルです。私たちは執筆やコンテンツの構成などについて話し合っています。また、「ウォータークーラー」のような会話もしています。この部屋は北米とヨーロッパの平日に活動している可能性が高いです。</p> + +<p><a href="https://wiki.mozilla.org/Matrix">Mozilla での Matrix の使い方</a>をもっと知りたいかもしれませんし、もしあなたが本当に興味を持っているのであれば、 <a href="https://about.riot.im/">Riot.im</a> のようなスタンドアロンの Matrix アプリケーションをインストールしてみてはいかがでしょうか。</p> + +<h3 id="What_about_IRC" name="What_about_IRC">IRC とは</h3> + +<p>長年にわたり、 Mozilla はリアルタイムの議論のために Internet Relay Chat (IRC) を使用していました。2020年初頭の時点で、 IRC は Matrix に取って代わられて非推奨となっています。 MDN を含む多くの場所で IRC チャンネルへの言及を目にするかもしれません。 MDNで見つけた IRC チャンネルへのリンクを更新して、代わりに対応する Matrix ルームを指すようにしてください。トピックのマトリックスルームがわからない場合は、 <a href="https://chat.mozilla.org/#/room/#general:mozilla.org">General</a> ルームで質問してください。アクティブでなくなったプロジェクトやトピックには Matrix ルームがないかもしれません。その場合はリンクを削除してください。</p> + +<h2 id="Join_our_meetings_and_other_eventss" name="Join_our_meetings_and_other_eventss">ミーティングやその他のイベントに参加する</h2> + +<p>MDN チームは、MDN コミュニティに開放している定期ミーティングをいくつか催しています。スケジュールやアジェンダ、過去と今後のミーティングの記録といった詳細は Mozilla Wiki の <a href="https://wiki.mozilla.org/MDN/Meetings">MDN Meetings</a> のページをご覧ください。</p> + +<p>ここで紹介したものやその他のミーティング、ミートアップ、その他のイベントについては <a href="https://www.google.com/calendar/embed?src=mozilla.com_2d35383434313235392d323530%40resource.calendar.google.com">MDN イベントカレンダー</a>をご覧ください。定期開催のミーティングは <a href="https://wiki.mozilla.org/MDN/Meetings">MDN ミーティングの Wiki ページ</a>にまとめられています。</p> diff --git a/files/ja/mdn/community/doc_sprints/index.html b/files/ja/mdn/community/doc_sprints/index.html new file mode 100644 index 0000000000..5af4cd4a75 --- /dev/null +++ b/files/ja/mdn/community/doc_sprints/index.html @@ -0,0 +1,121 @@ +--- +title: Doc sprints +slug: MDN/Community/Doc_sprints +translation_of: MDN/Community/Doc_sprints +--- +<div>{{MDNSidebar}}</div><p>{{ draft() }}</p> + +<div class="note"> +<p><strong>Note: </strong>The MDN community often held doc sprints during 2010-2013. Starting in 2014, these events were broadened in scope to "<a href="https://blog.mozilla.org/community/2015/04/17/a-highly-productive-hack-on-mdn-weekend-in-berlin/">Hack on MDN</a>" events that include code hacking as well as documentation projects. Most of the advice below applies equally well to "Hack" sprints and documentation sprints.</p> +</div> + +<p><span class="seoSummary">これは、Doc sprint（集中的な文書関連イベントを実施する短い期間）を組織化するためのガイドです。Doc sprint を組織化した経験者からのアドバイス、コツを含み、あなたが同じことがをする助けとなるものです。</span>このガイドはまた、<a class="external" href="http://en.flossmanuals.net/book-sprints/book-sprints/_draft/_v/1.0/introduction/" rel="external" title="http://booki.flossmanuals.net/book-sprints/_draft/_v/1.0/introduction/">FLOSS Manuals Book Sprints</a> という書籍からのアイディアを引用しています。</p> + +<h2 id="Doc_sprint_とは">Doc sprint とは?</h2> + +<p>Doc sprint とは、短い期間に、集まってドキュメントを作成することを指します。実際に、もしくは仮想的に集まって、決められたトピックや、それに関連した文書を協力して作成します。</p> + +<h2 id="スプリントの種類">スプリントの種類</h2> + +<p>Sprints can be virtual or in-person, or some combination. For a virtual sprint, everyone participates from wherever they happen to be located, communicating solely through mediated channels. For an in-person sprint, participants gather in the same location for the duration of the sprint, so that they can communicate face-to-face. Hybrid sprints can be mostly-in-person with some remote participants, or mostly-virtual with some local gatherings. In-person sprints require more logistical planning, to secure a meeting location, to get everybody there, and to house and feed them during the sprint.</p> + +<p>Another way to categorize sprints is by topical focus. For example, a sprint might focus on a particular subject area, such as Web development, or translation into a particular language.</p> + +<h2 id="スプリントを計画する">スプリントを計画する</h2> + +<h3 id="目標を決める">目標を決める</h3> + +<p>コミュニティとコンテンツに関して明確な目標を設定しましょう。次のようなことについて決めておくことによって、doc sprint の詳細を決めやすくなります。</p> + +<ul> + <li>特定の領域の文書を作成しますか？</li> + <li>チュートリアル、サンプルコード、翻訳など、作成したい文書やリソースの種類は決まっていますか？</li> + <li>新しい MDN への貢献者を誘いたいですか？</li> + <li>コミュニティメンバーの団結を高めたいですか？</li> +</ul> + +<h3 id="種類と想定参加者を決める">種類と想定参加者を決める</h3> + +<p>決定した目標に応じて、スプリントの形式を決めましょう（仮想的に集まるのか、実際に集まるのか、それともその組み合わせなのか）。想定する参加者も、併せて決めておきましょう。</p> + +<p>例えば、コミュニティメンバーを増やすことが目的なら、その地域の人が、実際に集まって行う形が最適でしょう。なぜなら長距離の移動も必要ありませんし、参加者がお互いに会って親睦を深められるからです。また特定の領域のトピックに焦点をあてたスプリントで、想定される参加者がお互いをよく知っているけれども、地理的に分散している場合は、仮想的に集まる形式をとると良いでしょう。</p> + +<h3 id="日時を決める">日時を決める</h3> + +<p>長距離の移動が必要な参加者のいるスプリントの場合、開催期間を 3 日間（例：週末 2 日と平日 1 日）はとったほうが良いでしょう。ただし長すぎないように注意が必要です。公開の、ローカルな、実際に集まるsプリントの場合は、多くの人が参加できると思われる日に、1 日だけ開催すると良いでしょう。仮想的に集まるなら、平日 1 日と休日 1日の 2 日開催とすることが多いです。例えばパリの Mozilla オフィスでは、毎水曜日に、ローカルなドックスプリントが開催されています。実際にオフィスに来る参加者が大半ですが、モントリオールからリモートで参加する人もいます。</p> + +<p>参加者が全員参加するカンファレンスがあるなら、その後に開催するのも良いでしょう。その場合は、参加者がカンファレンス後にスプリントへ参加する時間を取れることを確認しておきましょう。またカンファレンスの期間中にスプリントを開催するのは避けたほうがよいでしょう。</p> + +<p>仮想的に集まる形式をとるなら十分な作業時間を取れるように、タイムゾーンに気をつけましょう。ヨーロッパとアメリカやアメリカとアジアのように、異なるタイムゾーンからの参加者がいる場合は、参加者が起きていられる時間に計画しましょう。ただし全員にとって都合のよい時間はありえないことにも留意が必要です。</p> + +<p>また、仮想的に集まる形式の場合には、2-3 週前に日程を設定できます。実際に集まる場合は、予定や移動の調整が必要なので、2-3 週よりも前に日程を決めておく必要があります。</p> + +<h3 id="スプリントを広報する">スプリントを広報する</h3> + +<p>スプリントを公開し、参加者を広く募ることもできます。その際には、必ず参加できることがわかっている参加者が何人かいるようにしましょう。彼らが全員参加できるように日時を設定しましょう。非公開のスプリントの場合は、参加者を招待するだけでよいでしょう。ただし招待状は個別に送信し、なぜ参加者として選ばれたのかを詳細に説明するものである必要があります。</p> + +<p>公開のスプリントの場合は、トピックに興味のある既存グループを見つけておくと良いでしょう。例えば、特定の地域を対象とした集合型スプリントの場合、その地域で活動している Web 開発者のミートアップを見つけておくと良いでしょう。告知は送るグループにとって適切な手段でおこないましょう。告知文には、スプリントの詳細と参加登録方法が記載された Web ページへのリンクもつけておくと良いでしょう。<a href="https://www.eventbrite.com/" title="https://www.eventbrite.com/">Eventbrite </a>と <a href="http://lanyrd.com" title="http://lanyrd.com">Lanyrd</a> は参加登録も行えるサイトの例です。Mozilla の開発者向けイベントに、実際に参加するのは登録者の半数程度となっています。</p> + +<p>ターゲットとする人々に適切にリーチできるなら、SNS も利用しましょう。Web 開発者をターゲットとするなら、まず Twitter、次いで Google Plus が、Facebook や LinkedIn と比べて効果がありました。しかし地域によって SNS の利用は異なります（例えばブラジルでは Orkut の利用者が多い）。ターゲット層に多くのフォロワーを持つ人に、イベント告知のポストをシェアしてもらえるようにしておきましょう。</p> + +<h3 id="人が集まるスプリントで必要な手配">人が集まるスプリントで必要な手配</h3> + +<p>Logistics for in-person sprints are greater for longer sprints and those where sprinters travel to attend. A short or locals-only sprint need relatively little logistical support.</p> + +<h4 id="予算と資金">予算と資金</h4> + +<p>You need to figure out how much the event is going to cost, and where the money is going to come from.</p> + +<p>Costs to consider in your budget include:</p> + +<ul> + <li>旅費</li> + <li>宿泊</li> + <li>食料</li> + <li>会場</li> +</ul> + +<p>Some of these costs can be self-funded by participants, meaning that they pay for their own costs. There are a variety of ways to save money, which are mentioned in the following sections.</p> + +<p>It may be possible to get sponsorship from Mozilla to fund some of the costs of your event. It helps to have a clear focus for your event, and a specific plan and budget. If there is a <a href="https://reps.mozilla.org/people/#/">Mozilla Rep</a> in your area, work with them to request budget and swag through the Reps program. Otherwise, you can submit a <a href="https://bugzilla.mozilla.org/form.dev-engagement-event">developer events request</a> in Bugzilla.</p> + +<dl> + <dt>会場</dt> + <dd>There are lots of options for meeting space. If you are in a city with a Mozilla office, you can use the community space in that office. Elsewhere, options include meeting rooms in libraries, churches, coffee shops, or businesses where you have contacts. Many cities now have coworking spaces that rent their conference rooms for a reasonable fee.</dd> + <dt>資源</dt> + <dd>Be sure that your venue has good chairs and tables, and reliable power and Internet access. Sitting all day on a bad chair is not just uncomfortable; it can lead to injury. Make sure that the number of sprinters and their computers and devices does not overwhelm the power supply and available Internet bandwidth. Be generous (but not dangerous) with extension cords, and if necessary, international plug adapters. A projector for shared viewing can be very helpful. Whiteboards and sticky notes are great for brainstorming and planning.</dd> + <dt>移動</dt> + <dd>Travel is relevant only if the sprinters do not all live close to the sprint venue. The usual strategies for saving on travel apply, and are not specific to doc sprints.</dd> + <dt>宿泊</dt> + <dd>Where sprinters stay should not be inconveniently far from the meeting venue. It can be cheaper (and possibly more fun) to split the cost of a vacation house or flat, rather than paying for individual hotel rooms. If you have a mix of visitors and (willing) locals, the visitors can stay in the homes of local community members.</dd> + <dt>食料</dt> + <dd>Sprinters need to eat! Make arrangements for food during the sprint, and inform sprinters if certain meals will not be arranged. If the group is staying in a home, you can save money by buying and cooking food rather than going out to eat. Even if food is self-funded, it can reduce hassle to pitch into a common fund for food, rather than splitting every restaurant bill. If your venue allows, have snacks (some healthy and some not) available between meals.</dd> + <dt>楽しみ</dt> + <dd>Make time for non-writing social activities. These can be informal, like going for a hike together, or more formal, like a tourist excursion. Going out for beer (at the end of the day, of course) is usually a winner. On the other hand, don't plan every hour of every day. Everybody needs some down time, especially introverts.</dd> +</dl> + +<h2 id="sprint_の期間中">sprint の期間中</h2> + +<h3 id="作業を計画する">作業を計画する</h3> + +<p> </p> + +<h3 id="タスクを追跡する">タスクを追跡する</h3> + +<p>Have a way to track what tasks need to be worked on, who is doing what, and what has been completed. For MDN doc sprints, we use a wiki page for advance planning, and an etherpad for tracking work during the sprint.</p> + +<p>Often, people want to help but don't know where to start, and deciding among many options takes too much mental effort. For any given participant, give them a couple of possible tasks ("you could do A, or B"); this simplifies their choice, without making them feel like they're being bossed around.</p> + +<h3 id="協力する">協力する</h3> + +<p>One of the benefits of in-person sprints is that people can work together in ways that they might not be able to when they're not in the same place, for example, by working out ideas together on a whiteboard or by brainstorming with sticky notes. Still, there are opportunities for collaboration and camaraderie in any type of sprint. Chatting via IRC is essential for virtual sprints, and still very helpful for in-person sprints (for example, for sharing links). For a greater sense of "virtual presence", consider using a video conferencing service, such as Google Hangout.</p> + +<p>As an organizer, look for common interests among the participants and for ways that they can work together.</p> + +<h3 id="達成したことを祝う">達成したことを祝う</h3> + +<p>Be sure to take time to celebrate accomplishments at the end of the sprint. This gives participants a better feeling than when the sprint just ends without any summary. If possible, have people "demo" what they have done, even if it is just showing a new article page.</p> + +<p>Also, share the sprint accomplishments via a blog post, to celebrate publicly as well. This is important for any kind of sprint, but especially for virtual sprints, where the participants might not all be online at the official end of the sprint for a wrap-up session.</p> + +<p> </p> diff --git a/files/ja/mdn/community/index.html b/files/ja/mdn/community/index.html new file mode 100644 index 0000000000..7fdf95ca12 --- /dev/null +++ b/files/ja/mdn/community/index.html @@ -0,0 +1,54 @@ +--- +title: MDN Web Docs コミュニティに参加しましょう +slug: MDN/Community +tags: + - Community + - Guide + - Landing + - MDN Meta +translation_of: MDN/Community +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<div class="summary"> +<p>MDN Web Docs は wiki 以上のものです。つまりオープンなウェブ技術を利用する開発者たちのための素晴らしいリソースとして MDN を共に作り上げる、開発者たちによるコミュニティなのです。</p> +</div> + +<p>MDN に貢献していただけるのはもちろん大歓迎ですが、 MDN コミュニティに参加していただけるとよりありがたいです。コミュニティとつながりを持つには、こちらの簡単な3ステップを踏んでください。</p> + +<ol> + <li><a href="/ja/docs/MDN/Contribute/Howto/Create_an_MDN_account">MDN アカウントを作成する</a>。</li> + <li><a href="/ja/docs/MDN/Community/Conversations">ディスカッションに参加する</a>。</li> + <li><a href="/ja/docs/MDN/Community/Whats_happening">何が起きているのかを知り、対応する</a>。</li> +</ol> + +<h2 id="How_the_community_works" name="How_the_community_works">コミュニティはどのように機能するのか</h2> + +<p>以下は、 MDN のコミュニティを説明する他の記事です。</p> + +<div class="row topicpage-table"> +<div class="section"> +<dl> + <dt class="landingPageList"><a href="/ja/docs/MDN/Community/Roles">コミュニティでの役割</a></dt> + <dd class="landingPageList">MDN コミュニティ内には特定の役割を持つたくさんの役割があります。</dd> + <dt class="landingPageList"><a href="/ja/docs/MDN/Community/Doc_sprints">Doc sprints</a></dt> + <dd class="landingPageList">これはドキュメンテーションスプリントを開催するためのガイドです。ここには doc sprints を開催した人からの助言や tips があり、あなたの開催にも役立ちます。</dd> + <dt class="landingPageList"><a href="/ja/docs/MDN/Community/Whats_happening">何が起きているのかを知り対応する</a></dt> + <dd class="landingPageList">MDN は <a class="external external-icon" href="https://wiki.mozilla.org/MDN">Mozilla Developer Network community</a> によってもたらされています。ここに我々が行っていることの情報を共有する方法があります。</dd> +</dl> + +<dl> +</dl> +</div> + +<div class="section"> +<dl> + <dt class="landingPageList"><a href="/ja/docs/MDN/Community/Conversations">MDN コミュニティでの会話</a></dt> + <dd class="landingPageList">MDN の「成果」は MDN サイトに現れますが、「コミュニティ」も (非同期の) 議論と (同期の) オンラインチャットやミーティングで行われます。</dd> + <dt class="landingPageList"><a href="/ja/docs/MDN/Community/Working_in_community">コミュニティでの作業</a></dt> + <dd class="landingPageList">MDN の文書化にかなりの量で貢献する部分は、 MDN コミュニティの役割として作業する方法を知ることです。この記事では他のライターや開発チームの両方とやりとりすることを活用するのに役立つ tips を置いています。</dd> +</dl> +</div> +</div> diff --git a/files/ja/mdn/community/roles/admins/index.html b/files/ja/mdn/community/roles/admins/index.html new file mode 100644 index 0000000000..33f6cfe977 --- /dev/null +++ b/files/ja/mdn/community/roles/admins/index.html @@ -0,0 +1,57 @@ +--- +title: MDN の管理者の役割 +slug: MDN/Community/Roles/Admins +tags: + - MDN Meta + - ガイド + - コミュニティ +translation_of: MDN/Community/Roles/Admins +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">MDN の管理者 (または<strong>admin</strong>) の役割は高い権限レベルを伴っています。管理者は、サイトのプラットフォームのすべての機能を利用することができ、裏側にあるデータ構造に対してさえ限られたアクセスが可能です。この記事は、管理者に何ができるのか、またあなたがこれらの項目について助けが欲しい時に管理者に連絡する方法を記述しています。</span></p> + +<h2 id="Contacting_the_admins" name="Contacting_the_admins">管理者との連絡</h2> + +<p>管理者チームにメッセージを送る場合は、 <a href="mailto:mdn-admins@mozilla.org?subject=Admin%20help%20request">mdn-admins@mozilla.org</a> にメールを送ってください。</p> + +<h2 id="Admin_powers" name="Admin_powers">管理者の権限</h2> + +<p>管理者の役割には数々の特別な能力があります。それらの中には以下のものが含まれます:</p> + +<h3 id="Move_pages" name="Move_pages">ページを移動する</h3> + +<p>すべての管理者はページを(必要であれば下位のページも含むツリーごと)移動する移動する能力を持っています。</p> + +<h3 id="Delete_pages" name="Delete_pages">ページを削除する</h3> + +<p>すべての管理者はMDN's wiki (MDN) のいかなるページでも削除する権限を持ちます。しかし、もし、あなたがページを削除したい場合、単にページに"junk"というタグをつけるだけでいいです。<strong>消すような編集はしないでください</strong> (これをすることは本当に削除する必要があるのか確認することを難しくします)。もし、特に大きな問題 (攻撃的なコンテンツなど) があるなら、管理者に直接連絡してください。</p> + +<p>MDN 管理者はまた、削除したコンテンツを前の状態に戻す能力も持っています (少なくとも、削除されてからしばらく後にデータがシステムからパージされるまで)。もしあなたが間違って削除されたページを見つけたら、MDN 管理者に連絡をください。</p> + +<h3 id="Grant_and_remove_permissions" name="Grant_and_remove_permissions">権限を付与する/取り除く</h3> + +<p>管理者はユーザーの権限を変更することができます。これには決まった手順があります。詳しくは<a href="/ja/docs/MDN/Contribute/Tools/Template_editing">テンプレートの編集</a> を見てください。</p> + +<h3 id="Ban_and_unban_users" name="Ban_and_unban_users">ユーザーのアクセスを禁止/解除する</h3> + +<p>時折、ユーザーがトラブルを起こし、 MDN の編集から (一時的に、または恒久的に) 締め出す必要が生じることがあります。管理者は (トピックドライバー、翻訳チームリーダーと同様に) ユーザーのアクセスを禁止し、またユーザーのアクセス禁止を解除する権限を持っています。</p> + +<h3 id="Createedit_zones" name="Createedit_zones">ゾーンを作成/編集する</h3> + +<p>MDN の管理者は、新しくゾーンを作成したり、既存のページをゾーンに変換したり、ゾーンの情報と CSS を編集したりすることができます。ゾーンについてのさらなる情報については <a href="/ja/docs/MDN/Contribute/Tools/Zones">ゾーンの管理</a> ガイドを見てください。</p> + +<h3 id="Edit_user_information" name="Edit_user_information">ユーザーの情報を編集する</h3> + +<p>MDN 管理者はユーザーの情報を編集する限られた能力を持ち、ユーザーのインターフェイスからでは変更できない項目を変更することができます。ユーザー名を変更、古い形式の MDN アカウントに関連付けられているメールアドレスを変更する必要が生じた場合には、管理者に連絡し助けを求めることができます。<strong>すべてのリクエストに応えられるとは限らないため、必ずあなたの役に立つとはお約束できませんが。</strong></p> + +<h3 id="Add_or_change_calendar_entries" name="Add_or_change_calendar_entries">カレンダーの項目の作成や変更</h3> + +<p>MDN 管理者は <a href="https://mail.mozilla.com/home/publiccalendar@mozilla.com/MDN_Events.html">MDN イベントカレンダー</a>の更新、追記ができます。あなたのチームでカレンダーに書いて欲しい会議があれば、または書かれているイベントにおかしな点があれば、管理者に知らせてください、対応します。</p> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li><a href="/ja/docs/MDN/Community/Roles/Topic_driver_role/Drivers_and_curators">トピックドライバーと キュレーター</a></li> + <li><a href="/ja/docs/MDN/Community/Roles/Localization_driver_role">翻訳ドライバーの役割</a></li> +</ul> diff --git a/files/ja/mdn/community/roles/index.html b/files/ja/mdn/community/roles/index.html new file mode 100644 index 0000000000..4d54783057 --- /dev/null +++ b/files/ja/mdn/community/roles/index.html @@ -0,0 +1,21 @@ +--- +title: コミュニティでの役割 +slug: MDN/Community/Roles +tags: + - Community + - Landing + - MDN Meta + - NeedsTranslation + - TopicStub +translation_of: MDN/Community/Roles +--- +<div>{{MDNSidebar}}</div><p>MDN コミュニティには数々の役割が存在し、それぞれの役割に担うべき責任があります。</p> + +<p>（訳注：日本語訳がないため、表示されていない下位のページがあります）</p> + +<p>{{LandingPageListSubPages()}}</p> + +<dl> + <dt> </dt> + <dt> </dt> +</dl> diff --git a/files/ja/mdn/community/roles/localization_driver_role/index.html b/files/ja/mdn/community/roles/localization_driver_role/index.html new file mode 100644 index 0000000000..513e78999e --- /dev/null +++ b/files/ja/mdn/community/roles/localization_driver_role/index.html @@ -0,0 +1,71 @@ +--- +title: 翻訳ドライバの役割 +slug: MDN/Community/Roles/Localization_driver_role +tags: + - Community + - Guide + - MDN Meta + - l10n +translation_of: MDN/Community/Roles/Localization_driver_role +--- +<div>{{MDNSidebar}}</div> + +<p>MDN 翻訳ドライバは、ある言語またはロケールにおける MDN の文書化活動を調整し、リードします。 MDN の文書構造について、そして翻訳者と Mozilla の関心について、常に知らせを受け取る立場です。翻訳ドライバ自身がそのロケールについてのすべての翻訳をこなす必要はなく、実際には翻訳に関心を持つ貢献者のグループを集めて、グループの中でのタスクの調整を行うことが求められています。<a href="/ja/docs/MDN/Contribute/Localize/Localization_projects">各言語のローカライゼーションプロジェクト</a> に翻訳の対象となっているロケールと現在の翻訳ドライバの一覧があります。</p> + +<h2 id="なぜ翻訳ドライバになるのか？">なぜ翻訳ドライバになるのか？</h2> + +<p>翻訳ドライバになることで、コミュニティーをより深く理解し、そして Mozilla があなたの言語の社会において、どのように認識されるかに強い影響を持つ機会を得ることになります。この専門知識を現在の仕事で活かすことができるかもしれませんし、あるいは、異なった仕事を手にする助けとなるかもしれません。</p> + +<p>加えて、翻訳ドライバになれば、あなたはウェブの品質を高めるための力となることができます。</p> + +<h2 id="翻訳ドライバになるには">翻訳ドライバになるには</h2> + +<p>まだ翻訳ドライバがいないロケールの翻訳ドライバになるには、始めにいくつかの資格を満たすことが必要です:</p> + +<ul> + <li>ロケールの言語に関する専門知識がある。</li> + <li>ロケールで活発に貢献している (少なくとも月 1 回)。</li> + <li>さまざまな地域分散コミュニティとコミュニケーションをとることができる。</li> +</ul> + +<p>翻訳ドライバになるための最善の方法は、翻訳ドライバと同様に行動することです。翻訳ドライバのタスクのほとんどは、特別な能力や承認を必要としません。</p> + +<p>これらの要件を満たしたら、特定のロケールの翻訳ドライバになりたいことを、ロケールに対して何を行う必要があるかやあなたの資格の概要の説明を添えて <a href="https://discourse.mozilla-community.org/c/mdn">MDN ディスカッションフォーラム</a> に投稿できます。資格を満たしていれば、私たちはあなたが新しい特権を自由に使用する方法の基礎を得て養成されるように対処します。</p> + +<h3 id="すでにいる翻訳ドライバを手伝うには">すでにいる翻訳ドライバを手伝うには</h3> + +<p>ロケールごとの翻訳ドライバの数に上限はありません。もちろん、複数いる場合には協調して働く必要がありますが。 :-) ですから、彼らを手伝うことをためらう必要はありません: コンテンツに入り込む、スパム、エラーを監視したり、新たに翻訳された記事の手直しをしたり、すでに翻訳された記事の更新をしたりなど、手伝える仕事はいろいろあります。</p> + +<h2 id="責務">責務</h2> + +<p>翻訳ドライバの役割には、いくつかの重要な責務が伴います。その一部として:</p> + +<ul> + <li>翻訳作業が確実に完了するように、および人々が偶然にも同じものを 2 回翻訳してしまわないように、翻訳による貢献のコミュニティで調整します。wiki だけでなく MDN ウェブサイトの UI の翻訳について、ロケールの新たな貢献者を募集および採用します。</li> + <li>翻訳したページの整理、ページ構造のエラーおよび文書の階層構造の修正。重要なページの翻訳方針などを翻訳者のコミュニティと議論します。マクロの翻訳も忘れないようにしてください。</li> + <li>MDNコミュニティへのドキュメントの状態や進捗の報告。具体的には、<a href="https://discourse.mozilla-community.org/c/mdn">MDN ディスカッションフォーラム</a> での議論への参加などを通じて行います。</li> + <li>できるだけ多くの記事を翻訳してください。あなたが全てをやる必要はありませんが、いくらかでもできるのであれば、全体の助けになります！</li> +</ul> + +<h2 id="権限">権限</h2> + +<p>MDN に登録されたユーザーに共通する権限(例えば、変更を元に戻す)に加えて、翻訳ドライバは次のような権限を持っています:</p> + +<ul> + <li>ページ、またはページのツリーを移動する</li> + <li>添付ファイルをアップロードする、または操作する</li> + <li>KumaScript マクロを編集する</li> +</ul> + +<p>将来、新しい権限を追加する計画があります。例えば、貢献者のリストにアクセスできるようにする、スパマーからのアクセスを禁止するための操作を可能にする等です。</p> + +<h2 id="役割から去る場合には">役割から去る場合には</h2> + +<p>翻訳ドライバになった後、いつまでもその役割にとどまる必要はありません。あなたの関心、優先順位、使える時間は変化していくでしょうし、それはそれで構いません。翻訳ドライバとしての活動を続けられないことが予測できた場合には (もしくは、すでにやめていることに気づいた場合には)、次の手順を踏んでください。:</p> + +<ul> + <li>MDN 文書化プロジェクトのリーダーである <a href="https://developer.mozilla.org/en-US/profiles/chrisdavidmills">Chris Mills</a> (または他の MDN 管理者の誰か) に連絡し、翻訳ドライバの役割から降りることを伝えてください</li> + <li>可能であれば他のアクティブな貢献者に、翻訳ドライバの役割を引き受けるよう依頼してください。その方が同意した場合は MDN 文書化プロジェクトのリーダーに、新しい方が役割を受け入れることを知らせてください</li> +</ul> + +<p>2ヶ月以上にわたって MDN (と MDN ディスカッションフォーラム) での活動がない場合、翻訳ドライバとしての活動を続けるかどうかの意志を確認するための連絡が来るかもしれません。3ヶ月以上活動がなく、合理的だと認められる時間内に応答しない翻訳ドライバについては、この役割から除名されることがあります。</p> diff --git a/files/ja/mdn/community/roles/mentor_role/index.html b/files/ja/mdn/community/roles/mentor_role/index.html new file mode 100644 index 0000000000..a4088f61e7 --- /dev/null +++ b/files/ja/mdn/community/roles/mentor_role/index.html @@ -0,0 +1,66 @@ +--- +title: Mentor role +slug: MDN/Community/Roles/Mentor_role +tags: + - Community + - Guide + - MDN Meta + - NeedsTranslation + - TopicStub +translation_of: MDN/Community/Roles/Mentor_role +--- +<div>{{MDNSidebar}}</div> + +<p>An MDN mentor is a person committed to helping new contributors in a particular topic area and leading documentation work on MDN in that topic area. Mentors stay informed about the priorities and contribution activities in their topic area. They do not have to do all documentation work related to their topic themselves, and in fact, they are committed to gathering a group of contributors interested in the topic, delegating tasks among the group, and helping empower new contributors.</p> + +<h2 id="Becoming_a_mentor">Becoming a mentor</h2> + +<p>To become a mentor for a topic, you first need to meet certain qualifications:</p> + +<ul> + <li>Expertise with the topic</li> + <li>Active contributor to the topic (at least once a month)</li> + <li>Active on the <a href="https://developer.mozilla.org/en-US/docs/MDN/Community#Get_into_IRC">#mdn</a> IRC channel and the <a href="https://discourse.mozilla-community.org/c/mdn">MDN discussion forum</a></li> +</ul> + +<p>Once you have met those requirements, you can post on the <a href="https://discourse.mozilla-community.org/c/mdn">MDN discussion forum</a> that you would like to become the mentor for a given topic, with an explanation of what topic you would like to mentor and an overview of your qualifications. If you meet the qualifications, we will work with you to get you set up and trained in the basics of how to use the new privileges at your disposal.</p> + +<div class="note"> +<p><strong>Tip:</strong> If you want to become a mentor, just start acting like one! If you do a good job at it, you can practically be ensured that we will beg you to stay on in the role!</p> +</div> + +<h3 id="Are_mentors_different_than_topic_drivers">Are mentors different than topic drivers?</h3> + +<p>Both role are very close and have similar privileges and responsibilities. The difference is mainly in their commitment. For a given topic, <a href="/en-US/docs/MDN/Contribute/Topic_driver_role">topic drivers</a> lead the documentation and its content where mentors support and empowered the community of contributors around that topic. The two roles are complementary and work hand in hand most of the time.</p> + +<h2 id="Responsibilities">Responsibilities</h2> + +<p>The mentor role comes with a number of important responsibilities. Among them:</p> + +<ul> + <li>Help new contributors and answer their questions</li> + <li>Coordinate the writing community contributing to the documentation for the topic, to ensure that work gets done and that people don't accidentally document the same thing twice.</li> + <li>Share with the MDN community the progress and state of the documentation work, by participating in discussions on the <a href="https://discourse.mozilla-community.org/c/mdn">MDN discussion forum</a>, and so forth.</li> + <li>Engage and support new contributors to build a strong team of awesome contributors.</li> +</ul> + +<h2 id="Privileges">Privileges</h2> + +<p>In addition to the privileges available to all authenticated users on MDN, mentors have these additional privileges:</p> + +<ul> + <li>Move pages or trees of pages</li> + <li>Upload and manage file attachments</li> + <li>Edit KumaScript macros</li> +</ul> + +<h2 id="Leaving_the_role">Leaving the role</h2> + +<p>After you become a mentor, you don't have to stay in the role forever. Your interest, priorities, and available time may change, and that's OK. If you foresee that you won't continue as a mentor (or you realize that you have already stopped), please take the following steps:</p> + +<ul> + <li>Contact <a href="/en-US/profiles/chrisdavidmills">Chris Mills</a>, the MDN Documentation Lead, to notify him that you are stepping down as mentor.</li> + <li>If possible, ask someone else who is an active contributor in your topic area to step into the mentor role. If that person agrees, notify the MDN Documentation Lead of the new person taking the role.</li> +</ul> + +<p>If you haven't been active on MDN (or on the MDN discussion forum) in two months, you might be contacted to confirm that you want to continue as mentor. Mentors who are inactive for three months, or do not respond in a reasonable time when contacted, may be removed from their role.</p> diff --git a/files/ja/mdn/community/roles/mentor_role/mentors/index.html b/files/ja/mdn/community/roles/mentor_role/mentors/index.html new file mode 100644 index 0000000000..e959491231 --- /dev/null +++ b/files/ja/mdn/community/roles/mentor_role/mentors/index.html @@ -0,0 +1,264 @@ +--- +title: MDN のメンター +slug: MDN/Community/Roles/Mentor_role/Mentors +tags: + - Community + - MDN Meta + - Reference +translation_of: MDN/Community/Roles/Mentor_role/Mentors +--- +<div>{{MDNSidebar}}</div> + +<p>MDN コミュニティはメンターたちが積極的に支援しています。メンターは協力者に対して MDN を過ごしやすくしたり、協力を楽しんだりすするために道案内することで支援するためにいます。</p> + +<p>支援が必要な場合、メンターは支援をするためにいます。</p> + +<p>常に、もっと支援を行うことができます。 MDN のメンターになりたい場合は、活発に活動し、私たちに注意を払えば、望むところで会えるでしょう。そして、その域に達したことを <a href="https://developer.mozilla.org/profiles/sheppy">sheppy</a> (Docs チームのリーダー) に知らせてください。</p> + +<p>メンターになるために何をするのか、どのような役割を果たすかの詳細については、<a href="/ja/docs/MDN/Contribute/Mentor_role">メンターの役割</a>を参照してください。</p> + +<h2 id="Mentors" name="Mentors">メンター</h2> + +<p>MDN における現在のメンター全員の一覧です。</p> + +<table class="standard-table"> + <thead> + <tr> + <td class="header">トピック</td> + <td class="header">メンター名</td> + <td class="header">MDN ID</td> + <td class="header">IRC ユーザー名</td> + <td class="header">メールアドレス</td> + <td class="header">Twitter</td> + </tr> + </thead> + <tbody> + <tr> + <td>Accessibility</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>Add-on SDK</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>CSS</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>Developer tools</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>DOM</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>Emscripten</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>Firefox (desktop and mobile)</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>Firefox OS</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>Games</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td colspan="1" rowspan="1"><a href="/ja/docs/Glossary">用語集</a></td> + <td>Biraj Karmakar</td> + <td><a href="https://developer.mozilla.org/profiles/Biraj">Biraj</a></td> + <td>biraj</td> + <td>brnet00@gmail.com</td> + <td>@birajkarmakar</td> + </tr> + <tr> + <td>HTML</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>JavaScript</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>Learning Area</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>Marketplace</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>MathML</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>Persona & Firefox accounts</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>SVG</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>Web APIs</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>Web Apps</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + </tbody> +</table> + +<h2 id="MDN_Admin" name="MDN_Admin">MDN の管理者</h2> + +<p>MDN の管理者は一種のスーパーメンターです。すべての質問に回答し、編集時に行われた間違いを修正します。 <a href="/ja/docs/MDN/Community">IRC または MDN のメーリングリスト</a>にもよく現れます。いつ現れるかはタイムゾーンがヒントになりますが、保証はありません。</p> + +<table class="standard-table"> + <thead> + <tr> + <td class="header">タイムゾーン</td> + <td class="header">Curator name</td> + <td class="header">MDN ID</td> + <td class="header">IRC ユーザー名</td> + <td class="header">メールアドレス</td> + <td class="header">Twitter</td> + </tr> + </thead> + <tbody> + <tr> + <td><a href="http://www.timeanddate.com/time/zones/cet" rel="external">CET (UTC+1h)</a></td> + <td>Florian Scholz</td> + <td><a href="/profiles/fscholz">fscholz</a></td> + <td>fscholz</td> + <td>fscholz mozilla dot com</td> + <td><a href="http://twitter.com/floscholz">@floscholz</a></td> + </tr> + <tr> + <td><a href="http://www.timeanddate.com/time/zones/cet" rel="external">CET (UTC+1h)</a></td> + <td>Jeremie Patonnier</td> + <td><a href="/profiles/Jeremie">Jeremie</a></td> + <td>Jeremie</td> + <td><a href="mailto:jpatonnier@mozilla.com">jpatonnier@mozilla.com</a></td> + <td><a href="https://twitter.com/JeremiePat" rel="external">@JeremiePat</a></td> + </tr> + <tr> + <td><a href="http://www.timeanddate.com/time/zones/gmt" rel="external">GMT (UTC+0h)</a></td> + <td>Jean-Yves Perrier</td> + <td><a href="/profiles/teoli">teoli</a></td> + <td>teoli</td> + <td><a class="link-mailto" href="mailto:jperrier@mozilla.com" rel="freelink">jperrier@mozilla.com</a></td> + <td><a class="link-https" href="https://twitter.com/Teoli2003" title="https://twitter.com/Teoli2003">@Teoli2003</a></td> + </tr> + <tr> + <td><a href="http://www.timeanddate.com/time/zones/gmt" rel="external">GMT (UTC+0h)</a></td> + <td>Chris Mills</td> + <td><a href="/profiles/chrisdavidmills">chrisdavidmills</a></td> + <td>chrismills</td> + <td><a href="mailto:cmills@mozilla.com">cmills@mozilla.com</a></td> + <td><a href="http://twitter.com/chrisdavidmills" title="http://twitter.com/chrisdavidmills">@chrisdavidmills</a></td> + </tr> + <tr> + <td><a href="http://www.timeanddate.com/time/zones/cst" rel="external">CST (UTC-6h)</a></td> + <td>Janet Swisher</td> + <td><a href="/profiles/jswisher">jswisher</a></td> + <td>jswisher</td> + <td><a href="mailto:jswisher@mozilla.com">jswisher@mozilla.com</a></td> + <td><a class="external" href="http://twitter.com/jmswisher" title="http://twitter.com/jmswisher">@jmswisher</a></td> + </tr> + <tr> + <td><a href="http://www.timeanddate.com/time/zones/cst" rel="external">CST (UTC-6h)</a></td> + <td>Eric Shepherd</td> + <td><a href="/profiles/sheppy">sheppy</a></td> + <td>sheppy</td> + <td><a href="mailto:eshepherd@mozilla.com">eshepherd@mozilla.com</a></td> + <td><a class="external" href="http://www.twitter.com/sheppy" title="http://www.twitter.com/sheppy">@sheppy</a></td> + </tr> + <tr> + <td><a href="http://www.timeanddate.com/time/zones/pst" rel="external">PST (UTC-8h)</a></td> + <td>Will Bamberg</td> + <td><a href="/profiles/wbamberg">wbamberg</a></td> + <td>wbamberg</td> + <td><a href="mailto:wbamberg@mozilla.com">wbamberg@mozilla.com</a></td> + <td></td> + </tr> + </tbody> +</table> diff --git a/files/ja/mdn/community/roles/topic_driver_role/index.html b/files/ja/mdn/community/roles/topic_driver_role/index.html new file mode 100644 index 0000000000..f4fc8c6935 --- /dev/null +++ b/files/ja/mdn/community/roles/topic_driver_role/index.html @@ -0,0 +1,81 @@ +--- +title: トピックドライバの役割 +slug: MDN/Community/Roles/Topic_driver_role +tags: + - MDN Meta + - ガイド + - コミュニティ +translation_of: MDN/Community/Roles/Topic_driver_role +--- +<div>{{MDNSidebar}}</div> + +<p>MDN トピックドライバは、特定のトピック分野の MDN に関する文書化活動を調整し、リードします。彼らは Mozilla、標準化団体、あるいは他のテクノロジ企業など、必要に応じて、トピック分野における新しい開発について常に情報を提供しています。トピックに関連するすべてのドキュメント作成作業を自分で行う必要はありません。実際、トピックに関心のある寄稿者のグループを集め、グループ間でタスクを委任することをお勧めします。 MDN の各トピック領域の担当者については、<a href="/ja/docs/MDN/Contribute/Documentation_topics_and_curators">ドキュメンテーションのトピックおよびキュレーター</a>のページを参照してください。</p> + +<h2 id="なぜトピックドライバになるのでしょうか。">なぜトピックドライバになるのでしょうか。</h2> + +<p>トピックドライバになることは、トピックに取り込まれる、または取り込まれる機会を与え、そのトピックが MDN にどのように提示されるかに大きな影響を与える機会を提供します。あなたは現在の仕事でこの専門知識を使うかもしれません、またはあなたが別の仕事を達成するのを助けるためかもしれません。</p> + +<p>In addition, as a topic driver, you can be a driving force to improve the quality of the Web.</p> + +<h2 id="Becoming_a_topic_driver">Becoming a topic driver</h2> + +<p>To become a topic driver for a topic that doesn't have one yet, you first need to meet certain qualifications:</p> + +<ul> + <li>Expertise with the topic</li> + <li>Active contributor to the topic (at least once a month)</li> + <li>Ability to communicate with a diverse, geographically distributed community</li> +</ul> + +<p>Once you've met those requirements, you can post on the <a href="https://discourse.mozilla-community.org/c/mdn">MDN discussion forum</a> that you'd like to become the driver for a given topic, with an explanation of what topic you'd like to drive and an overview of your qualifications. If you meet the qualifications, we'll work with you to get you set up and trained in the basics of how to use the new privileges at your disposal.</p> + +<div class="note"> +<p><strong>Tip:</strong> If a topic doesn't have a topic driver, and you want to become the topic's driver, just start acting like that topic's driver! If you do a good job at it, you can practically be ensured that we'll beg you to stay on in the role!</p> +</div> + +<h3 id="Helping_an_existing_topic_driver">Helping an existing topic driver</h3> + +<p>For topics that already have drivers, you can still be a big help! Most topics are large and broad enough that having many people contributing to the documentation and sample code is of incredible benefit. In fact, having multiple viewpoints on a topic is almost certainly going to improve the overall coverage of the topic.</p> + +<ul> + <li>Add new examples and improve any that are weak.</li> + <li>Update articles based on changes to specifications or implementation details.</li> + <li>Help coordinate discussions on the mailing lists.</li> + <li>Help monitor the content for spam, errors, and so forth.</li> +</ul> + +<h3 id="Are_topic_drivers_different_than_mentors">Are topic drivers different than mentors?</h3> + +<p>Both role are very close and have the same kind of privileges and responsibilities. The difference is mainly in their commitment. For a given topic, topic drivers lead the documentation and its content where <a href="/en-US/docs/MDN/Contribute/Mentor_role">mentors</a> support and empowered the community of contributors around that topic. They are complementary and work hand in hand most of the time.</p> + +<h2 id="Responsibilities">Responsibilities</h2> + +<p>The topic driver role comes with a number of important responsibilities. Among them:</p> + +<ul> + <li>Track specifications and implementations of the technology to know when the documentation needs to be updated.</li> + <li>Coordinate the writing community contributing to the documentation for the topic, to ensure that work gets done and that people don't accidentally document the same thing twice.</li> + <li>Share with the MDN community the progress and state of the documentation work, by participating in discussions on the <a href="https://discourse.mozilla-community.org/c/mdn">MDN discussion forum</a>, and so forth.</li> + <li>Contribute as much writing time as you reasonably can; you don't have to do all of it, but it's helpful if you can do some!</li> +</ul> + +<h2 id="Privileges">Privileges</h2> + +<p>In addition to the privileges available to all authenticated users on MDN (such as reverting changes, topic drivers have these additional privileges:</p> + +<ul> + <li>Move pages or trees of pages</li> + <li>Upload and manage file attachments</li> + <li>Edit KumaScript macros</li> +</ul> + +<h2 id="Leaving_the_role">Leaving the role</h2> + +<p>After you become a topic driver, you don't have to stay in the role forever. Your interest, priorities, and available time may change, and that's OK. If you foresee that you won't continue as a topic driver (or you realize that you have already stopped), please take the following steps:</p> + +<ul> + <li>Contact <a href="/en-US/profiles/chrisdavidmills">Chris Mills</a>, the MDN Documentation Lead, to notify him that you are stepping down as topic driver.</li> + <li>If possible, ask someone else who is an active contributor in your topic area to step into the topic driver role. If that person agrees, notify the MDN Documentation Lead of the new person taking the role.</li> +</ul> + +<p>If you haven't been active on MDN (or on the discussion forum) in two months, you might be contacted to confirm that you want to continue as topic driver. Topic drivers who are inactive for three months, or do not respond in a reasonable time when contacted, may be removed from their role.</p> diff --git a/files/ja/mdn/community/whats_happening/index.html b/files/ja/mdn/community/whats_happening/index.html new file mode 100644 index 0000000000..097057a686 --- /dev/null +++ b/files/ja/mdn/community/whats_happening/index.html @@ -0,0 +1,42 @@ +--- +title: 何が起きているかを追跡する +slug: MDN/Community/Whats_happening +tags: + - Beginner + - Community + - Guide + - MDN Meta +translation_of: MDN/Community/Whats_happening +--- +<div>{{MDNSidebar}}</div> + +<p>MDN は <a href="https://wiki.mozilla.org/MDN">MDN コミュニティ </a>によって運営されています。私たちが何をしているのかについて、私たちが情報を共有する方法をいくつか紹介します。</p> + +<h2 id="Blogs" name="Blogs">ブログ</h2> + +<dl> + <dt><a href="https://hacks.mozilla.org/" title="https://hacks.mozilla.org/">Mozilla Hacks</a></dt> + <dd>Web と Mozilla のテクノロジーと機能を詳細にカバーしたニュース。</dd> + <dt><a href="https://blog.mozilla.org/community/category/developer-engagement/">Engaging Developers</a></dt> + <dd>Mozilla の MDN に関連するコミュニティの間でのプロモーション活動や議論。</dd> +</dl> + +<h2 id="Streams_of_ephemera" name="Streams_of_ephemera">短期的な情報の発信</h2> + +<ul> + <li><a href="http://twitter.com/MozDevNet">@MozDevNet</a>: Mozilla Developer Network の興味深いページ、チュートリアル、ガイド、投稿募集、特徴的なアップデートやその他ニュースについて。</li> + <li><a href="https://twitter.com/mozhacks" title="https://twitter.com/mozhacks">@MozHacks</a>: 新しい web テクノロジー、良い HTML5 アプリ、Firefox 機能についてツイート。</li> + <li><a href="http://www.youtube.com/user/mozhacks" title="http://www.youtube.com/user/mozhacks">Mozilla Hacks (YouTube)</a></li> +</ul> + +<h2 id="Status_boards_and_dashboards" name="Status_boards_and_dashboards">ステータスボードとダッシュボード</h2> + +<p><a href="/ja/docs/MDN/Doc_status">Documentation status</a> ページを見て、MDN コンテンツをすべて横断的に見て何が起きているかを理解します。どの記事が書いたり更新したりする必要があり、どのトピックが手助けが要るのかや、もっと多くのことを見ることができます。</p> + +<h2 id="MDN_meetings" name="MDN_meetings">MDN ミーティング</h2> + +<p>MDN 関連のさまざまなプロジェクトとブロセスに関する進捗を追ったり共有したりする、多くの通常ミーティングがあります。<a href="https://wiki.mozilla.org/MDN/Meetings">MDN ミーティング wiki ページ</a>に記載されています。</p> + +<p>何が起こっているかを感じるのに、最も良いのは 2週間に 1 回水曜日の 10:00 に (10月-3月は UTC-0800、3月-10月は UTC-0700) <a href="irc://irc.mozilla.org/mdn" title="irc://irc.mozilla.org/devmo">#mdn</a> <a href="http://wiki.mozilla.org/IRC" title="http://wiki.mozilla.org/IRC">IRC</a> チャンネルで行われる MDN コミュニティミーティングに参加することです。<a href="https://wiki.mozilla.org/MDN/Meetings/Community" title="https://wiki.mozilla.org/MDN/Community_meetings">MDN コミュニティミーティング</a> wiki ページを見て、過去のアジェンダと記録を確認してください。</p> + +<p><a class="external text" href="https://www.google.com/calendar/embed?src=mozilla.com_2d35383434313235392d323530%40resource.calendar.google.com" rel="nofollow">Public MDN Events</a> のカレンダーには MDN コミュニティミーティング、doc sprints、その他 MDN 関連イベントが含まれています。Vidyo テレビ会議システムの「mdn」チャンネルでミーティングを見たら、<a href="https://v.mozilla.com/flex.html?roomdirect.html&key=gMM1xZxpQgqiQFNkUR3eBuHgxg">ウェブで会話に参加できます</a>。</p> diff --git a/files/ja/mdn/community/working_in_community/index.html b/files/ja/mdn/community/working_in_community/index.html new file mode 100644 index 0000000000..662d2321f4 --- /dev/null +++ b/files/ja/mdn/community/working_in_community/index.html @@ -0,0 +1,114 @@ +--- +title: コミュニティでの作業 +slug: MDN/Community/Working_in_community +tags: + - Community + - Guide + - MDN Meta +translation_of: MDN/Community/Working_in_community +--- +<div>{{MDNSidebar}}</div> + +<p>MDN の文書に関連して行われる、意味をなす規模での貢献の大部分は、いかに MDN コミュニティの一員として作業するかを知ることだといえます。この記事ではあなたが行う他の文書作成者、開発チームとのやりとりの多くで役に立つコツを紹介します。</p> + +<h2 id="General_etiquette_guidelines" name="General_etiquette_guidelines">一般的なエチケットのガイドライン</h2> + +<p>Mozilla コミュニティで作業する際の品行に関する、一般的なガイドラインを紹介します。</p> + +<ul> + <li>礼儀正しく! 意見が衝突する場面でも、私たちは同じ使命を持っているのです: ウェブをより良いものにすること。</li> + <li>頼むこと、要求するのではなく。要求するのではなく丁寧に支援を依頼すると、人々が助けてくれたり反応してくれたりする可能性がはるかに高まります。文書化の作業は重要であり、また開発コミュニティもそれを理解していますが、敬意を払わずにチームを扱うと、人間の本能として人々は不快で気難しい状態になる傾向があります。</li> + <li>文書化の緊急性の情報の必要性と、議論の参加者があなたを助けるために費やさなければならない時間の情報の必要性のバランスをとってください。必ずしもすぐに必要ないのであれば、会話に参加するほかの人たちを熱中させるほど詳しく押し通してはいけません。</li> + <li>あなたの要望によって接触した人々から貴重な時間をとることを意識して、時間を有効活用するようにしてください。</li> + <li>文化の違いに配慮してください。Mozilla は多国籍かつ多文化なチームでですので、あなたとは文化が異なる (と思われる) 人と対話するときは、コミュニケーション中にそのことを意識するようにしてください。</li> + <li>既存の会話を乗っ取るのではなく、新しい会話を始めてください。あなたが話す必要がある人々がそれに留意していても、無関係の会話に質問を挟み込まないでください。あなたには便利でも、あなたが話そうとしている人々を怒らせてしまい、理想に満たない結果になってしまうかもしれません</li> + <li>{{interwiki("wikipedia", "パーキンソンの凡俗法則")}} を避けてください。あなたの熱意が、いらだたせる学者まがいの行動にならないようにしてください。会話が厄介ではっきりした目的がないものになります。</li> +</ul> + +<h2 id="Be_tactful" name="Be_tactful">機転を利かせること</h2> + +<p>他者とのコミュニケーションでは、常に機転を利かせて敬意を表してください。</p> + +<h3 id="Politely_pointing_out_mistakes" name="Politely_pointing_out_mistakes">礼儀正しくミスを指摘する</h3> + +<p>誰かに連絡を取る目的が、その人たちに何か別のことをするように頼むことである場合、あるいはその人たちが行った誤り (特に、何度も行っている場合) を指摘することである場合は、メッセージを肯定的なコメントで始めてください。これはいわば打撃を和らげて、相手を悪者扱いするのではなく助けようとしていることを示します。</p> + +<p>例えば新しい貢献者がタグをつけずに多くのページを作成しており、あなたがその問題を指摘したい場合は、相手へのメッセージを以下のようにするとよいでしょう (それぞれのケースで変更しなければならない箇所に下線をつけています):</p> + +<blockquote> +<p>Hi, <u>MrBigglesworth</u>, I've been noticing your contributions to <u>the Wormhole API documentation</u>, and it's fantastic to have your help! I particularly like <u>the way you balanced your level of detail with readability</u>. That said, though, you could make these articles even better and more helpful if you <u>added the correct tags to the pages</u> as you go.</p> + +<p><u>See the MDN tagging guide (https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Tag) for details.</u></p> + +<p>Thanks again, and I look forward to your future contributions!</p> +</blockquote> + +<h2 id="Sharing_knowledge" name="Sharing_knowledge">知識を共有する</h2> + +<p>MDN プロジェクトに参加していると、何が行われているかや、コミュニティの他のメンバーが何に関わっているかを知ると役に立ちます。コミュニティ内で他者と対話することで、アイデア、更新状況などを得る (そして共有する) ことができます。また、誰が何を行ったかを知るのに役立つツールや情報リソースもあります。</p> + +<h3 id="Communication_channels" name="Communication_channels">コミュニケーションチャネル</h3> + +<p>コミュニティのメンバー (開発者と文書作成者のどちらも) と交流できる手段がいくつかあり、それぞれに固有のエチケットに関する決まりがいくらかあります。</p> + +<h4 id="Discourse">Discourse</h4> + +<p><a href="https://discourse.mozilla.org/c/mdn">MDN Discourse フォーラム</a>は、 MDN への協力についての一般的な質問を行い、議論を始めるのによい場所です。</p> + +<h4 id="Chat">Chat</h4> + +<p>Matrix チャットシステムを使用して、リアルタイムで連絡を取ることができます。 MDN のスタッフは <a href="https://chat.mozilla.org/#/room/#mdn:mozilla.org">MDN Web Docs ルーム</a> におり、ヨーロッパと北米の勤務日に活動しています。他のチャットルームを見て、興味のあるトピックに関わっている人を見つけましょう。</p> + +<h4 id="GitHub">GitHub</h4> + +<p>MDN で問題を見つけたり、質問したりしたい場合は <a href="https://github.com/mdn/sprints/issues">GitHub sprints repo issues</a> に問題を提出してください。これらの問題は、将来のある時点でトリアージされ、対処されることになります。</p> + +<h4 id="Email">Email</h4> + +<p>電子メールアドレスを持っている場合は、他の人々とプライベートなメール交換をすることもあります。</p> + +<div class="note"> +<p><strong>注記:</strong> 一般的に、あなたが文書化している技術に関する文書に誰かが電子メールアドレスを投稿した場合、個人的に電子メールアドレスを示された場合、あるいは広く知られた電子メールである場合は、受け入れ可能な "最初の連絡手段" が電子メールになります。あなたがそれを探し出さなければならない場合は、他に試みる連絡手段がまったくない場合を除いて、始めに Matrix やメーリングリストを使用する許可を得ることを試みましょう。</p> +</div> + +<h3 id="Content_status_tools" name="Content_status_tools">コンテンツの状態を示すツール</h3> + +<p>文書化の状態に関する情報を提供する、役に立つツールがいくつかあります。</p> + +<dl> + <dt><a href="/dashboards/revisions">リビジョンダッシュボード</a></dt> + <dd>リビジョンダッシュボードは、MDN のコンテンツの変更点を確認するためのすばらしいツールです。最近の履歴を見る、確認する期間を選択する、あるいはロケールや貢献者名やトピックでフィルタリングすることができます。リビジョンのセットを見ると、それぞれのリビジョンの変更点を調べる、ページをすばやく開く、全体の履歴を調べる、あるいは変更を取り消す (権限がある場合) ことができます。</dd> + <dt><a href="/ja/docs/MDN/Doc_status/Overview">文書化状態の概観</a></dt> + <dd><a href="/ja/docs/MDN/Doc_status/Overview">文書化状態の概観</a> ページは、状態を追跡するために設定された MDN の全領域のリストを、そこにさまざまな作業が必要なページがいくつあるかという情報とともに提供します。特定のトピック領域をクリックすると、タグがないページや特定の作業が必要であることを示すタグがついたページなど、作業が必要なコンテンツの詳しい一覧を確認できます。また、長期間更新されていないページや陳腐化したと思われるページ、その領域の文書に影響があると位置づけられているバグの一覧を見ることもできます。</dd> + <dt><a href="/ja/docs/MDN/Plans">文書化プロジェクトの計画</a></dt> + <dd>私たちは計画段階の、あるいは大規模で進行中の文書作成プロジェクトをいくつか抱えており、何を行う必要があるかを追跡し続けることを支援する計画文書を作成しました。</dd> + <dt><a href="https://tree.taiga.io/project/viya-mdn-durable-team">MDN Taiga</a></dt> + <dd>MDN のスタッフである執筆者は、現在および将来の文書化プロジェクトを管理するために Taiga と呼ばれるツールを使用します。私たちが何をしており、またどのように進めているかを見ることができます。さらに、すぐに起こしたプロジェクトが何であるかを見ることもできます。それらのいくつかはスタッフの執筆者が引き受けますが、希望であればあなたが引き受けることも自由です! MDN チームが従っているアジャイルプロセスについて、詳しくは <a href="https://wiki.mozilla.org/Engagement/MDN_Durable_Team/Processes">Mozilla wiki のプロセスのページ</a> をご覧ください。</dd> +</dl> + +<h2 id="The_development_community" name="The_development_community">開発コミュニティ</h2> + +<p>MDN 文書作成コミュニティのメンバーとして、開発者と管理者の関係でもっとも重要であると思われることは、開発者とともに開発および維持することです。開発者は私たちが開発するソフトウェアを作成しますが、もっとも役に立つ情報源でもあります。開発者とよい関係を維持することはとても重要です。彼らに好かれていれば、質問に早く、正確に、また徹底的に答える可能性が高まります!</p> + +<p>また、あなたは MDN の文書作成コミュニティを代表しています。文書作成チームとのすべての交流を良好にすることで、開発チームとのすばらしい作業場の関係を維持するようにしてください。</p> + +<p>関連して、適切な話し相手を見つけるための手段が、<a href="https://wiki.mozilla.org/Modules">モジュールオーナーの一覧</a> を見ることです。</p> + +<h2 id="The_writing_community" name="The_writing_community">文書作成者たちのコミュニティ</h2> + +<p>文書作成やのコミュニティは大規模です。きわめて頻繁に、あるいは大規模に貢献する方は比較的少数ですが、ときどき貢献する人々は数十人から数百人います。幸い、この方々は全体的にウェブ、Mozilla、文書化が純粋に好きなすばらしい人たちであり、交流することはほぼ容易です。</p> + +<p>MDN コミュニティについて詳しくは、<a href="/ja/docs/MDN/Community" title="Project:MDN/Contributing/Join_the_community">MDN コミュニティに参加する</a> の記事をご覧ください。</p> + +<p>他の執筆者と直接対話する機会が最も多い場所は <a href="https://discourse.mozilla.org/c/mdn">Discourse フォーラム</a>です。</p> + +<p>{{anch("General etiquette guidelines", "一般的なエチケットのガイドライン")}} を覚えておくことで、たいていの物事がとてもスムーズに進むことがわかるでしょう。</p> + +<h2 id="See_also" name="See_also">関連項目</h2> + +<ul> + <li><a href="/ja/docs/Project:MDN/Contributing" title="/ja/docs/Project:MDN/Contributing">MDN に貢献する</a></li> + <li><a href="/ja/docs/Project:MDN/Contributing/Join_the_community" title="/ja/docs/Project:MDN/Contributing/Join_the_community">MDN のコミュニティ</a></li> + <li><a href="http://matt.might.net/articles/how-to-email/" title="http://matt.might.net/articles/how-to-email/">How to send and reply to email</a></li> + <li><a href="http://blog.gerv.net/2012/10/how-to-be-a-mozillia/">How to be a Mozillian</a></li> +</ul> diff --git a/files/ja/mdn/contribute/faq/index.html b/files/ja/mdn/contribute/faq/index.html new file mode 100644 index 0000000000..93ba29bd8d --- /dev/null +++ b/files/ja/mdn/contribute/faq/index.html @@ -0,0 +1,30 @@ +--- +title: FAQ +slug: MDN/Contribute/FAQ +tags: + - MDN +translation_of: MDN/Contribute +--- +<div>{{MDNSidebar}}</div><h2 id="Mozilla_Developer_Networkとは何か">Mozilla Developer Networkとは何か ?</h2> + +<p><b>Mozilla Developer Network</b> (<b>MDN</b>)は(以前の<b>Mozilla Developer Center) </b>、web標準とMozillaプロジェクトの開発用文書化のための、Mozillaを支援するコミュニティwebサイトです。</p> + +<h2 id="新しく編集者として参加する方法は">新しく編集者として参加する方法は ?</h2> + +<p>MDNを編集する事の良い点を全て知るのは時間がかかりますが、今すぐに書き始める事ができます。コミュニティは新人に新しい事を学ぶように約束します。参加するには次の簡単な手順に従って下さい。</p> + +<ol> + <li>MDNのアカウントを作成します。</li> + <li><a href="https://lists.mozilla.org/listinfo/dev-mdc">dev-mdc</a> のメーリングリストを購読します (必須ではありませんが強く推奨されます)。</li> + <li>記事を編集する事で、最初の貢献を始めます。 (新しい記事も作成できますが、まずメーリングリストで協議してその記事が必要かを確認して下さい。)</li> + <li>レビューを待ち、それから学習します。</li> + <li>実習して定期的に貢献します。</li> +</ol> + +<h2 id="MDNを書くことのメリットは">MDNを書くことのメリットは ?</h2> + +<p>コミュニティと一緒に作業する体験が得られて、筆記のコミュニケーションスキルが上達するでしょう。あなたの履歴書に何行か追加するのにも役立つでしょう。</p> + +<h2 id="次にする事は">次にする事は ?</h2> + +<p>単に<a href="https://developer.mozilla.org/ja/docs/MDN/Getting_started#Option_2.3A_I_like_code">MDNに参加する</a>の記事にある手順に従って下さい。</p> diff --git a/files/ja/mdn/contribute/feedback/index.html b/files/ja/mdn/contribute/feedback/index.html new file mode 100644 index 0000000000..694d82c0fb --- /dev/null +++ b/files/ja/mdn/contribute/feedback/index.html @@ -0,0 +1,73 @@ +--- +title: MDN Web Docs についてのフィードバックを送る +slug: MDN/Contribute/Feedback +tags: + - Documentation + - Guide + - MDN + - MDN Meta +translation_of: MDN/Contribute/Feedback +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p>MDN Web Docs へようこそ! <span class="seoSummary">MDN Web Docs への提案があったり、利用していて問題があったりした場合は、ここが正しい場所です。あなたがフィードバックを送ることに関心を持っていることこそが、 あなたをよりMozilla コミュニティの一員として深く関わらせてくれますし、関心を持ってくださったことにあらかじめお礼申し上げます。</span></p> + +<p><span class="seoSummary">あなたの知見を提供するにはいくつかの選択肢があり、この記事は手助けになるでしょう。</span></p> + +<h2 id="Update_the_documentation" name="Update_the_documentation">文書を更新する</h2> + +<p>まず最初に、ドキュメントの問題を見つけたら、いつでも気軽にあなた自身で修正することができます。</p> + +<ol> + <li><a href="/ja/docs/MDN/Contribute/Howto/Create_an_MDN_account">ログイン</a>を <a href="https://github.com/">GitHub</a> から行います。</li> + <li>各ページの青い<strong>編集</strong>ボタンをクリックして、<a href="/ja/docs/MDN/Contribute/Editor">エディター</a>を開きます。</li> + <li>変更し終わったら、<strong>公開</strong>ボタンをクリックしてください。</li> +</ol> + +<p>ここのドキュメントは Wiki 内にあり、ボランティアと有給のスタッフのチームによって監督されています。なので遠慮せずに — 文法が完璧である必要ありません。失敗はきれいに修正されるでしょう。つまり何も問題ありません!</p> + +<p>MDN 文書化への協力について、もっと詳しい情報は、下記をご覧ください。</p> + +<ul> + <li><a href="/ja/docs/Project:Getting_started">作業の進め方</a>で何をするかの考えを得る</li> + <li><a href="/ja/docs/MDN/Contribute">MDN への協力</a></li> + <li><a href="/ja/docs/MDN/Contribute/Editor">MDN エディター UI のガイド</a></li> +</ul> + +<h2 id="Join_the_conversation" name="Join_the_conversation">会話に参加しましょう</h2> + +<p>私たちと話しましょう! MDN のコンテンツについて作業する他の人と連絡を取るための、いくつかの方法があります。 (訳注: 基本的に英語でのコミュニケーションとなります。)</p> + +<h3 id="Synchronous_Chat" name="Synchronous_Chat">(同期的な) チャット</h3> + +<p>MDN やそのコンテンツについての会話を <a href="https://wiki.mozilla.org/Matrix">Matrix</a> で行っています。会話に参加していただくことができます。</p> + +<p><a href="https://chat.mozilla.org/#/room/#mdn:mozilla.org">MDN Web Docs</a></p> + +<dl> + <dd>この部屋は、サイトの利用、サイト内のコンテンツの閲覧、サイト内のコンテンツへの協力など、 MDN の一般的な議論を行うための部屋です。記事の内容についての質問やコメント、見たい記事や作成したい記事などについて、文書作成チームと話したいことなどがあれば、ここで話し合ってください。</dd> +</dl> + +<h3 id="Asynchronous_Discussions" name="Asynchronous_Discussions">(非同期の) 議論</h3> + +<p><a href="https://discourse.mozilla-community.org/c/mdn">MDN discussion forum</a> で、長期にわたる議論を行っています。<a href="mailto://mdn@mozilla-community.org">mdn@mozilla-community.org</a> へ電子メールを送信すると、フォーラムに投稿できます。フォーラムに参加する場合は、議論に関する通知を電子メールで送信するかを選択することもできます。</p> + +<h2 id="Report_an_issue" name="Report_an_issue">問題を報告する</h2> + +<h3 id="Documentation_issues" name="Documentation_issues">文書の問題</h3> + +<p>問題を見つけても、何らかの理由により自分で修正できない場合、<a href="https://github.com/mdn/sprints/issues/new?template=issue-template.md&projects=mdn/sprints/2&labels=user-report" title="文書の内容の問題を報告">問題を報告</a>することもできます。このフォームは以下のようなあらゆる文書の問題に使用することができます。</p> + +<ul> + <li>単純な修正</li> + <li>内容の新しい部分全体に対する要求</li> + <li>不適切な内容の報告 (スパムや間違った場所での翻訳など)</li> +</ul> + +<p>前述のように、あなた自身で協力していただきたいところですが、この選択肢も同様に利用できます。</p> + +<h3 id="Site_issues" name="Site_issues">サイトの問題</h3> + +<p>MDN のウェブサイトの問題に遭遇した場合や、サイトの新機能のアイデアがある場合、 <a href="https://github.com/mdn/kuma/issues/new/choose">MDN 開発チームにチケットを発行</a>することもできます。</p> diff --git a/files/ja/mdn/contribute/getting_started/index.html b/files/ja/mdn/contribute/getting_started/index.html new file mode 100644 index 0000000000..0d0cde409c --- /dev/null +++ b/files/ja/mdn/contribute/getting_started/index.html @@ -0,0 +1,108 @@ +--- +title: MDN で始めよう +slug: MDN/Contribute/Getting_started +tags: + - Documentation + - Getting Started + - Guide + - MDN + - MDN Project + - MDN プロジェクト + - New Contributors + - 初心者 + - 新たな協力者 +translation_of: MDN/Contribute/Getting_started +--- +<div>{{MDNSidebar}}</div> + +<p id="What_is_MDN.3F"><span class="seoSummary">私たちは開発者のオープンなコミュニティであり、ブランドやブラウザー、プラットフォームを問わず、ウェブをより良くするリソースを構築しています。誰でも協力でき、それによってコミュニティはより強固なものとなります。ともに協力することで、ウェブをより良いものへ革新していく後押しを継続できます。ここから、あなたと始まります。</span></p> + +<p><span>MDN のすべての部分 (文書、デモ、そしてこのサイト自体) は、開発者のオープンなコミュニティによって作成されています。ぜひ参加してください。</span></p> + +<h2 id="3_simple_steps_to_MDN" name="3_simple_steps_to_MDN">MDN への簡単な 3 ステップ</h2> + +<p>MDN は Wiki であり、<strong>誰でも</strong>コンテンツを追加、編集することができます。プログラマーであったり、技術に精通していたりする必要はありません。簡単なこと (校正や誤字の修正) から、複雑なこと (API ドキュメントの執筆) まで、行うべき事はたくさんあります。</p> + +<p>協力するのは簡単で危険を伴いません。間違ってしまった場合でも、簡単に修正できます。出来栄えをどうすべきかわからなかったり、文法が完璧でなかったりしても、気にしないで！ MDN にあるコンテンツをできるだけ良くすることを専門とするチームがあります。誰かがやってきて、あなたの成果がきちんと丁寧に書かれているかどうか確認してくれます。あなたの知識を共有し、長所を活かしましょう。</p> + +<h3 id="Step_1_Create_an_account_on_MDN" name="Step_1_Create_an_account_on_MDN">ステップ 1 : MDN のアカウントを作成する</h3> + +<p>MDN への協力を開始するには、 MDN のアカウントが必要です。詳細は「<a href="/ja/docs/MDN/Contribute/Howto/Create_an_MDN_account">MDN アカウントを作成するには</a>」をご覧ください。</p> + +<h3 id="Step_2_Pick_a_task_to_complete" name="Step_2_Pick_a_task_to_complete">ステップ 2 : 完成させるタスクを選ぶ</h3> + +<p>ログインしたら、{{anch("Possible task types", "下記リスト")}}内の、色々なタスクの種類についての説明を読んで、最もやってみたいものを決めましょう。お好きなタスクを選択し、協力を開始することができます。</p> + +<h3 id="Step_3_Do_the_task" name="Step_3_Do_the_task">ステップ 3 : タスクを行う</h3> + +<p>やってみたいタスクを決めて、作業対象とする特定のページや、コード例などを探したら、あとはただやってみましょう！</p> + +<p>完璧にしようと悩まないで。 MDN に協力している他の方々が、見落とした間違いの修正を手伝ってくれます。何かを「実際に」行う前に試してみたいのであれば、 <a href="/ja/docs/Sandbox">Sandbox</a> ページで試してみることができます。進めていくにつれ疑問がわいたら、回答が得られるメーリングリストやチャットチャンネルについての情報が載っている<a href="/ja/docs/MDN/Community">コミュニティに関するページ</a>をご覧ください。</p> + +<p>終了したら、自由に他の項目を選ぶか、あるいは下記にある<a href="#Other_things_you_can_do_on_MDN">その他の MDN で行えること</a>をご覧ください。</p> + +<h2 id="Possible_task_types" name="Possible_task_types">協力できるタスクの種類</h2> + +<p>MDN に協力するための道は、スキルや興味によって複数のものがあります。中には怖気づいてしまうようなタスクもありますが、簡単にできる作業もたくさんあります。多くの作業は 5 分もかかりません。タスクとタスクに対する短い説明とともに、それぞれのタスクのタイプで必要となるおおよその平均時間を確認できます。</p> + +<h3 id="Option_1_I_like_words" name="Option_1_I_like_words">その1: 言葉が好き</h3> + +<p>既存のドキュメントのレビューや編集、またそれらに正しいタグをつけるといった協力ができます。</p> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Howto/Set_the_summary_for_a_page">ページの要約作成</a> (5-15分)</li> + <li><a href="/ja/docs/MDN/Contribute/Howto/Do_an_editorial_review">編集レビュー</a> (5-30分)</li> + <li><a href="/ja/docs/MDN/User_guide/Writing#Editing_an_existing_page">既存の記事を新しい情報に更新</a> (5分-1時間)</li> + <li><a href="/ja/docs/MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary">用語集で新規項目を書く</a> (15分-1時間)</li> + <li><a href="/ja/docs/MDN/Contribute/Howto/Create_and_edit_pages">新しい技術や API についての記事を書く</a> (30分-2時間)</li> + <li><a href="/ja/docs/MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web">ウェブの学習を補助する記事を書く</a> (1-3時間)</li> +</ul> + +<div class="note"><strong>メモ:</strong> 記事をレビューしたり、新しい記事を書いたりする際は、<a href="/en-US/docs/MDN/Contribute/Guidelines/Writing_style_guide">スタイルガイド</a>に目を通しておくようお願いします。その記事の一貫性を保証する助けになります。</div> + +<h3 id="Option_2_I_like_code" name="Option_2_I_like_code">その2: コードが好き</h3> + +<p>さらなるコード例が必要です！あるいはこのサイトのプラットホームである <a href="/ja/docs/MDN/Kuma">Kuma</a> の構築を手伝っていただくこともできます！</p> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Howto/Convert_code_samples_to_be_live">コード例を作成する</a> (30分)</li> + <li><a href="https://kuma.readthedocs.io/en/latest/installation.html">Kuma のビルド環境をセットアップ</a> (1時間)</li> + <li><a href="https://github.com/mozilla/kuma/blob/master/CONTRIBUTING.md">Kuma コードベースにパッチを送る</a> (1時間)</li> + <li><a href="/ja/docs/Web/Demos_of_open_web_technologies">新しいデモを投稿 </a>(1時間)</li> +</ul> + +<h3 id="Option_3_I_like_both_words_and_code" name="Option_3_I_like_both_words_and_code">その3: 言葉もコードも両方好き</h3> + +<p>新しい記事の執筆、技術的正確さのレビュー、文書の調整など、技術と言語の両方のスキルを必要とするタスクもあります。</p> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Howto/Tag_JavaScript_pages">JavaScript ページのタグ付けする</a> (5分)</li> + <li><a href="/ja/docs/MDN/About/Promote">自分のウェブサイトで MDN を宣伝</a> (5分)</li> + <li><a href="/ja/docs/MDN/Contribute/Howto/Do_a_technical_review">技術レビュー</a> (30分)</li> + <li><a href="/ja/docs/MDN/Contribute/Structures/API_references">API リファレンスの執筆または更新</a> (30分から2時間以上)</li> + <li><a href="/ja/docs/MDN/Contribute/Howto/Create_and_edit_pages#Creating_a_new_page">よく知っている主題の新しい記事を執筆する</a> (1時間以上)</li> + <li><a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables">リファレンスページのブラウザー互換性データを追加または更新</a> (30分から1時間)</li> +</ul> + +<h3 id="Option_4_I_want_MDN_in_my_language" name="Option_4_I_want_MDN_in_my_language">その4: 母国語の MDN が欲しい</h3> + +<p>MDN 上の全てのローカライゼーションと翻訳の作業は、素晴らしいボランティアコミュニティによって行われています。</p> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Localize/Translating_pages">ページを翻訳する</a> (2時間)</li> + <li><a href="/ja/docs/MDN/Contribute/Localize/Localization_projects">ローカライゼーションプロジェクト</a>に載っているローカライズ担当者と繋がりを持つ (30分)</li> +</ul> + +<h3 id="Option_5_I_found_some_wrong_info_but_I_dont_know_how_to_fix_it" name="Option_5_I_found_some_wrong_info_but_I_dont_know_how_to_fix_it">その5: 間違った情報を見つけたが修正方法が分からない</h3> + +<p>問題は<a class="external" href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Mozilla%20Developer%20Network">文書のバグをファイル</a>することで報告することができます。 (5分)</p> + +<p>問題には説明的な題名をつけてください。 (どこでリンクを見つけたかを書かずに「リンク切れ」と書くのは役に立ちません。プロのヒント: MDN の「リンク切れ」の多くは、まだ書かれていない記事へのリンクです)。 "Request type" の下のところは、問題を発見した場合は "Correction or update"、 MDN から何かが欠けている場合は "New documentation" の括弧の中に "x" を入れてください。 "Details" の下には、問題について、およびどこで正しい情報が見つかるか、知っている限り、時間が許す限り多くの情報を書いてください。これには、ウェブリンクだけでなく、人 ("誰と誰に聞く") を含めることができます。</p> + +<h2 id="Other_things_you_can_do_on_MDN" name="Other_things_you_can_do_on_MDN">その他の MDN でできること</h2> + +<ul> + <li><a href="/ja/docs/MDN/Community">MDN コミュニティに参加</a>する。</li> + <li>他の人があなたについて良く知ってもらえるように、<a href="/ja/profile">プロフィールを記入</a>する。</li> + <li><a href="/ja/docs/MDN/Contribute">MDN への協力方法</a>について学ぶ。</li> +</ul> diff --git a/files/ja/mdn/contribute/howto/add_or_update_browser_compatibility_data/index.html b/files/ja/mdn/contribute/howto/add_or_update_browser_compatibility_data/index.html new file mode 100644 index 0000000000..110eb7b20f --- /dev/null +++ b/files/ja/mdn/contribute/howto/add_or_update_browser_compatibility_data/index.html @@ -0,0 +1,35 @@ +--- +title: ブラウザーの互換性データを追加もしくは更新する方法 +slug: MDN/Contribute/Howto/Add_or_update_browser_compatibility_data +tags: + - Guide + - Howto + - MDN Meta +translation_of: MDN/Contribute/Howto/Add_or_update_browser_compatibility_data +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p class="summary">ウェブ機能のブラウザー互換性に関する情報がある場合、もしくは調査や実験を行う意思と能力がある場合は、<a class="external external-icon" href="https://github.com/mdn/browser-compat-data/" rel="noopener">MDN の Browser Compatibility Data</a> (BCD) の更新を手伝うことができます。</p> + +<dl> + <dt>どこで行う必要があるのか？</dt> + <dd> + <p>MDN でのブラウザー互換性情報の改善を手助けする方法は以下のような方法があります:</p> + + <ul> + <li>BCD リポジトリーにまだ含まれていないウェブ機能のデータを追加する。</li> + <li>ブラウザーの新しいバージョンへの変更や既存データの誤りの修正、または特定のテクノロジーの機能の更新に基づいた新しい情報で既存のデータを更新する。</li> + <li><a class="external external-icon" href="https://github.com/mdn/browser-compat-data/issues" rel="noopener">Github に送信された BCD の問題</a>に対処するためにプルリクエストを送信する。</li> + </ul> + </dd> + <dt>そのタスクをするために知っておくべきことは何か?</dt> + <dd> + <ul> + <li>Github の使い方に精通していること</li> + <li>JSON の使用に関する知識</li> + <li>様々なブラウザーでのウェブ標準機能の互換性に関する情報、もしくはテストする機能。"古い" 互換性テーブルデータを JSON に変換することも可能。</li> + </ul> + </dd> + <dt>タスクを実行する手順は何か？</dt> + <dd>Github の BCD リポジトリーを構成する <a class="glossaryLink" href="/ja/docs/Glossary/JSON" title="JSON: The JavaScript Object Notation (JSON) is a data-interchange format. Although not a strict subset, JSON closely resembles a subset of JavaScript syntax. Though many programming languages support JSON, JSON is especially useful for JavaScript-based apps, including websites and browser extensions.">JSON</a> ファイルを更新する方法の詳細については、<a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables">互換性テーブルに関する記事</a>を参照してください。特にヘルプを探している問題のリストについては、<a class="external external-icon" href="https://github.com/mdn/browser-compat-data/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22" rel="noopener">"Help Wanted" タグで Github の issue</a> を探してください。</dd> +</dl> diff --git a/files/ja/mdn/contribute/howto/convert_code_samples_to_be_live/index.html b/files/ja/mdn/contribute/howto/convert_code_samples_to_be_live/index.html new file mode 100644 index 0000000000..3f8029ddac --- /dev/null +++ b/files/ja/mdn/contribute/howto/convert_code_samples_to_be_live/index.html @@ -0,0 +1,36 @@ +--- +title: コードサンプルを "ライブ" に変換するには +slug: MDN/Contribute/Howto/Convert_code_samples_to_be_live +tags: + - Beginner + - Howto + - MDN Meta +translation_of: MDN/Contribute/Howto/Convert_code_samples_to_be_live +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">MDN には "<a href="/ja/docs/MDN/Contribute/Structures/Live_samples">ライブサンプル</a>" システムがあり、ここではコードサンプルが、そのサンプルの出力を直接表示するのに使われます。しかし、既存の記事にはこのシステムをまだ使っていないコードサンプルが多々あり、変換する必要があります。</p> + +<p><span class="seoSummary">ライブサンプルは、サンプルの出力がどのようなものかを見ることができ、ドキュメントをよりダイナミックで教育的なものにできます。このガイドは既存サンプルを取り上げて、 "ライブ" 動作を追加する方法を掲載します。</span></p> + +<dl> + <dt><strong>どこのページに行う必要があるか?</strong></dt> + <dd><a href="/ja/docs/tag/NeedsLiveSample">NeedsLiveSample</a> とタグ付けられた記事。</dd> + <dt><strong>タスクを行うのにどんな知識が必要か?</strong></dt> + <dd> + <ul> + <li>コードサンプルに応じて、 HTML, CSS 及び/あるいは JavaScript を理解すること</li> + <li>MDN 記事内の <a href="/ja/docs/MDN/Contribute/Tools/KumaScript">KumaScript</a> マクロを使う能力</li> + </ul> + </dd> + <dt><strong>タスクを実行するステップは?</strong></dt> + <dd> + <ol> + <li><a href="/ja/docs/tag/NeedsLiveSample">NeedsLiveSample</a> とタグ付けされていて、あなたが慣れていると感じる機能向けのコードサンプルがある記事の一覧から1つ選ぶ。</li> + <li>コードサンプルが "ライブ" となるよう変換する。</li> + <li>以前にサンプル出力を表示するために使われていた、あらゆるコードや画像を削除する。</li> + </ol> + </dd> +</dl> + +<p>ライブサンプルの作成と編集についての詳細情報は、 <a href="/ja/docs/MDN/Contribute/Structures/Live_samples">ライブサンプルシステムの使用</a>を参照してください。</p> diff --git a/files/ja/mdn/contribute/howto/create_an_interactive_exercise_to_help_learning_the_web/index.html b/files/ja/mdn/contribute/howto/create_an_interactive_exercise_to_help_learning_the_web/index.html new file mode 100644 index 0000000000..00d20765d7 --- /dev/null +++ b/files/ja/mdn/contribute/howto/create_an_interactive_exercise_to_help_learning_the_web/index.html @@ -0,0 +1,183 @@ +--- +title: インタラクティブな学習用エクササイズを作成する方法 +slug: MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web +translation_of: MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p>When learning the web, it's important to rely on active learning content. Such content is made to help with learning something pro-actively. It can be exercises, live hackable examples, tasks to perform, assessments, etc. In short, anything that can help someone to actively understand something.</p> + +<p>There is no straight forward way to create such content. For example many third party tools exist that can help you create live hackable examples (see: <a href="https://jsfiddle.net/" rel="external">JSFiddle</a>, <a href="https://codepen.io/">CodePen</a>, <a href="http://dabblet.com/">Dabblet</a>, etc.) that you can link from MDN articles. If you want to create more advanced comprehensible exercises, you can easily use <a href="https://thimble.mozilla.org" rel="external">Thimble</a> from the WebMaker project.</p> + +<p>Currently, MDN does not have an easy tool to author such active content. However, if you are a coder you can use the current MDN features to create custom active learning content. Read on to see how to do that.</p> + +<h2 id="MDN_ライブサンプル">MDN ライブサンプル</h2> + +<p>MDN has a very cool feature called <strong>live samples</strong>. It's a mechanism that turns any HTML, CSS, and JavaScript code inside an MDN page into its executed equivalent. Before using it, you should read over <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Using the live sample system</a>, which is our complete documentation for building them. While they're easy to do, there are quirks and tricks you'll learn along the way.</p> + +<p>What is interesting is that it's really easy to tweak that feature to use it in order to embed any kind of tool or utility you want into an MDN page.</p> + +<h3 id="Hidden_code">Hidden code</h3> + +<p>The first way to use a code sample to create active learning content is to edit the page where you want to add your content. Use the Live Sample feature to create your content as you wish. Don't bother with the code complexity you could write; just create what you need. Once your content is ready, just switch to the editor code view and surround your code with a simple {{HTMLElement('div')}} element with the class <code>hidden</code>. By doing so, your code won't be displayed but your live sample remains accessible and displayable.</p> + +<p>Let's see a simple example:</p> + +<div class="moreinfo"> +<p>Click on the following square to randomly change its color or just type a hexadecimal code color</p> + +<div class="hidden"> +<h4 id="hidden_code_example">hidden code example</h4> + +<h5 id="HTML">HTML</h5> + +<pre class="brush: html"><div class="square"> + #<input class="color"> +</div></pre> + +<h5 id="CSS">CSS</h5> + +<pre class="brush: css">body { + padding: 10px; + margin : 0; +} + +.square { + width : 80px; + height : 80px; + padding: 10px; + background-color: black; + color: white; + text-align: center; +} + +.color { + width: 60px; + text-transform: uppercase; +} +</pre> + +<h5 id="JS">JS</h5> + +<pre class="brush: js">function setColor(color) { + document.querySelector('.square').style.backgroundColor = '#' + color; + document.querySelector('.color').value = color; +} + +function getRandomColor() { + var color = Math.floor(Math.random() * 16777215); + return color.toString(16); +} + +function getInputColor() { + var value = document.querySelector('.color').value; + var color = Number('0x' + color); + if (color === +color) { + return color.toString(16); + } + return value; +} + +document.addEventListener('click', function () { + setColor(getRandomColor()); +}); + +document.addEventListener('keyup', function () { + setColor(getInputColor()); +}); +</pre> +</div> +{{EmbedLiveSample('hidden_code_example', 120, 120)}}</div> + +<p>If you take a look at that page HTML code with the MDN editor, you'll see the exact following HTML code:</p> + +<pre class="brush: html"><div class="moreinfo"> +<p>Click on the following square to randomly change its color or just type an hexadecimal code color</p> + +<div class="hidden"> +<h4 id="hidden_code_example">hidden code example</h4> + +<h5 id="HTML">HTML</h5> + +<pre class="brush: html"> +&lt;div class="square"&gt; + #&lt;input class="color"&gt; +&lt;/div&gt;</pre> + +<h5 id="CSS">CSS</h5> + +<pre class="brush: css"> +body { + padding: 10px; + margin : 0; +} + +.square { + width : 80px; + height : 80px; + padding: 10px; + background-color: black; + color: white; + text-align: center; +} + +.color { + width: 60px; + text-transform: uppercase; +} +</pre> + +<h5 id="JS">JS</h5> + +<pre class="brush: js"> +function setColor(color) { + document.querySelector('.square').style.backgroundColor = '#' + color; + document.querySelector('.color').value = color; +} + +function getRandomColor() { + var color = Math.floor(Math.random() * 16777215); + return color.toString(16); +} + +function getInputColor() { + var value = document.querySelector('.color').value; + var color = Number('0x' + color); + if (color === +color) { + return color.toString(16); + } + return value; +} + +document.addEventListener('click', function () { + setColor(getRandomColor()); +}); + +document.addEventListener('keyup', function () { + setColor(getInputColor()); +}); +</pre> +</div> + +\{{EmbedLiveSample('hidden_code_example', 120, 120)}} +</div></pre> + +<p>You can see a more advance example of such a tweak on <a href="/en-US/docs/Web/API/Canvas_API#JavaScript">the Canvas API page</a>.</p> + +<h3 id="Code_from_outside_the_page">Code from outside the page</h3> + +<p>The previous example is okay if you want to embed basic active learning content. However, if you want to deal with complex code, it can become a bit awkward to deal with that <code>hidden</code> class wrapper.</p> + +<p>So another option is to write the code of your learning content on an MDN page and then embed it into another page. To do this we can use the {{TemplateLink("EmbedDistLiveSample")}} macro instead of the {{TemplateLink("EmbedLiveSample")}} macro.</p> + +<p>Let's how that sample looks when configured as if it were being embedded from a remote origin:</p> + +<div class="moreinfo"> +<p>Click on the following square to randomly change its color or just type a hexadecimal code color</p> +{{EmbedLiveSample('The_example', 120, 120, '', 'MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web/distant_example')}}</div> + +<p>This time, if you take a <a href="/en-US/docs/MDN/Contribute/Editor/Source_mode">look at that page's HTML using the MDN editor</a>, you'll see no hidden code. If you want to see the code, just go to <a href="/en-US/docs/MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web/distant_example">the page that hosts it</a>.</p> + +<p>You can see a more advanced example of this usage in our <a href="/en-US/docs/Web/Guide/HTML/Forms/How_to_build_custom_form_widgets">HTML Form tutorial</a>, which uses this technique to allow experimentation with forms.</p> diff --git a/files/ja/mdn/contribute/howto/create_an_mdn_account/index.html b/files/ja/mdn/contribute/howto/create_an_mdn_account/index.html new file mode 100644 index 0000000000..70b2843e40 --- /dev/null +++ b/files/ja/mdn/contribute/howto/create_an_mdn_account/index.html @@ -0,0 +1,46 @@ +--- +title: MDN アカウントを作成するには +slug: MDN/Contribute/Howto/Create_an_MDN_account +tags: + - Beginner + - Documentation + - Guide + - Howto + - MDN Meta + - ガイド + - 初心者 +translation_of: MDN/Contribute/Howto/Create_an_MDN_account +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">MDN 上にあるコンテンツを編集するには、 MDN プロフィールが必要です。 MDN を読んだり、検索したりするだけの場合はプロフィールは不要です。このガイドは、 MDN のプロフィールをセットアップする手助けをします。</span></p> + +<div class="pull-aside"> +<div class="moreinfo"><strong>MDN に登録するにはなぜメールアドレスが必要なのか</strong><br> +<br> +メールアドレスはアカウントの回復に使用されます。また MDN の管理者がアカウントやサイトでの活動などについて連絡とる場合に必要となります。<br> +<br> +また、 (<a href="/ja/docs/MDN/Contribute/Howto/Watch_a_page">特定のページが変更されたとき</a>のような) 通知やメッセージ (例えば、ベータテストチームに参加し、テストが必要な新しい機能についてのメールを受信できます) にサインアップできます。<br> +<br> +メールアドレスは、 MDN では決して表示されず、<a href="https://www.mozilla.org/privacy/websites/">プライバシーポリシー</a>に従ってのみ使用されます。 + +<div class="note">GitHub 経由でログインしている場合、そして GitHub でメールアドレスを ”通知しない” に設定している場合、MDN からメッセージ（あなたがページを購読した時などの通知も含まれます）は受信されないでしょう。</div> +</div> +</div> + +<ol> + <li>MDN の各ページの上部に<strong>ログイン</strong>と書かれたボタンがあります。ここにマウスをポイント (モバイル端末の場合はタップ) すると、 MDN へのサインインに対応している認証サービスの一覧が表示されます。</li> + <li>ログインするサービスを選択します。現在は、 GitHub のみ利用できます。 GitHub を利用すると、 GitHub プロファイルへのリンクが MDN プロファイルの公開ページに追加されることに注意してください。 <img alt="ユーザーがサインアップの詳細を入力するところ" src="https://mdn.mozillademos.org/files/16954/2019-11-17.png" style="height: 848px; width: 1896px;"></li> + <li>サービスのプロンプトに従って、 GitHub のアカウントに接続します。 <img alt="ユーザーがログインしたりアカウントを作成したりしているところ" src="https://mdn.mozillademos.org/files/16956/2019-11-17_3.png" style="height: 879px; width: 1902px;"></li> + <li>認証サービスから MDN に戻ると、ユーザー名とメールアドレスの入力を求められます。<em>ユーザ名はあなたが貢献したページなどにクレジットとして公開されます。ユーザー名にメールアドレスを使用しないでください</em>。 <img alt="ユーザーがログインしたりアカウントを作成したりしているところｓ" src="https://mdn.mozillademos.org/files/16955/2019-11-17_2.png" style="height: 862px; width: 1870px;"></li> + <li><strong>MDN プロフィールを作成する</strong>をクリックします。</li> + <li>ステップ 4 で指定したメールアドレスが、認証サービスで使用しているものと同じでない場合、メールを確認し、メール内にあるリンクをクリックする必要があります。</li> +</ol> + +<p>以上です。これで MDN アカウントができました。すぐにページを編集することができます。</p> + +<p>MDN ページの上部にある自分のユーザー名をクリックすると、プロフィールを確認できます。そこで<strong>編集</strong>ボタンをクリックすると、プロフィールを変更できます。</p> + +<div class="note"> +<p>ユーザー名に空白や "@" を含めてはいけません。ユーザー名は、あなたが貢献したページなどに表示されることを覚えておいてください。</p> +</div> diff --git a/files/ja/mdn/contribute/howto/create_and_edit_pages/index.html b/files/ja/mdn/contribute/howto/create_and_edit_pages/index.html new file mode 100644 index 0000000000..a338b31625 --- /dev/null +++ b/files/ja/mdn/contribute/howto/create_and_edit_pages/index.html @@ -0,0 +1,185 @@ +--- +title: ページを作成および編集する方法 +slug: MDN/Contribute/Howto/Create_and_edit_pages +tags: + - Howto + - Intro + - MDN Meta + - ガイド + - 初心者 +translation_of: MDN/Contribute/Howto/Create_and_edit_pages +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">この記事は、新しい協力者に既存ページの編集と、新規ページを作成する手順を紹介します。</span></p> + +<h2 id="Editing_an_existing_page" name="Editing_an_existing_page">既存ページの編集</h2> + +<p>ページを編集するには以下のようにします。</p> + +<ol> + <li>読み取り専用版の MDN Web Docs (https://developer.mozilla.org) を見ているのであれば、記事ヘッダーにある <strong>Wiki で編集</strong>をクリックしてください。変更可能な Wiki 版のサイト (https://wiki.developer.mozilla.org) へ移動しますが、まだ編集インターフェイスは開きません。</li> + <li>Wiki ページの記事ヘッダーにある<strong>編集</strong>ボタンをクリックしてください。</li> + <li>ページが編集インターフェイス付きで読み込み直され、情報を直接追加したり削除したりできます。</li> + <li>書いたり編集したりするために、基本機能以外に段落を追加したり、テキストを削除したり、見出しを挿入したりすることができます。</li> +</ol> + +<p><strong>MDN</strong> の組み込みエディターの使い方について詳しくは、<a href="/ja/docs/MDN/Contribute/Editor">MDN エディター UI のガイド</a>の<a href="/ja/docs/MDN/Contribute/Editor/Basics">エディターの UI 要素</a>を参照してください。</p> + +<h3 id="Preview_changes" name="Preview_changes">変更のプレビュー</h3> + +<p>変更がどのように見えるかを確認するには、以下のようにします。</p> + +<ul> + <li>ページの上端または下端の編集機能の中にある「<strong>プレビュー</strong>」ボタンをクリックします。</li> + <li>新しいウィンドウまたはタブに、編集中のリビジョンを表示するプレビューページが開きます。</li> + <li>このボタンをクリックするたびに、最新の変更内容でプレビューページが更新されます。</li> +</ul> + +<p>ページをプレビューしても進行状況は保存<strong>されません</strong>ので、開いている編集タブを閉じないように注意してください。</p> + +<h3 id="Revision_comment" name="Revision_comment">リビジョンのコメント</h3> + +<p>変更をプレビューしたら、<em>このリビジョンを保存しましょう</em>。<strong>保存</strong>する前に、編集ボックスより下にあるリビジョンコメントボックスを探して、他の寄稿者に変更を加えた理由を知らせるコメントを残してください。たとえば、新しいセクションを追加したり、いくつかの単語を変更して用語をより統一させたり、段落を書き換えて言語を明確にしたり、冗長であったため情報を削除したなどです。</p> + +<h3 id="Table_of_Contents" name="Table_of_Contents">目次</h3> + +<p>記事の「このページ内」の節は、ページの見出しにリンクする自動生成されたリストです。見出しを編集することで、このリンクも編集することができます。「翻訳についての説明」を選択して「目次」ドロップダウンの値を変更することで、目次全体を消したり、リンクの数を減らしたりすることもできます。</p> + +<h3 id="Tags" name="Tags">タグ</h3> + +<p>ページの編集セクションの下に、ページの内容と機能を記述するタグを追加または削除できます。 適用するタグの情報については、<a href="/ja/docs/MDN/Contribute/Tagging">ページに正しくタグ付けする方法</a>を参照してください。</p> + +<h3 id="Review_needed" name="Review_needed">レビューが必要な場合</h3> + +<p>専門家、または経験豊富な寄稿者が編集内容を確認する必要がある場合は、技術レビュー (コード、API、技術などの場合)、編集レビュー(散文、文法、コンテンツの場合) を要求することができるので、保存する前に適切なボックスがオンになっていることを確認してください。</p> + +<h3 id="Attach_files" name="Attach_files">添付ファイル</h3> + +<p>ファイルを添付するには、特殊なユーザー権限が必要です。詳細は <a href="/en-US/docs/MDN/Contribute/Editor/Basics/Attachments">Attachments in the MDN editor</a> をご覧ください。そこにアップロード権限のリクエスト方法も書かれています。</p> + +<h3 id="Publish_Discard_or_Keep_editing" name="Publish_Discard_or_Keep_editing">公開、破棄、編集の続行</h3> + +<p>編集作業が終わり、プレビューに満足したのであれば、<strong>ページタイトルの右側</strong>か<strong>ページ最下部</strong>にある<em>緑色</em>の「<strong>公開</strong>」ボタンをクリックして、作業やコメントを保存することができます。そのまま編集を続行したい場合は、「<strong>公開して編集を続行</strong>」ボタンをクリックするして、編集インターフェイスを開いたまま作業を続けることができます。</p> + +<p>気が変わったら、<em>赤い</em>「<strong>破棄</strong>」ボタンをクリックすると編集内容を破棄できます。なお、変更を破棄すると<em>完全に</em>破棄されます。</p> + +<p>リビジョンコメントボックスで<strong>Enter</strong>キーを押すと、「<strong>公開して編集を続行</strong>」ボタンを押した場合と同じ結果になります。</p> + +<div class="note"> +<p>注: 保存しようとしたとき、変更が不正であるとして保存できず、内容が MDN にとって適切だと思った場合は、 <a href="mailto:mdn-admins@mozilla.com?subject=MDN%3A%20Content%20Rejection%20Appeal&body=%3CDescribe%20the%20content%20you%20were%20trying%20to%20save%20and%20where%20you%20were%20trying%20to%20place%20it.%3E">MDN の管理者チームにメールを送って</a>、助けを求めてください。</p> +</div> + +<h2 id="Getting_page-creation_permissions" name="Getting_page-creation_permissions">ページ作成権限の取得</h2> + +<p>セキュリティ上の理由から、新しく作成されたアカウントでは、新しいページを作成することができません。ページを作成しようとすると、ページを作成するための手引きページが表示されます。ページを作成する方法は2つあります。</p> + +<ul> + <li><strong>ページの作成を依頼する。</strong>これを行うには、<a href="https://github.com/mdn/sprints/issues/new?template=issue-template.md&projects=mdn/sprints/2&labels=user-report">文書の要求の問題を登録</a>し、タイトルを "Create page: <ページ名>" としてください。テンプレートの URL 欄には、分かれば MDN 上でページを作成したい場所を記入してください。コメントのテキストには、なぜこのページを作成する必要があるかについての情報を記入してください。</li> + <li><strong>ページ作成の権限を申請する。</strong>ページ作成の権限を申請して、それが認められた場合、下記の方法でページを作成することができます。権限を申請するには <a href="mailto:mdn-admins@mozilla.org">MDN の管理者チームにメールを送って</a>ください。メールの内容にはあなたのユーザー名と権限を申請する理由 (例えば、新しい API の文書を書くために多くの新しいページを作成する必要がある、用語集に新しい用語を追加するためなど) を書いてください。申請する前に、サイトの内容に何らかの役に立つ貢献をしており、また一定の期間協力をしてからにするべきです (時間の長さはあくまでも一つの考慮なので、何か固定の期間があるわけではありません)。</li> +</ul> + +<h2 id="Creating_a_new_page" name="Creating_a_new_page">新しいページを作成する</h2> + +<p>ページ作成権限があれば、新しいページの作成を開始できます。</p> + +<p>新しい記事をどこに置くべきか分からなくても、<strong>心配する必要はありません。</strong>それをどこ置いても、わたしたちはそれを見つけて適正な場所に移動するか、それが最も理にかなっている場合は既存のコンテンツにマージします。あなたはページを完璧にすることについても心配する必要はありません。私たちみんなでコンテンツをきれいに美しくします。</p> + +<p>新しいページを作成するには、いくつかの方法があります。</p> + +<ul> + <li><a href="#Missing_page_link">「存在しないページ」へのリンク</a></li> + <li><a href="#New_page_without_link">リンクなしで新しいページを作成</a></li> + <li><a href="#Subpage_of_an_existing_page">既存のページのサブページを作成</a></li> + <li><a href="#Clone_of_an_existing_page">既存のページを複製</a></li> + <li><a href="#Link_from_an_existing_page">既存のページからリンク</a></li> +</ul> + +<h3 id="Missing_page_link" name="Missing_page_link">「存在しないページ」へのリンク</h3> + +<p>ほとんどの Wiki と同様に、 MDN ではまだ存在しないページへのリンクを作成することができます。 たとえば作成者は、 API のメンバーのページを作成する前に、すべてのメンバーのリストを作成することができます。 MDN では、存在しないページへのリンクは通常赤字で表示されます。</p> + +<p>「存在しないページ」へのリンクからページを作成するには</p> + +<ol> + <li>MDN にログインしていて、ページ作成権限を取得してください。ログインしていない場合は、「存在しないページ」のリンクは、404 (ページが見つかりません) というエラーを表示します。</li> + <li>「存在しないページ」のリンクをクリックしてください。ページ作成権限があれば <a href="/ja/docs/MDN/Contribute/Editor">MDN エディターの UI</a> が開き、新しくページを作成する準備が整います。</li> + <li>ページの内容を書き込んで保存します。</li> +</ol> + +<h3 id="New_page_without_link" name="New_page_without_link">リンクなしで新しいページを作成</h3> + +<p><em>別のページからリンクせずに新しいページを作成するには</em>、ブラウザの URL フィールドに一意のページ名を入力します。たとえば、次のように入力します。</p> + +<pre class="language-html notranslate">https://wiki.developer.mozilla.org/en-US/docs/FooBar</pre> + +<p>MDN は "FooBar" というタイトルの新しいページを作成し、エディターを開いて新しいページにコンテンツを追加することができます。エディターモードの使用方法については、この記事の「<a href="#Editing_an_existing_page">既存のページを編集する</a>」セクションを参照してください。</p> + +<p>別のページからリンクせずに新しいページを作成するには</p> + +<ol> + <li>MDN にログインしていて、ページ作成権限を取得する</li> + <li>ブラウザーの URL 欄に下記のように入力する</li> +</ol> + +<pre class="language-html notranslate">https://wiki.developer.mozilla.org/en-US/docs/new</pre> + +<p>MDN は新しいページを作成し、エディターを開いて新しいページにコンテンツを追加することができます。エディターモードの使用方法については、この記事の「<a href="#Editing_an_existing_page">既存のページを編集する</a>」セクションを参照してください。</p> + +<h3 id="Subpage_of_an_existing_page" name="Subpage_of_an_existing_page">既存のページのサブページを作成</h3> + +<p>既存のページの下の階層にサブページを作成することができます。</p> + +<ol> + <li>必要であれば、記事ヘッダーの <strong>Wiki で編集</strong> をクリックして Wiki サイトへ移動してください。</li> + <li>「親」ページで、<strong>詳細設定</strong>メニュー (ツールバーの歯車アイコン) をクリックすると、「<strong>新しいサブページ</strong>」をクリックします。</li> + <li>新しい文書を作成するためのエディタービューが開きます。</li> + <li>「<strong>タイトル</strong>」欄に文書のタイトルを入力します。</li> + <li>必要に応じて<strong>スラッグ</strong>欄を変更します。たとえば、タイトルが長い場合により短い URL が適切である場合などです。この欄はエディターが、タイトルの中の空白をアンダースコアに置き換えて自動的に記入しますが、 URL の最後の部分のみを変更します。</li> + <li><strong>目次</strong>欄では、ページの目次に自動的に表示する見出しレベルを選択します。必要がない場合は「目次なし」を選択します。</li> + <li>エディターペインにページの内容を書き込んで変更を保存します。エディターモードの使用方法については、この記事の「<a href="#Editing_an_existing_page">既存のページを編集する</a>」セクションを参照してください。</li> +</ol> + +<h3 id="既存のページを複製">既存のページを複製</h3> + +<p>新しいページの土台として使用したい書式を持つ既存のページがある場合は、そのページを「複製」し、それから内容を変更してください。</p> + +<ol> + <li>必要であれば、記事ヘッダーの <strong>Wiki で編集</strong> をクリックして Wiki サイトへ移動してください。</li> + <li>元のページで、<strong>詳細設定</strong>メニュー（ツールバーの歯車アイコン）をクリックし、「<strong>このページを複製</strong>」をクリックします。 新しい文書を作成するためのエディタービューが開きます。</li> + <li>新しいコンテンツに適切となるようにページ<strong>タイトル</strong>を変更します。 <strong>スラッグ</strong>欄は、「<strong>タイトル</strong>」欄を変更すると自動的に更新されます。</li> + <li>必要に応じて、<strong>スラッグ</strong>欄のパスを変更して、新しい文書を文書階層の別の部分に配置します。帆殿の場合では、必要ありません。複製されたページはふつう、元のページと同様の内容w持っており、同様の位置に配置する必要があるからです。</li> + <li><strong>目次</strong>欄で、ページの目次に自動的に表示する見出しレベルを選択します。必要がない場合は「目次なし」を選択します。</li> + <li>エディターペインにページの内容を書き込んで、変更を保存します。エディターモードの使用方法については、この記事の「<a href="#Editing_an_existing_page">既存のページを編集する</a>」セクションを参照してください。</li> +</ol> + +<h3 id="Link_from_an_existing_page" name="Link_from_an_existing_page">既存のページからリンク</h3> + +<p>これは、いくつかの方法の組み合わせです。現在存在しているページから、新しいページへのリンクを作成し、挿入したリンクをクリックします。</p> + +<ol> + <li>既存ページのテキスト内の (意味のある) どこかの場所に新しいページの名前を入力します。</li> + <li>その名前をハイライトしてエディターツールバーから<strong>リンクアイコン (<img alt="" src="https://developer.mozilla.org/files/3810/link-icon.png" style="height: 28px; width: 29px;">) をクリック</strong>します。<strong>'Update Link'</strong> のダイアログが開き、 <strong>'Link To'</strong> 欄が強調されています。</li> + <li>既定では URL 欄の最初に <strong>"/ja/docs/"</strong> が挿入されます。 "/ja/docs/" の後にページ名を入力します。ページ名はリンクテキストと同じである必要はありません。</li> + <li><strong>OK</strong> をクリックしてリンクを作成、挿入します。</li> +</ol> + +<p>ページがまだ存在しない場合、リンクは赤く表示されます。ページがすでに存在する場合、リンクは青く表示されます。新しいページを作成したいが、ページタイトルがすでに取られている場合、まずはすでにあるページの編集を助けたり改良したりするのがもっと意味があるのではないのかを確認してください。そうでない場合、新しいページに別の名前を考えてリンクを作成します。ガイドラインの <a href="https://developer.mozilla.org/Project:en/Page_Naming_Guide" title="Project:en/Page_Naming_Guide">page naming guide</a> を参照してください。</p> + +<p>新しいページに中身を追加するには、 (エディターを保存して閉じた後に) 作成したばかりの赤いリンクをクリックします。新しいページがエディターモードで開かれて、書き始められます。エディターモードの使用については、この記事の<a href="#Editing_an_existing_page">既存のページを編集する</a>節を参照してください。</p> + +<h2 id="Refreshing_page_content" name="Refreshing_page_content">ページ内容の更新</h2> + +<p>KumaScript のマクロの MDN 対応や、他のページの内容の統合は、パフォーマンス上の理由でページをキャッシュする必要により妨げられることがあります。ページはソースから構築され、その出力は将来のリクエストのためにキャッシュされます。そのため、マクロ (テンプレート) や (<span class="templateLink"><code><a href="https://developer.mozilla.org/en-US/docs/Template:Page">Page</a></code></span> マクロを使用した) 統合はマクロやその出力、統合された素材の内容のその後の変更が反映されません。</p> + +<ul> + <li>ページを手動で更新するには、ウェブブラウザーで強制的に再読み込みしてください。 MDN はこれを検知してページの再構築を起動し、更新されたマクロの出力や統合されたページ内容を引き出します。</li> + <li>ページを定期的に自動再構築するよう設定することもできます。これは、ページが頻繁に更新されると予想されない限り使用するべきではありません。詳しくは<a href="/ja/docs/MDN/Contribute/Tools/Page_regeneration">ページの再生成</a>を参照してください。</li> +</ul> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Editor">MDN エディターガイド</a></li> + <li><a href="/ja/docs/MDN/Contribute/Content/Style_guide">MDN のスタイルガイド</a></li> +</ul> diff --git a/files/ja/mdn/contribute/howto/create_learning_pathways/index.html b/files/ja/mdn/contribute/howto/create_learning_pathways/index.html new file mode 100644 index 0000000000..d82d0877f2 --- /dev/null +++ b/files/ja/mdn/contribute/howto/create_learning_pathways/index.html @@ -0,0 +1,70 @@ +--- +title: 学習パスの作成方法 +slug: MDN/Contribute/Howto/Create_learning_pathways +tags: + - MDN Meta + - ガイド + - 学習 + - 方法 +translation_of: MDN/Contribute/Howto/Create_learning_pathways +--- +<div>{{MDNSidebar}}</div> + +<p>学習領域で可能なさまざまなタスクの中で、最も重要なのは学習パスを設計することです。<span class="seoSummary">学習パスは基本的に、何かを学ぶために、通常は特定の順序で、読み、実行するための一連の記事です。 しかし良い・効率的なパスを作るには、いくつかの作業が必要です。このガイドは MDN の学習パスの計画と作成方法を学ぶのに役立ちます。</span></p> + +<p>学習パスは実際にはチュートリアルのように見えますが、その通りでそれは非常に似ています。違いは、チュートリアルは、学習の道が青写真である具体的な結果だということです。MDN で素晴らしい学習コンテンツを作成するために必要なことの詳細を見てみましょう。</p> + +<h2 id="処方箋">処方箋</h2> + +<p>学習パスの設計の冒頭には、常にあなたのアイデアを定式化する時があります。そのような道筋のデザイナーとして、あなたは先生の立場にあるので、教えているレッスンを正式なものにする必要があります。要するに、あなたは次の質問に答えなければなりません：</p> + +<dl> + <dt>何を教えたいですか？</dt> + <dd> + <p>一般的な知識 (例えば、オブジェクト指向プログラミング、{{Glossary("HTML")}}、Web デザイン) もしくはより具体的な実行するタスク (例えば、<a href="/ja/docs/Learn">Web サイトを構築する</a>方法、ナビゲーションを設計する方法 メニュー) かもしれません。これは本当にあなた次第ですが、集中しておくことが重要です。Web はかなり大きな獣で、学ぶべきことがたくさんあります。あなたのパスから学ぶ人に明確な洞察を与えるために、教えたいことを絞り込んでください。</p> + </dd> + <dt>オーディエンスは誰ですか？</dt> + <dd>学習スタイル、したがって教授のアプローチは、誰が学習をしているかによって大きく異なります。あなたが子供たちに教えたいのであれば、大人を教えるときとは異なるアプローチを取ります。初心者に対して教えるときは、熟練した開発者はすぐにはっきりと分かる基本的なことに集中する必要があります。その質問に答えることで、パスに入れる必要のある情報の深みと深さを定義するのに役立ちます。</dd> + <dt>事前知識が必要ですか？</dt> + <dd>これはパスの使いやすさを定義するために重要です。パスに多くの前提条件がある場合は、難しいパスです。つまり、非常に熟練した人だけが始めることができます。初心者を対象とするパスは、前提条件が比較的少数である必要があります。たとえば、{{Glossary("WebGL")}} を教えるための学習経路を作成したい場合、その経路から学ぶ人は既に {{Glossary("JavaScript")}} を知っていなければなりません。したがって、平均的または熟練した Web 開発者だけがそのようなパスに入ることができます。 これは大丈夫ですが、最初からそれを明確にする方が良いです。</dd> +</dl> + +<div class="note"> +<p><strong>プロのヒント:</strong> これを単独で行うことは困難な時があります。 あなたのアイデアを共有し、フィードバックを収集することをお勧めします。それはあなたのアイデアをテストし、物事を忘れるのを助けるでしょう。これを行うには、<a href="https://discourse.mozilla-community.org/c/mdn">MDN ディスカッションフォーラム</a> (テクニカルコンテンツについて話す) と <a href="https://forum.learning.mozilla.org/">Mozilla ラーニングフォーラム</a> (さまざまな教授法について話す) であなたのアイデアをすべて話すことができます。また、シンプルなメモ帳ツール (<a href="https://etherpad.mozilla.org/">Etherpad</a> など) を使用して簡単に情報を共有したり収集したりすることもできます。</p> +</div> + +<h2 id="概念">概念</h2> + +<p>あなたが誰に何を教えたいのか分かったので、それを行う方法を定義しましょう。</p> + +<p>最初に行うことは、チュートリアルのレッスンを小さな個別の部分に分割することです。<br> + 基本的には、画像を持っていて、ジグソーを使用してパズルのピースを作成するようなものです。小さければ小さいほど良いです。<br> + 一度それらのすべての作品を持っていたら、それらをグループ化して論理インクリメンタルグループにソートするときです。<br> + ゼロから完了までの包括的な方法を生み出すために必要なだけ繰り返します。</p> + +<p>There is no magic way to acheive this. Each lesson has its own requirement and each teacher has their own teaching method. The way you want to teach something will have a huge impact on how you'll break things into smaller parts. As a reminder, for MDN, ultimately it will be about writing articles and providing exercises for people who will learn by themselves.</p> + +<p>Also remember that there is no hard constraint on how to sort things out. If you want to build straight forward learning pathways that's fine. But if you want to build conditional pathways, that's fine too. What is important is to make things clear. You have to put yourself into the learners' shoes. Conception of a learning pathway is not very complicated but can take quite some time.</p> + +<div class="note"> +<p><strong>Pro tip:</strong> When going to conception, it can be helpfull to discuss things with others (as for the ideation part, see above). Since creating a learning pathway is about structuring information, it can be very helpfull to use some of the techniques that come from UX design such as <a href="https://en.wikipedia.org/wiki/Card_sorting" rel="external">card sorting</a>. As an example, card sorting was used to figure out how to structure the "How to build a web site" pathway. It helped us break up and sort things out by producing a clear <a href="https://wiki.mozilla.org/MDN/Learning_Area/Tree_of_knowledge">tree of knowledge</a>.</p> +</div> + +<h2 id="作成">作成</h2> + +<p>Ultimately once you get a clear view of the pathway itself, it is important to start defining the type of content needed for each step of the pathway. On MDN, at a minimum there should be a <a href="/en-US/docs/MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web">learning article</a>. Such articles can be associated with various <a href="/en-US/docs/MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web">active learning content</a> (basically: exercises). Of course, you can also imagine other types of content such as videos, assessments and tests to validate knowledge, etc.</p> + +<p>Once you are clear on those various content requirements, you are ready to shape you pathway on MDN. This is very simple <a href="/en-US/docs/new?parent=119769">create a new landing page</a> for your pathway under <a href="/en-US/Learn/tutorial">/Learn/tutorial</a>. This landing page must clearly state what the reader will learn as well as any prerequisites necessary to follow that pathway. It also must contain the full list of articles to read with an excerpt for each article. Active learning content can also be listed here but it's not mandatory if they are linked directly inside the related articles.</p> + +<p>Once the landing page is ready, it "just" requires creating the necessary content. For that, you have two options:</p> + +<ul> + <li>Do it yourself (beware, it can take a long time)</li> + <li>Engage people in order to help you. To do that, join the Learning Area community (see the topic box below) and explain by any means possible about what you are doing in order to find help. Welcome to MDN :)</li> +</ul> +<h3 id="Contact_us">Contact us</h3> + +<ul> + <li>On IRC: <a href="irc://irc.mozilla.org/mdn">#mdn</a></li> + <li><a href="https://discourse.mozilla.org/c/mdn">Discourse</a></li> +</ul> diff --git a/files/ja/mdn/contribute/howto/do_a_technical_review/index.html b/files/ja/mdn/contribute/howto/do_a_technical_review/index.html new file mode 100644 index 0000000000..4896a6fd7d --- /dev/null +++ b/files/ja/mdn/contribute/howto/do_a_technical_review/index.html @@ -0,0 +1,60 @@ +--- +title: 技術レビューを行う方法 +slug: MDN/Contribute/Howto/Do_a_technical_review +tags: + - Documentation + - Guide + - Howto + - MDN Meta + - Review + - レビュー +translation_of: MDN/Contribute/Howto/Do_a_technical_review +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p class="summary"><strong>技術レビュー</strong>は技術的な正確さと記事の完全性の確認と、必要に応じて修正する作業から成ります。記事の執筆者が他人に記事の技術的なコンテンツをチェックしてほしい場合、編集時に「技術レビュー」チェックボックスをチェックします。執筆者が特定の技術者に技術レビューを行うよう依頼することもありますが、その分野の技術に詳しい人は誰でも行うことができます。</p> + +<p><span class="seoSummary">この記事は、技術レビューを行う方法について説明します。技術レビューをすることで、MDN のコンテンツを正確にする手助けができます。</span></p> + +<dl> + <dt>どのような作業か</dt> + <dd>記事の技術的な正確性と完全性の確認と修正です。</dd> + <dt>行う必要があるものはどれか</dt> + <dd>特に<a href="/ja/docs/needs-review/technical">技術レビュー</a>が必要だとマークされている記事です。</dd> + <dt>作業を行う上で必要な知識</dt> + <dd> + <ul> + <li>レビューをする記事の話題に関するエキスパートとしての知識。もしその記事を読んで特に新しい知識が得られないようであれば、自分はエキスパートだと考えてください。</li> + <li>MDN のウィキの記事を編集する方法。</li> + </ul> + </dd> + <dt>作業のステップ</dt> + <dd> + <ol> + <li>レビューする記事を選んでください。 + <ol> + <li><a href="/ja/docs/needs-review/technical">技術レビュー</a>が必要なページの一覧に行きましょう。この一覧には、技術レビューが必要なページがすべて掲載されています。</li> + <li>自分が詳しい話題のページを選択しましょう。</li> + <li>記事のリンクをクリックしてページを読み込んでください。</li> + </ol> + </li> + <li><a id="core-steps" name="core-steps"></a>技術的な詳細に注意を払いながら、記事を読んでください。記事は正しいでしょうか？抜けていることはないでしょうか？最初に選択したページが自分に合わないようであれば、ためらわずに他のページに切り替えましょう。</li> + <li>エラーがなければ、レビューを完了するために記事を編集する必要はありません。ページの左のサイドバーにある「クイックレビュー」ボックスを見てください。この黄色いボックスでは、レビュー待ち項目の一覧が表示されており、レビューリクエストフラグを解除することができます。技術レビューがリクエストされていると、以下のようになります。<br> + <img alt="サイドバーに表示されるクイックレビューボックスに技術レビューが表示されている様子" src="https://mdn.mozillademos.org/files/15790/has-technical-review.png" style="height: 123px; width: 318px;"></li> + <li>「<strong>技術面</strong>」のチェックを外し、［<strong>保存</strong>］をクリックしてください。</li> + <li>エラーを見つけて修正しなければならないときは、嬉しいことにレビューリクエストの状態をエディターから変更することができます。手順は以下の通りです。 + <ol> + <li>ページを編集するために、ページの先頭付近にある［<strong>編集</strong>］ボタンを押してください。これで <a href="/ja/docs/MDN/Contribute/Editor">MDN エディター</a> に入ります。</li> + <li>正しくない技術情報を修正したり、欠けている情報を補ったりしてください。</li> + <li>記事の下にある<strong>リビジョンのコメント</strong>を入力してください。ここにはどのような編集を行ったかを短いメッセージで、「技術レビュー完了」のように書きます。情報を修正した場合は、それを「技術レビューを行い、引数の説明を修正した」のようにコメントに書いてください。これは他の協力者やサイトの編集者がなぜ変更されたのかを知る手掛かりになります。レビューの品質に達していないと感じた場合は、それを書いてもいいでしょう。</li> + <li>ページのリビジョンのコメントのすぐ上、「<strong>レビューが必要ですか？</strong>」下にある「<strong>技術レビュー</strong>」ボックスのチェックを外します。</li> + <li>［<strong>公開</strong>］ボタンを押してください。</li> + </ol> + </li> + </ol> + + <p>おめでとうございます！これで最初の技術レビューが完了しました。ご協力ありがとうございました。</p> + </dd> +</dl> diff --git a/files/ja/mdn/contribute/howto/do_an_editorial_review/index.html b/files/ja/mdn/contribute/howto/do_an_editorial_review/index.html new file mode 100644 index 0000000000..fbcbb03e99 --- /dev/null +++ b/files/ja/mdn/contribute/howto/do_an_editorial_review/index.html @@ -0,0 +1,58 @@ +--- +title: 編集レビューを行う方法 +slug: MDN/Contribute/Howto/Do_an_editorial_review +tags: + - Documentation + - Editorial Review + - Guide + - Howto + - MDN Meta + - 文書化 + - 編集レビュー +translation_of: MDN/Contribute/Howto/Do_an_editorial_review +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p class="summary"><strong>編集レビュー</strong>は、記事内の誤植、言葉遣い、文法、用法などの間違いの修正などの作業です。 MDN の技術文書に価値ある協力を行うためには執筆の専門家である必要はありませんが、記事には校正や精読が必要です。これが編集レビューで行われます。</p> + +<p><span class="seoSummary">この記事は、編集レビューを行う方法について記述します。編集レビューをすることで、 MDN のコンテンツを正確かつ、良く書けたものにする手助けができます。</span></p> + +<dl> + <dt>何をすればいいですか？</dt> + <dd>編集レビューが必要であるとマークされた記事の校正と精読です。</dd> + <dt>レビューが必要な記事はどこにありますか？</dt> + <dd>記事内に、編集レビューが必要とマークされています。</dd> + <dt>編集レビューをするには、何を知っておく必要がありますか？</dt> + <dd>日本語の文法と語彙についてよく知っている必要があります。編集レビューとは、正しくわかりやすい文法や言葉を選択する作業です。また、 <a href="/ja/docs/MDN/Contribute/Guidelines/Writing_style_guide">MDN 執筆スタイルガイド</a>にも従ってください。</dd> + <dt>レビューする手順は？</dt> + <dd> + <ol> + <li>レビューする記事を選びます。 + <ol> + <li><a href="/ja/docs/needs-review/editorial">編集レビューが必要な記事</a>の一覧に行ってください。この一覧には、編集レビューがリクエストされたすべてのページが表示します。</li> + <li>記事のリンクをクリックしてページを読み込みます。<br> + <strong>注: </strong>この一覧は自動的に生成されますが、あまり頻繁的ではないので、編集レビューが必要なくなった記事が載っていることもあります。選択した記事に「この記事は編集レビューが必要です」というバナーが表示されて<em>いなければ</em>、飛ばして別な記事を選んでください。</li> + </ol> + </li> + <li id="core-steps">記事を注意深く読み、誤植、言葉遣い、文法、用法などの間違いがないか確認します。選んだ記事が自分のやりたいものと違っていたら、気にせず別のページに移動してください。</li> + <li>これ以上直すべきところがなければ、編集はせずに、レビュー済みとしてマークしてください。ページ左のサイドバーにある「クイックレビュー」ボックスを見てください。<br> + <img alt="レビューリクエストボックス(日本語版)" src="https://mdn.mozillademos.org/files/14709/2017-02-23%2011.48.25.png" style="height: 256px; width: 692px;"></li> + <li><strong>編集レビュー</strong>のチェックボックスのチェックを解除して、<strong>保存</strong>をクリックします。</li> + <li>直すべきところを見つけた場合には、次の手順に従います。 + <ol> + <li>上部にある<strong>編集</strong>ボタンをクリックします。クリックすると、<a href="/ja/docs/Project:MDN/Contributing/Editor_guide">MDN エディター</a>が開きます。</li> + <li>誤植、言葉遣い、文法、用法などの間違いを見つけたら修正します。一度にすべての箇所を修正しなくても構いません。ただしその場合には、記事全体のレビューが完全に終わったと考えられない限り、編集レビューのリクエストはそのままにしておいてください。</li> + <li>記事の下部にある <strong>リビジョンのコメント</strong> 欄に 「<em>編集レビュー: 誤植、文法の修正。</em>」のようなコメントを入力します。このようなコメントを書いておけば、他の協力者やサイトの編集者たちが、どの部分がどんな理由で変更されたのかを簡単に知ることができます。</li> + <li><strong>レビューが必要ですか？</strong> の下にある <strong>編集レビュー</strong> のチェックボックスのチェックを外します。このボックスは、ページの「リビジョンのコメント」セクションのすぐ下にあります。</li> + <li><strong>公開</strong>ボタンをクリックします。</li> + </ol> + </li> + </ol> + + <div class="note"> + <p>あなたが行った変更は、保存直後には表示されないことがあります。背後で行っているページの処理や保存に時間がかかることがあるためです。</p> + </div> + </dd> +</dl> diff --git a/files/ja/mdn/contribute/howto/document_web_errors/index.html b/files/ja/mdn/contribute/howto/document_web_errors/index.html new file mode 100644 index 0000000000..b08647d0ab --- /dev/null +++ b/files/ja/mdn/contribute/howto/document_web_errors/index.html @@ -0,0 +1,63 @@ +--- +title: ウェブのエラーを文書化する方法 +slug: MDN/Contribute/Howto/Document_web_errors +tags: + - Howto + - MDN + - Meta +translation_of: MDN/Contribute/Howto/Document_web_errors +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p>MDN <a href="/ja/docs/Web/JavaScript/Reference/Errors">JavaScript error reference</a> は <a href="/ja/docs/Tools/Web_Console">Developer Console </a>で発生するエラーについて、ウェブ開発者を手助けすることを目的とした新しいプロジェクトです。</p> + +<p>この機能は、Firefox (Developer Edition) をお使いの場合に有効です。JavaScript エラーに含まれる "Learn more" が問題の修正に役立つ追加のアドバイスを含む JavaScript error reference にリンクしています。</p> + +<p>{{EmbedYouTube("OabJc2QR6o0")}}</p> + +<p>このプロジェクトを助けるには、メッセージが投げられるツールからより多くのリンクを追加できるように、もっと多くの MDN エラードキュメントを書くことが必要です。</p> + +<h2 id="Prerequisites" name="Prerequisites">前提条件</h2> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Howto/Create_an_MDN_account">MDN アカウント</a>が必要です。</li> + <li><a href="/ja/docs/Web/JavaScript">JavaScript </a>の知識か、検索する力が必要です。</li> +</ul> + +<h2 id="Step_1_–_find_an_error_to_document" name="Step_1_–_find_an_error_to_document">Step 1 – 文書化するエラーを探しましょう</h2> + +<ul> + <li>Firefox/Gecko のエラーメッセージ: <a href="https://dxr.mozilla.org/mozilla-central/source/js/src/js.msg">https://dxr.mozilla.org/mozilla-central/source/js/src/js.msg</a></li> + <li>Edge/Chakra のエラーメッセージ: <a href="https://github.com/Microsoft/ChakraCore/blob/master/lib/Parser/rterrors.h">https://github.com/Microsoft/ChakraCore/blob/master/lib/Parser/rterrors.h</a></li> + <li>Chrome/v8 のエラーメッセージ: <a href="https://github.com/v8/v8/blob/master/src/messages.h#L75">https://github.com/v8/v8/blob/master/src/messages.h#L75</a></li> +</ul> + +<h2 id="Step_2_–_look_at_existing_error_docs" name="Step_2_–_look_at_existing_error_docs">Step 2 – 既存のエラードキュメントを探しましょう</h2> + +<ul> + <li>既存の <a href="/ja/docs/Web/JavaScript/Reference/Errors">JavaScript エラーメッセージ</a>を見て、エラーの文書化される方法を見てみます。</li> + <li>書こうとするエラーの種類によっては、このページを詳細に見ます。</li> + <li>新しいエラーページをキックオフするのに、既存のエラーページのコンテンツをコピーしたくなるかもしれません。</li> +</ul> + +<h2 id="Step_3_–_create_a_new_page" name="Step_3_–_create_a_new_page">Step 3 – 新しいページを作成します</h2> + +<ul> + <li>すべてのエラーページはこの木の下にあります: <a href="/ja/docs/Web/JavaScript/Reference/Errors">/docs/Web/JavaScript/Reference/Errors</a></li> + <li><a href="/ja/docs/new?parent=179598">このリンク</a>に従ってサブページを作成できます。</li> +</ul> + +<h2 id="Step_4_–_write_some_content" name="Step_4_–_write_some_content">Step 4 – ページの内容を書きます</h2> + +<ul> + <li>既存のエラードキュメントから構造をコピーして使うか、最初からスタートするかのいずれでも。あなたの選択です!</li> + <li>少なくとも次のものが要ります: + <ul> + <li>いろいろなブラウザーで投げられるメッセージを含んだ文法ボックス</li> + <li>エラーの種類</li> + <li>エラーが発生する理由と、その結果を説明したテキスト。メッセージの投げられた背景まで</li> + <li>エラーを展示する例 (1 つ以上要ります!) とコードを修正する方法の例</li> + <li>MDN 上のその他のリファレンスへのポインター</li> + </ul> + </li> +</ul> diff --git a/files/ja/mdn/contribute/howto/index.html b/files/ja/mdn/contribute/howto/index.html new file mode 100644 index 0000000000..9b60cb2800 --- /dev/null +++ b/files/ja/mdn/contribute/howto/index.html @@ -0,0 +1,18 @@ +--- +title: How-to ガイド +slug: MDN/Contribute/Howto +tags: + - Documentation + - Landing + - MDN + - TopicStub + - ガイド +translation_of: MDN/Contribute/Howto +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<div class="note">このページでは、日本語訳されたサブページの一覧を表示しています。<a href="/en-US/docs/MDN/Contribute/Howto">英語版</a>に存在していても、日本語訳されていないページは表示されません。日本語訳にご協力ください。</div> + +<p class="summary">ここにある記事は、MDN に貢献する際に具体的な目標を達成するためのステップごとのガイドを提供するものです。</p> + +<p>{{LandingPageListSubpages}}</p> diff --git a/files/ja/mdn/contribute/howto/link_a_github_account/index.html b/files/ja/mdn/contribute/howto/link_a_github_account/index.html new file mode 100644 index 0000000000..4f7443b7f0 --- /dev/null +++ b/files/ja/mdn/contribute/howto/link_a_github_account/index.html @@ -0,0 +1,111 @@ +--- +title: GitHub アカウントを MDN プロフィールに結びつける方法 +slug: MDN/Contribute/Howto/Link_a_GitHub_account +tags: + - Documentation + - MDN + - MDN Meta + - MDN Project +translation_of: Archive/MDN/Howto_Link_a_Github_account +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<div class="note"> +<p><strong>Note: </strong>Support for Persona logins on MDN was disabled on November 1, 2016. The method for adding a Github account to your profile therefore no longer works. If you didn't add a GitHub login to your MDN account before we disabled Persona logins, please <strong>file an <a class="external external-icon" href="https://mzl.la/accounthelp">"Account Help" bug</a> </strong>on Bugzilla. For further reading about the end of life of Persona, see: <a href="https://wiki.mozilla.org/Identity/Persona_Shutdown_Guidelines_for_Reliers">Persona shutdown guidelines</a>.</p> +</div> + +<p><span class="seoSummary">Mozilla の <a href="https://login.persona.org/">Persona</a> 認証システムは終了しつつあるため、MDN に貢献したいすべてのユーザーは、2016年11月1日までにMDN にサインインする別の方法を持っておく必要が出てきます。現在は、唯一サポートしている代替品が GitHub なので、その日以降に MDN にサインイン・編集するには <a href="https://github.com/">GitHub</a> アカウントが必要になります。この記事ではあなたの MDN プロフィールに GitHub 認証を追加する方法を述べます。</span></p> + +<div class="warning"> +<p>2016年11月1日までにこれを行わないとなりません、さもないと、MDNにサインインする方法がもうなくなってしまうでしょう!</p> +</div> + +<h2 id="概要">概要</h2> + +<p>GitHub 認証をアカウントに追加するのは難しくありません。少し後に詳細に入りますが、まず最初に、ステップの一覧がこちらです:</p> + +<ol> + <li>Persona で <a href="/docs/MDN/Signing_in">MDN アカウントにサインインする</a></li> + <li><a href="https://developer.mozilla.org/ja/users/account/connections">アカウント接続</a> ページに移動する</li> + <li>GitHub 認証を追加する</li> +</ol> + +<h2 id="詳細な手順">詳細な手順</h2> + +<p>こちらが、知っておくべきこと全てのやり方を詳しく説明したステップバイステップガイドです。</p> + +<h3 id="MDN_アカウントにサインインする">MDN アカウントにサインインする</h3> + +<ol> + <li>MDN ページの上部で、 <strong>サインイン</strong> ボックスにマウスを重ねるかタップします。利用できる認証ボックス、つまり <strong>Persona</strong> か <strong>GitHub</strong> が表示されます<br> + <img alt="Sign in box on MDN, showing Persona and Github." src="https://mdn.mozillademos.org/files/13426/Mozilla_Developer_Network_-__Private_Browsing_.png" style="border-style: solid; border-width: 1px; height: 140px; width: 425px;"></li> + <li><strong>Persona</strong> を選択し、機密情報を使ってサインインします。認識されないエラーが出た場合、今使っているeメールアドレスが何であろうと、MDNにPersonaをリンクした時のeメールアドレスを使っているか確認してください。問題が続く場合、 {{anch("Persona doesn't remember me")}}を見てください。</li> +</ol> + +<h3 id="アカウント接続_ページに移動する">"アカウント接続" ページに移動する</h3> + +<p>アカウント接続ページにたどり着くには2つの方法があります。</p> + +<p>最初は、単に下記のリンクをクリックします。</p> + +<p>あるいは、下記を行います:</p> + +<ol> + <li>MDN ページ上部にあるユーザ名をクリックします。(ログイン前に <strong>サインイン</strong> ボックスがあった場所にあります) これでプロフィールページに移ります。</li> + <li>"歯車" メニューを開き、<strong>アカウント接続</strong> をクリックします。<img alt='Gear menu in profile, showing the "Account connections" option' src="https://mdn.mozillademos.org/files/13428/SheppyWork___MDN_-__Private_Browsing_.png" style="height: 217px; width: 219px;"></li> +</ol> + +<h3 id="GitHub_認証を追加する">GitHub 認証を追加する</h3> + +<p>あなたは "アカウント接続" ページにいます。ここにはすでにあなたの MDN プロフィールと結ばられている外部アカウントが一覧になっています。GitHub が既に載っていたら、おめでとうございます! もう出発できます! ただし、確実にパスワードを覚えているようにするために、MDN からサインアウトしてからまた GitHub の秘密情報でサインインするのを試してみます。</p> + +<p>GitHub が載っていない場合、ページの下部付近にて、既にリンクされた外部アカウントを見ます。そこで <strong>新しいアカウントを接続する</strong> という節が見えて、MDN プロフィールに接続できるアカウントの種類が一覧されています。それはこのような感じです:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13430/Account_Connections___MDN_-__Private_Browsing_.png" style="height: 79px; width: 476px;"></p> + +<p>GitHub を追加するには:</p> + +<ol> + <li><strong>GitHub と接続</strong>をクリックします。 MDN は GitHub に連絡してアカウントをリンクする権限を要求します。GitHub にまだサインインしていない場合、それを求められます:<br> + <img alt="Screenshot of GitHub sign in window." src="https://mdn.mozillademos.org/files/13444/GitHub_Sign_In.png" style="height: 447px; width: 356px;"></li> + <li>GitHub アカウントで2要素認証を有効化している場合、認証コードの入力を求められます:<img alt="Screenshot of GitHub's Two-factor authentication window." src="https://mdn.mozillademos.org/files/13460/GitHub_-_Where_software_is_built.png" style="height: 448px; width: 361px;"></li> + <li>GitHub アカウントにサインインしており、GitHub と MDN とのリンクの承認を求められるでしょう(すでに何らかの理由により、承認済みでない場合)。このページは下記に出ています。<br> + <img alt='Screenshot of GitHub "Authorize application" window.' src="https://mdn.mozillademos.org/files/13456/Authorize_Mozilla_Developer_Network.png" style="height: 420px; width: 766px;"><br> + 緑の <strong>Authorize application</strong> ボタンをクリックして、MDN アカウントが GitHub アカウントにアクセスできる権限を与えます。GitHub アカウントがうまく MDN プロフィールと結びつけられたら、下記のメッセージが見えます:<br> + <img alt="Account successfully created." src="https://mdn.mozillademos.org/files/13454/Edit_Your_Profile___MDN.png" style="height: 57px; width: 646px;"></li> +</ol> + +<p>MDN のサインインに GitHub を使えるだけでなく、実際すでに GitHub 認証を使ってサインインしています! いまやあなたは Persona の終了に対する準備ができています。パスワードマネージャをインストールしていれば、必要に応じて更新してください。</p> + +<h2 id="トラブルシューティング">トラブルシューティング</h2> + +<p>プロフィールに GitHub アカウントを追加しようとする時に問題に入った場合、下記のトラブルシューティング tips が役立つでしょう。</p> + +<h3 id="Error_Could_not_find_profile_matching_account">Error: Could not find profile matching account</h3> + +<p>あなたのプロフィールに GitHub アカウントを追加しようとして "Could not find profile matching account," というエラーが出た場合、いくつか異なる事を意味します。GitHubアカウントに複数のアカウントを持っている場合、いくらか混乱があります; GitHub は MDN が期待するeメールアドレスに報告せず、その結果エラーとなります。他の処理中のグリッチでも同じメッセージが出る事もあります。</p> + +<p>この問題の回避策は: ブラウザのプライベートウィンドウを開きます; たとえば Firefox ではファイルメニューで "新しいプライベートウィンドウ" を選びます (または <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> [Mac では<kbd>Cmd</kbd>-<kbd>Shift</kbd>-<kbd>P</kbd>])。そこでMDNへ移動し、<a href="/en-US/docs/MDN/Signing_in">MDN アカウントにサインインして</a> 上記に説明したように、あなたのプロフィールに GitHub アカウントを再度追加してみてください。</p> + +<h3 id="アカウント接続のページで_GitHub_認証が表示されない">アカウント接続のページで GitHub 認証が表示されない</h3> + +<p>それはキャッシュの問題かもしれません。ページをリロードするかログアウトして再びログインすれば問題は解決するでしょう。</p> + +<h3 id="Persona_に私の情報が記憶されていない">Persona に私の情報が記憶されていない</h3> + +<p>Persona にログインを試みてMDNアカウントに GitHub ログインしようとした時に、 "Your email address is new to us,(あなたのeメールアドレスを我々は知りません)" と告げられた場合、Personaに最終ログインしてから長い時間が経ったためシステムがあなたのeメールアドレスを削除してしまった可能性が高いです。これはいくらかの期間の後に起こります; つまりPersonaのログインウィンドウはこの状況でこのようになります:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13765/unknown-to-persona.png" style="height: 533px; width: 800px;"></p> + +<p>If this happens, you need to simply follow Persona's instructions to create a new password for that email address. MDN doesn't care about this process; the fact that your email address matches up is all that matters. A confirmation email will be sent to verify that you own the email address, probably from <code>no-reply@persona.org</code>. If you have spam filtering, it may be sent to your spam folder.</p> + +<p>Once you've finished the process of setting the password for the email address you used to log into MDN, your access to MDN will be restored. Then you can follow the steps in {{anch("Detailed instructions")}} above to add your GitHub login to your MDN account.</p> + +<h2 id="こちらも見てください">こちらも見てください</h2> + +<ul> + <li><a href="/docs/MDN/Contribute/Howto/Create_an_MDN_account">MDN アカウントを作成する方法</a></li> + <li><a href="/docs/MDN/Getting_started">MDN を始めるには</a></li> +</ul> diff --git a/files/ja/mdn/contribute/howto/migrate_external_content_to_mdn/index.html b/files/ja/mdn/contribute/howto/migrate_external_content_to_mdn/index.html new file mode 100644 index 0000000000..9899dce7f3 --- /dev/null +++ b/files/ja/mdn/contribute/howto/migrate_external_content_to_mdn/index.html @@ -0,0 +1,66 @@ +--- +title: 外部コンテンツを MDN Web Docs に移行する方法 +slug: MDN/Contribute/Howto/Migrate_external_content_to_MDN +tags: + - Content migration + - MDN Meta +translation_of: MDN/Contribute/Howto/Migrate_external_content_to_MDN +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">他の場所から MDN Web Docs に移行することに意味のある既存のコンテンツが見つかることがあります。<span class="seoSummary">この記事では、どのような種類のコンテンツを移行することが意味のあることなのか、コンテンツを移行すべきかどうか、移行を行うためにどのようなワークフローを使用すべきかについて説明します。</span></p> + +<h2 id="What_content_would_make_sense_to_migrate" name="What_content_would_make_sense_to_migrate">どのようなコンテンツが移行することに意味があるのか</h2> + +<p>MDN Web Docs に移行することに意味があると思われるコンテンツの種類はいくつかあります。</p> + +<ul> + <li>チュートリアル/ガイド: の使用に関する実用的な情報。これらは MDN Web Docs 上でレベルや範囲に応じて様々な場所で役立ちます (例: <a href="/ja/docs/Web/API/Fetch_API/Using_Fetch">Fetch の使用</a>、<a href="/ja/docs/Learn/HTML/Introduction_to_HTML/Creating_hyperlinks">ハイパーリンクの作成</a>)。</li> + <li>解説/概念の記事: これらは一般的に、 API がなぜそのような構造になっているのか、どのような問題を解決するために設計されているのかなど、高レベルの概念を説明するものです。これらは「概念」記事 (例えば <a href="/ja/docs/Web/API/WebVR_API/Concepts">WebVR の概念</a>) として意味があります。</li> + <li>コード例: MDN Web Docs は、参照記事の中に入れるコードスニペットであれ、リンク先の完全な例であれ、良いコード例を本当に大切にしています。私たちは、スタンドアロンの例として、または<a href="https://github.com/mdn/interactive-examples">対話型の例のリポジトリ</a>の一部として、優れたコード例を GitHub リポジトリに歓迎します。</li> +</ul> + +<p>MDN Web Docs に移行しても意味がないコンテンツは下記のとおりです。</p> + +<ul> + <li>長い事例研究</li> + <li>製品のドキュメント</li> + <li>宣伝コンテンツ</li> +</ul> + +<h2 id="Why_would_you_migrate_the_content" name="Why_would_you_migrate_the_content">なぜコンテンツを移行するのか</h2> + +<p>良い開発者向けコンテンツがすでに存在するのであれば、いくつかの理由から MDN Web Docs に移行することには意味があります。</p> + +<ul> + <li>SEO: MDN Web Docs はとても有名なサイトで、そこにあなたのコンテンツを置くことは、より見つけやすくするための良い方法です。</li> + <li>車輪の再発明ではないこと: MDN Web Docs のドキュメントは完全であることを誇りとしています。つまり、重要なリファレンスやチュートリアルはすべて他の場所にリンクするのではなく、サイト上に書く必要があるということです。既存のチュートリアルをここに置くことは、それを書く必要がないことを意味します。 ;-)</li> + <li>改訂とメンテナンス: あなたのコンテンツを MDN Web Docs に掲載すると、ライターチームとコミュニティの全面的な支援を受けて、作品のレビュー、編集、メンテナンスを行うことができます。</li> +</ul> + +<h2 id="Should_you_migrate_the_content" name="Should_you_migrate_the_content">コンテンツを移行すべきか</h2> + +<p>コンテンツの質が高く、上記のコンテンツタイプの基準を満たしているのであれば、移行しても良さそうです。しかし、まずは以下の点を考慮してから移行するようにしましょう。</p> + +<ul> + <li>コンテンツの重複: 移動させたいリソースは、すでに MDN Web Docs 上にあるコンテンツと重複していますか？もしそうであれば、別のリソースを移動させるのではなく、既存のリソースを改善することのほうが意味があるかもしれません。外部リソースが既存のリソースよりもはるかに優れている場合は、そのリソースを移動し、古いリソースが新しいリソースにリダイレクトされていることを確認してください。</li> + <li>どこに置くか: リソースの移動先がわからない場合は、まず私たちに相談してください (<a href="/ja/docs/MDN/Feedback#Join_the_conversation">会話に参加する</a>を参照してください)。</li> + <li>所有権。コンテンツの権利を所有していない場合は、所有者の許可を得ずに移動することはできません。まず所有者に連絡して、それについて話し合う必要があります。コンテンツがある種の寛容なライセンススキーム (クリエイティブ・コモンズやGPLなど) の下で公開されている場合は、ライセンス条件が満たされていることを確認してください。気軽に私たちに相談してください。</li> + <li>コミュニティの満足度を維持する: コンテンツを所有していても、その周りにコミュニティがある場合は、コミュニティに相談する必要があります - 彼らの意見を聞き、何が起こっているのかを理解してもらい、コンテンツの移動に伴う混乱や迷惑を最小限に抑えましょう。</li> + <li>リダイレクト: コンテンツリソースを移動する際には、リンクが切れないように、古いコンテンツを新しい場所にリダイレクトするのが一般的です。これが意味を成さない場合もあります。例えば、移動したコンテンツがオリジナルのテンプレートのコピーであり、両方のコンテンツが存在する文脈の中でしか意味を成さない場合などです。新しいバージョンへのリンクをどこかで提供することで、2つの関係が明確になることがよくあります。</li> + <li>意味のあるものにする。コンテンツが移動された場合、古い場所と新しい場所にあるリソースはまだ意味がありますか？これを確実にするために、説明やナビゲーションメニューを更新する必要があるかもしれません。</li> +</ul> + +<h2 id="Workflow_for_migration" name="Workflow_for_migration">移行のワークフロー</h2> + +<p>以下は、コンテンツを MDN Web Docs に移行するためのワークフローの例です。 <a href="https://github.com/w3c/payment-request-info/issues/4">この GitHub の問題</a>で記録されているように、 W3C Payment Request のコードを MDN に移行しました。</p> + +<ol> + <li>移行するリソースを特定する。</li> + <li>コンテンツの所有者を特定し、コンテンツの移動が問題にならないことを確認するために、その所有者や関連するコミュニティと話をします。</li> + <li>移行を支援してくれる MDN Web Docs の担当者を特定します。疑問がある場合は、MDN のコンテンツ担当者である <a href="mailto:cmills@mozilla.com">Chris Mills</a> に相談してみましょう。</li> + <li>MDN/<a href="https://github.com/mdn/">our GitHub org</a> を見て、コンテンツを置く場所を特定し、既存のコンテンツと重複していないことを確認します (上記参照)。</li> + <li>MDN のスタイルに合うように、必要に応じて変更を加えながらコンテンツを移動させます。</li> + <li>MDN チーム/コミュニティにレビューを依頼します。</li> + <li>必要に応じて、古いリソースから新しい場所にリダイレクトします。</li> +</ol> diff --git a/files/ja/mdn/contribute/howto/remove__experimental__macros/index.html b/files/ja/mdn/contribute/howto/remove__experimental__macros/index.html new file mode 100644 index 0000000000..90c42d4705 --- /dev/null +++ b/files/ja/mdn/contribute/howto/remove__experimental__macros/index.html @@ -0,0 +1,48 @@ +--- +title: 実験的なマクロをいつどのように削除するか +slug: MDN/Contribute/Howto/Remove__Experimental__Macros +tags: + - MDN Meta + - ガイド + - 方法 +translation_of: MDN/Contribute/Howto/Remove_Experimental_Macros +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p class="summary"><span class="seoSummary">MDN 上のページには、ページによって記述された Web 技術機能が実験的でまだ標準化されていないことを読者に通知するための KumaScript <a href="/ja/docs/MDN/Contribute/Structures/Macros">マクロ</a>が含まれています。</span>しかし、実験的としてフラグが設定されている項目は標準化されている可能性がありますが、そのページはマクロを削除するために再訪されません。<span class="seoSummary">これらの「実験的な」マクロを含むページを見直し、実験的でないアイテムからマクロを削除することで、MDN の改善に役立てることができます。</span></p> + +<p>問題のマクロはページ内の特定の項目にフラグを立てる {{TemplateLink("experimental_inline")}} と、ページ全体にフラグを立てる {{TemplateLink("SeeCompatTable")}} です。</p> + +<div class="warning"> +<p><strong>Warning:</strong> <code>SeeCompatTable</code>の使用は推奨しません。互換性に関するすべてのデータは、ブラウザの互換性表とその中の脚注内に表示されることが期待されています。</p> +</div> + +<p>Here is the definition of "experimental" from the <a href="/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions">MDN Definitions and Conventions</a> article:</p> + +<p>{{page("/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions", "Experimental")}}</p> + +<dl> + <dt>Where does this task need to be done?</dt> + <dd> + <p>Pages in the following lists:</p> + + <ul> + <li><a href="https://developer.mozilla.org/search?kumascript_macros=experimental_inline&locale=*" rel="nofollow noopener">All pages on MDN that use <code>\{{experimental_inline}}</code></a> (list item icon)</li> + <li><a href="https://developer.mozilla.org/search?kumascript_macros=experimental_inline&locale=en-US" rel="nofollow noopener">All pages in English that use <code>\{{experimental_inline}}</code></a> (list item icon)</li> + <li><a href="https://developer.mozilla.org/en-US/search?kumascript_macros=SeeCompatTable&locale=*" rel="nofollow noopener">All pages on MDN that use <code>\{{SeeCompatTable}}</code></a> (page banner)</li> + <li><a href="https://developer.mozilla.org/en-US/search?kumascript_macros=SeeCompatTable&locale=en-US" rel="nofollow noopener">All pages in English that use <code>\{{SeeCompatTable}}</code></a> (page banner)</li> + </ul> + </dd> + <dt>What do you need to know to do the task?</dt> + <dd>Knowledge of the standardization or implementation status of the relevant item.</dd> + <dt>What are the steps to do the task?</dt> + <dd> + <ol> + <li>Review the page to see what item or items the macro is associated with.</li> + <li>Determine whether each item is still experimental or not. The compatibility table on the page may be more current than the the macros; you can also test using the item in multiple browsers.</li> + <li>If an item is no longer experimental, remove the "experimental" macro call associated with it. (Note: an item on a summary page that has the {{TemplateLink("experimental_inline")}} macro next to it is often a link to a full reference page, containing the {{TemplateLink("SeeCompatTable")}} macro.</li> + <li>Save the page with a comment about what you did.</li> + <li>If you have removed all "experimental" macros from a page (for inline macros, you might remove only some of them), force a refresh (Shift+Refresh) on the relevant search results page (linked above) to ensure that the list is updated.</li> + </ol> + </dd> +</dl> diff --git a/files/ja/mdn/contribute/howto/report_a_problem/index.html b/files/ja/mdn/contribute/howto/report_a_problem/index.html new file mode 100644 index 0000000000..f51c040c4f --- /dev/null +++ b/files/ja/mdn/contribute/howto/report_a_problem/index.html @@ -0,0 +1,24 @@ +--- +title: MDN の問題を報告する +slug: MDN/Contribute/Howto/Report_a_problem +tags: + - Guide + - Howto + - MDN Meta +translation_of: MDN/Contribute/Howto/Report_a_problem +--- +<div>{{MDNSidebar}}</div> + +<p>時々、 MDN を使っていて問題にぶつかることがあるでしょう。それがサイトの仕組みの問題であっても、文書の内容に関する誤りであっても、自分自身で修正を試みるか、問題を報告することができます。前者が好ましいのですが、後者が管理できる限界である場合もありますし、それでも構いません。</p> + +<h2 id="Documentation_errors_or_requests" name="Documentation_errors_or_requests">記述の誤り、修正のリクエスト</h2> + +<p>MDN は wiki なので、明らかに最高の対処はあなたが見つけた問題点を自分自身で直すことです。しかし、正しい答えを知らなかったり、あなた自身のプロジェクトの締め切りが迫っているなどの事情で、後で誰かが見られるようにひとまず問題をメモしないといけないこともあるでしょう。</p> + +<p>Mozilla のすべての場合と同様に、文書の問題もバグとして報告することになります。<a href="https://github.com/mdn/sprints/issues/new?template=issue-template.md&projects=mdn/sprints/2&labels=user-report">開発者向け文書についてのリクエスト</a> を使用します。この文書についてのリクエストフォームは、私たちが問題の修正を始めるために必要な情報をまとめる役割を果たします。</p> + +<p>もちろん、私たちの文書化コミュニティは忙しいので、あなた自身が修正することが、問題を解決する一番速い方法になることも時々あります。詳しくは<a href="/ja/docs/MDN/Contribute/Howto/Create_and_edit_pages" title="/ja/docs/Project:MDN/Contributing/Creating_and_editing_pages">ページの作成と編集</a>を読んでください。</p> + +<h2 id="Site_bugs_or_feature_requests" name="Site_bugs_or_feature_requests">サイトのバグ報告または機能のリクエスト</h2> + +<p><a href="/ja/docs/MDN/Kuma" title="/ja/docs/Project:MDN/Kuma">Kuma</a> ─ Mozilla が開発し MDN のウェブサイトで使用されているプラットフォーム—は、継続的に開発されている状態です。 私たちの開発者たちは —数々のボランティア貢献者と同じように—着実に改善を重ねています。もしもバグを見つけたり、サイトの問題に突き当たったり、あるいはこのソフトウェアをさらに素晴らしいものにする提案を持っているなら、あなたは <a href="https://github.com/mdn/kuma/issues/new">Kuma のフィードバックフォーム</a> を使って報告を提出できます。性能監視ツールがすでにふさわしい人々に知らせている可能性が高いものの、このフォームをサイトの性能問題を報告するのに使うこともできます。</p> diff --git a/files/ja/mdn/contribute/howto/resolve_a_mentored_developer_doc_request/index.html b/files/ja/mdn/contribute/howto/resolve_a_mentored_developer_doc_request/index.html new file mode 100644 index 0000000000..f268a9957b --- /dev/null +++ b/files/ja/mdn/contribute/howto/resolve_a_mentored_developer_doc_request/index.html @@ -0,0 +1,34 @@ +--- +title: 世話人のいる開発者文書リクエストの解決方法 +slug: MDN/Contribute/Howto/Resolve_a_mentored_developer_doc_request +tags: + - Beginner + - Documentation + - Guide + - MDN Meta +translation_of: MDN/Contribute/Howto/Resolve_a_mentored_developer_doc_request +--- +<div>{{MDNSidebar}}</div> + +<p>MDN Web Docs プロジェクトには、 Mozilla の Bugzilla インスタンスに、変更をリクエストする大きなバックログがあります。問題を修正してリクエストを閉じていただくことによって MDN を改善することができます。</p> + +<h2 id="Where_does_this_need_to_be_done" name="Where_does_this_need_to_be_done">どこにで実施する必要があるのか</h2> + +<p><a href="https://codetribute.mozilla.org/projects/mdn">Mentored MDN bugs on Codetribute</a> から見つけることができます。 Bugzilla の課題は、改善のリクエストや新しい素材や機能のアイディアも含めて、すべて「バグ」と呼ばれています。このリストのバグは MDN に初めて協力している人にとって良いものと判断されたものであり、問題を解決する上でガイダンスやアドバイスを行ってくれる世話人が割り当てられています。</p> + +<h2 id="What_do_you_need_to_know_to_do_the_task" name="What_do_you_need_to_know_to_do_the_task">タスクを実行するのに知っておく必要があることは何か</h2> + +<p>選択した作業のリクエストの主題に詳しい必要があります。MDN の編集や <a href="https://www.bugzilla.org/">Bugzilla</a> の利用にいくらか馴染んでおくといいでしょう。</p> + +<h2 id="What_are_the_steps" name="What_are_the_steps">どのようなステップで行うのか</h2> + +<ol> + <li>関心のありそうで、自分の知識の範囲内にあるリクエストを選択してください。完全に分かっていないものを選択しても、その中で必要なことを合理的に学ぶことができるのであれば構いません。</li> + <li>リクエストを注意深く読んで、何がリクエストされているかを確認してください。また、 <strong>Mentors</strong> (世話人) フィールドに挙がっている名前に注意してください。世話人は、あなたのような人がリクエストを処理することを助けるために打ち込んでいる人です。</li> + <li>まだ済んでいないのであれば、 <a href="https://bugzilla.mozilla.org/createaccount.cgi">Bugzilla のアカウントを作成してください。</a></li> + <li>処理するリクエストを決めたら、リクエストを自分自身に割り当ててください。 <strong>Assigned To</strong> フィールド (名前やメールアドレスを入れるところ) の隣にある "take" リンクをクリックし、それから <strong>Save Changes</strong> ボタンをクリックしてください。世話人はリクエストの所有権をあなたが取ったことを知ります。</li> + <li>MDN でリクエストを満たすために必要な作業を行います。世話人に質問する必要があれば、リクエストにコメントを追加してください。仕事が基本的に終わったか、世話人にレビューを依頼するのもいいでしょう。</li> + <li>リクエストが満たされたことをあなたと世話人が確認したら、 <strong>Status</strong> を RESOLVED に変更し、解決状況を FIXED にして <strong>Save Changes</strong> をクリックしてください。</li> +</ol> + +<p>以上です。文書のバグ修正は完了です。</p> diff --git a/files/ja/mdn/contribute/howto/set_the_summary_for_a_page/index.html b/files/ja/mdn/contribute/howto/set_the_summary_for_a_page/index.html new file mode 100644 index 0000000000..0c560dbc04 --- /dev/null +++ b/files/ja/mdn/contribute/howto/set_the_summary_for_a_page/index.html @@ -0,0 +1,116 @@ +--- +title: ページに概要を設定するには +slug: MDN/Contribute/Howto/Set_the_summary_for_a_page +tags: + - Documentation + - Guide + - Howto + - MDN Meta + - SEO + - Summaries + - Summary +translation_of: MDN/Contribute/Howto/Set_the_summary_for_a_page +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p><span class="seoSummary">この記事では、 MDN Web Docs サイトにおける <strong>SEO summary</strong> (<strong>description</strong> または単に <strong>summary</strong> とも) を設定する方法を示します。</span>この概要はいくつもの用途で使用されます。</p> + +<ul> + <li>Google を始めとする検索エンジンで、ページを列挙し索引をつけるのに役立てるために使われます。</li> + <li>検索エンジンが検索結果ページにこの概要を表示して、読み手が自分のニーズに最も近いページを選択するための手助けになります。</li> + <li>MDN のメニューや主題のランディングページが、記事の題名の下によくこの概要を表示し、こちらもユーザーが探している情報を見つけるための手助けになります。</li> + <li>MDN 上のリンクでは、よく概要のテキストを含むツールチップを表示し、クリックして記事を読む前にユーザーに概要が見られるようにしています。</li> +</ul> + +<p>したがって、概要は記事自体の文脈でも、他の文脈内に単独で表示された場合でも、意味が分かるようにしてください。また、概要のテキストを書く際には <a href="/ja/docs/MDN/Contribute/Guidelines/Writing_style_guide">MDN 執筆スタイルガイド</a>を意識しておいてください。</p> + +<h2 id="The_default_summary" name="The_default_summary">既定の概要</h2> + +<p>概要のないページは、既定の概要が明確に設定されます。既定では、概要のテキストは、 {{Glossary("HTML")}} の最初の題名ではなくテキストの内容と見られるブロックのテキスト全体です。しかし、これが使用するのに最適なテキストとはならない可能性がいくつもあり得ます。</p> + +<ul> + <li>最初のテキストブロックが、有益な記事の内容の概要ではなく、余談や何らかの注意書きである場合。</li> + <li>最初のテキストブロックが内容の段落であるものの、良い記事の概要を含んでいない場合。</li> + <li>テキストが長すぎる (または短すぎる) 場合。</li> +</ul> + +<p>明示的にページの概要を設定し、概要ができるだけ有益になるようにするのが最善です。</p> + +<h2 id="Setting_the_summary" name="Setting_the_summary">概要の設定</h2> + +<p>ページの概要の設定についての方法を見てみましょう。</p> + +<div class="note"><strong>訳注:</strong> 以下の説明は、英語版における操作方法です。英語からの翻訳ページの場合は、まず英語版の概要を修正した上で、日本語版ページ翻訳を反映してください。</div> + +<h3 id="What_is_the_task" name="What_is_the_task">どのような作業か</h3> + +<p>他の文脈で概要として使用するページ内のテキストをマークします。適切なテキストが利用できない場合は、適切な短いテキストを書く作業も含まれるかもしれません。</p> + +<h3 id="どこで行う必要があるのか">どこで行う必要があるのか</h3> + +<p>概要のないページ、概要があるが有益ではないページ、概要が推奨されるガイドラインに合っていないページです。</p> + +<h3 id="What_do_you_need_to_know_to_do_the_task" name="What_do_you_need_to_know_to_do_the_task">この作業で必要なスキル</h3> + +<p>MDN エディターが使えること。英語でよい文章を書くスキル。良い要約を書くために、主題に十分通じていること。</p> + +<h3 id="What_are_the_steps_to_do_it" name="What_are_the_steps_to_do_it">作業のステップ</h3> + +<ol> + <li>概要を設定するページを選択してください。すでにあるのであれば、素晴らしい！ステップ2まで飛ばしてください。そうでなければ、修正するページを探します。 + <ol> + <li><a href="/ja/docs/MDN/Doc_status">MDN 文書化状況</a>のページで、よく知っている主題 (例えば HTML) の <strong>Sections</strong> の下のセクションをクリックします。<br> + <img alt="" src="https://mdn.mozillademos.org/files/8681/sections.png" style="height: 130px; width: 504px;"></li> + <li>主題についての文書化ステータスのページで、<strong>Summary</strong> 表の <strong>Pages</strong> をクリックします。その主題の節にあるすべてのページの索引が表示されます。左の列にはページへのリンクが、タグと概要は右の列に表示されます。<br> + <img alt="" src="https://mdn.mozillademos.org/files/8675/pages.png" style="height: 82px; width: 361px;"></li> + <li>概要がないか、概要が良くないページを選択します。<br> + <img alt="" src="https://mdn.mozillademos.org/files/8677/summary.png" style="height: 38px; width: 296px;"></li> + <li>リンクをクリックしてそのページへ移動します。</li> + </ol> + </li> + <li>概要を追加したいページに来たら、 <strong>編集</strong> をクリックして、ページを MDN エディター内に開きます。エディターの使用についての情報が必要であれば、 <a href="/ja/docs/MDN/Contribute/Editor">MDN エディター UI のガイド</a>を参照してください。</li> + <li>文脈の外に出しても概要として使える1～2文を探します。必要であれば、1～2文でよい概要として選択できる文になるようテキストを作成または変更します。{{anch("Crafting a good summary", "よい概要の作成")}}を見ると、適切な概要を選択したり作成したりするのに役立ちます。</li> + <li>概要として使用するテキストを選択します。</li> + <li>エディタツールバーの <em>Styles</em> ウィジェットで、 <strong>SEO Summary</strong> を選択します。ページのソースでは、選択したテキストが、 <code>class="seoSummary"</code> をつけた {{HTMLElement("span")}} 要素で囲まれます。<br> + <img alt="" src="https://mdn.mozillademos.org/files/8679/styles.png" style="height: 231px; width: 403px;"></li> + <li>リビジョンのコメントをつけて変更を保存します。コメントは必須ではありませんが、付けることを強く推奨します。そうすることで、他の人が変更を追跡しやすくなります。付けるのを勧める。「SEO summary を設定」のようなものでも充分です。</li> +</ol> + +<h2 id="Crafting_a_good_summary" name="Crafting_a_good_summary">よい概要の作成</h2> + +<p>概要は以下のような、多数の異なるシナリオで使用されます。</p> + +<ul> + <li>Google を始めとする検索エンジンと同様に、 MDN の検索結果ページにおいて記事の説明として</li> + <li>MDN 自身のメニューや主題のランディングページにおける説明として</li> + <li>ユーザーがカーソルを MDN 上の記事へのリンクに当てた時のツールチップの中で</li> +</ul> + +<p>概要を作成する上で、これらのシナリオを念頭に置いておくことが重要です。これらの場面のすべてで概要がよく機能することを保証できるように、以下のガイドラインに従ってみてください。</p> + +<div class="note"> +<p><strong>メモ:</strong> 他に特別に示されていない限り、これらは<em>ガイドライン</em>であり、杓子定規の規則ではありません。これらのガイドラインに合うようにするべきですが、時には避けられない例外もあります。</p> +</div> + +<ul> + <li>概要はページの主題と種類の両方を示すようにしてください。例えば、「このガイドでは、現在画面上に表示されているアニメーションだけを更新するレスポンシブウェブアプリを作成するための Intersection Observer API の使い方を学習します。」は93文字で、どの技術を説明するのか、技術をどう使用するのか、この記事がチュートリアルであることを説明しています。</li> + <li>記事中のどの段落のどこにあるテキストを選択することもできますが、できれば最初の段落内 (または、場合によっては2段落目) にしてください。もし記事の要点がその段落にないのであれば、おそらくページの導入部を書き直す必要があるでしょう。</li> + <li>概要は記事の一部なので、記事本文の文脈内に合うようにする必要があります。</li> + <li>概要の中に他のページへのリンクを設置することが可能です。これは検索エンジンに渡される前に自動的に削除されるので、不利になることはありません。ツールチップとして使用される場合にも削除されます。 MDN のメニューやランディングページ内のページの説明として使用される場合は、とても便利なので、リンクは概要から削除され<em>ません</em>。</li> + <li>概要には、ページに含まれる情報を探している人が検索する可能性が高い重要な用語を適切に選択して含める必要があります。 Intersection Observer API の例の場合、 API の名前、「アニメーション」、「表示されている」、「レスポンシブ」、「ウェブアプリ」などのキーワードがあります。</li> + <li>検索エンジン最適化 (SEO) のためには、概要から取得される値は150文字以下の長さにする必要があります。</li> + <li>通常、<strong>検索エンジンの結果ページ</strong> (<strong>SERP</strong>) には概要の160文字を超える部分が表示されないため、それより長い概要は避けてください。テキストを不意に切り落とすと、人々がリンクをクリックするのを思いとどまらせる可能性があります。</li> + <li>ページ上で表示されない素晴らしい概要を書いて、 <code>"hidden"</code> クラスのブロック内で概要を非表示にするのは魅力的かもしれません。しかし、検索エンジンはユーザーには見えないテキストを無視するため、これは<em>機能しません</em>。</li> +</ul> + +<p>この概要は、本の裏表紙または表紙の内側の宣伝文句 ({{interwiki("wikipedia", "en:blurb")}}) に似ていると考えてください。この短いテキストは、すばやく読者の注意を惹き、読み進める気を起させるものです。読者の注意をすばやくキャッチし、読者に読み進めてもらう必要があります。</p> + +<p>検索エンジンの結果ページと記事テキスト自体の両方でうまく機能する概要を書くことは少し難しいかもしれませんが、現在 MDN はページの内容とは別に SEO 用の概要を作成する方法を提供していませんので、できる範囲でやってください。</p> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Howto/Write_for_SEO">どのように MDN Web Docs で SEO を考慮するか</a></li> +</ul> diff --git a/files/ja/mdn/contribute/howto/tag/index.html b/files/ja/mdn/contribute/howto/tag/index.html new file mode 100644 index 0000000000..2f8c6d0811 --- /dev/null +++ b/files/ja/mdn/contribute/howto/tag/index.html @@ -0,0 +1,381 @@ +--- +title: 適切にタグづけする方法 +slug: MDN/Contribute/Howto/Tag +tags: + - Beginner + - Contribute + - Glossary + - Guide + - Howto + - Intro + - MDN Meta + - Tutorial + - ガイド +translation_of: MDN/Contribute/Howto/Tag +--- +<div>{{MDNSidebar}}</div> + +<p class="summary"><strong>記事のタグ</strong>は、ユーザーが役立つコンテンツに触れるための重要な方法です。コンテンツを分類するために、それぞれのページは通常いくつかのタグを持っています。<span class="seoSummary">このページでは、読者が情報を見つけやすく、また私たち自身が整理しやすくするために、ページにタグ付けする最良の方法を説明します。</span></p> + +<p>タグ編集のユーザーインターフェイスのヘルプは、エディターガイドの<a href="/ja/docs/MDN/Contribute/Editor/Basics#The_tags_box">タグ付けの節</a>を見てください。</p> + +<p>以下に説明するように、タグを適切に使ってください。そうしないと、自動化ツールからコンテンツ一覧や、ランディングページや、記事のクロスリンクを正しく生成できません。</p> + +<div class="blockIndicator warning"> +<p><strong>翻訳者へのメモ:</strong> このページに掲載されているタグを翻訳<em>しない</em>でください。これらは、特定のサイト管理作業や自動データ処理など、特定の目的のために使用されており、翻訳することでこれらのプロセスを壊すことになります。</p> +</div> + +<h2 id="How_MDN_uses_tags" name="How_MDN_uses_tags">MDN のタグの用途</h2> + +<p>MDN ではタグがいくつかの用途で使われています。</p> + +<dl> + <dt>{{anch("Document category", "文書の分類")}}</dt> + <dd>どの種類の文書か。リファレンスであるか。チュートリアルであるか。ランディングページであるか。訪問者がこれらのタグを使って検索の絞り込みをすることができるので、本当に重要です。</dd> + <dt>{{anch("Topic", "トピックの識別")}}</dt> + <dd>何に関する記事なのか。 API についてなのか。 DOM か、 グラフィックか。また、これらは検索の絞り込みに使えるので重要です。</dd> + <dt>{{anch("API identification", "API の識別")}}</dt> + <dd>API について記述するリファレンスページは、 API についての要素（どのインターフェイスの一部なのか、そのページで扱うプロパティもしくはメソッド）を特定することで分類されます。</dd> + <dt>{{anch("Technology status", "技術の状態")}}</dt> + <dd>その技術の状態は何か。標準外 (non-standard) か、非推奨 (deprecated) か、廃止 (obsolete) か、実験的 (experimental) か。</dd> + <dt>{{anch("Skill level", "スキルレベル")}}</dt> + <dd>チュートリアルとガイド向け、どれだけ記事で扱う題材が進んでいるのか?</dd> + <dt>{{anch("Document metadata", "文書メタデータ")}}</dt> + <dd>物書きのコミュニティは、特定の作業が必要となるページの情報を追跡するのにタグを使います。</dd> +</dl> + +<h2 id="Tag_type_guide" name="Tag_type_guide">タグの種類のガイド</h2> + +<p>タグの種類と取りうる値の簡単なガイドをします。</p> + +<h3 id="Document_category" name="Document_category">文書のカテゴリ</h3> + +<p>記事に対してこれらのカテゴリの中の1つをタグ付けすれば、自動化ツールがランディングページや目次などをより正確に作成するのに役立ちます。新しい検索システムでは、これらの用語を使って、訪問者が望むリファレンスやガイド情報の場所を位置付けることができます。</p> + +<p>下記のカテゴリ名を標準的なタグ付け用語として使っています。</p> + +<dl> + <dt><code>{{Tag("Intro")}}</code></dt> + <dd>この記事はあるトピックについての入門的な素材を提供します。できれば、それぞれの技術分野に Intro は1つだけであるべきです。</dd> + <dt><code>{{Tag("Reference")}}</code></dt> + <dd>この記事は API、要素、属性、プロパティ、などに関するリファレンスの資料を含んでいます。</dd> + <dt><code>{{Tag("Landing")}}</code></dt> + <dd>このページはランディングページです。</dd> + <dt><code>{{Tag("Guide")}}</code></dt> + <dd>この記事は手順書やガイドのページです。</dd> + <dt><code>{{Tag("Example")}}</code></dt> + <dd>この記事はコード例のページや、コード例を含むページです (つまり、1行の「文法の例」ではなく、実際に利用できるコードの断片です)。</dd> +</dl> + +<h3 id="Topic" name="Topic">トピック</h3> + +<p>記事のトピックの範囲を識別することで、よりよい検索結果を作り出すのに役立ちます（ランディングページとナビゲーションも同様）。</p> + +<p>新しいトピック分野を指定する際にはいくらか自由度がありますが、 API や技術の名前に制限しようとしています。以下のような有用な例があります。</p> + +<ul> + <li><code>{{Tag("HTML")}}</code></li> + <li><code>{{Tag("CSS")}}</code></li> + <li><code>{{Tag("JavaScript")}}</code> ("S" は大文字です!)</li> + <li><code>{{Tag("Document")}}</code></li> + <li><code>{{Tag("DOM")}}</code></li> + <li><code>{{Tag("API")}}</code> 個々の API の概要、インターフェイス、メソッド、プロパティ</li> + <li><code>{{Tag("Method")}}</code> API の個々のメソッド</li> + <li><code>{{Tag("Property")}}</code> API の個々のプロパティ</li> + <li><code>{{Tag("Graphics")}}</code></li> + <li><code>{{Tag("SVG")}}</code></li> + <li><code>{{Tag("WebGL")}}</code></li> + <li><code>{{Tag("Tools")}}</code></li> + <li><code>{{Tag("Web")}}</code></li> + <li><code>{{Tag("Element")}}</code></li> + <li><code>{{Tag("Extensions")}}</code> および <code>{{Tag("WebExtensions")}}</code> ウェブ拡張機能の文書。</li> +</ul> + +<p>一般的に、トピックを識別するタグは、関連する多数のページがあるインターフェイス (例えば様々なプロパティやメソッドのページがある <a href="/ja/docs/Web/API/Node">Node</a> など) の名前や、技術全体の種類の名前であるべきです。例えば、 WebGL についてのページは <code>Graphics</code> と <code>WebGL</code> でタグ付けしたくなるでしょうが、 {{HTMLElement("canvas")}} に関するページは <code>HTML</code>, <code>Element</code>, <code>Canvas</code>, <code>Graphics</code> になるでしょう。</p> + +<h4 id="Mozilla-specific_content" name="Mozilla-specific_content">Mozilla 固有のコンテンツ</h4> + +<p>これらのタグは、 Mozilla 固有のコンテンツでのみ使われます。</p> + +<ul> + <li><code>{{Tag("Mozilla")}}</code></li> + <li><code>{{Tag("Firefox")}}</code></li> + <li><code>{{Tag("Gecko")}}</code></li> + <li><code>{{Tag("XUL")}}</code></li> + <li><code>{{Tag("XPCOM")}}</code></li> +</ul> + +<h3 id="API_identification" name="API_identification">API の識別</h3> + +<p>API リファレンスの中では、それぞれの記事が API のどの部分に対応するのかを識別できるようにしてください。</p> + +<dl> + <dt><code>{{tag("Interface")}}</code></dt> + <dd>インターフェイスに関する主要な記事にはこのタグをつけてください。例: {{DOMxRef("RTCPeerConnection")}}</dd> + <dt><code>{{tag("Constructor")}}</code></dt> + <dd>それぞれのインターフェイスには、 "Constructor" とタグ付けされたページが最大1ページある場合があります。これはインターフェイスのコンストラクターです。ページは {{DOMxRef("RTCPeerConnection.RTCPeerConnection()")}} のように、インターフェイスと同じ名前にしてください。.</dd> + <dt><code>{{tag("Property")}}</code></dt> + <dd>インターフェイス中の特定のプロパティを説明する記事には、すべてこのタグが必要です。例えば、 {{DOMxRef("RTCPeerConnection.connectionState")}} を参照してください。</dd> + <dt><code>{{tag("Method")}}</code></dt> + <dd>インターフェイスのメソッドについて記述している記事には、全てこのタグが必要です。例えば、 {{DOMxRef("RTCPeerConnection.createOffer()")}} を参照してください。</dd> +</dl> + +<p>加えて、リファレンスページはインターフェイス、プロパティ、メソッドの名前でタグ付けする必要があります。例:</p> + +<dl> + <dt>{{DOMxRef("RTCPeerConnection")}} インターフェイス</dt> + <dd>"RTCPeerConnection" を、他の関連するタグ ("Interface", "WebRTC", "WebRTC API", "API", "Reference" など) と共にタグ付けしてください。</dd> + <dt>{{DOMxRef("RTCPeerConnection.createOffer()")}} メソッド</dt> + <dd>"RTCPeerConnection" と "createOffer" (注: タグ名に括弧を含め<em>ない</em>でください) を、他の関連するタグ、 "WebRTC", "WebRTC API", "API", "Reference" などと共にタグ付けしてください。関連性に応じて "Offer" や "SDP" などの関連するタグでタグ付けすることも検討してください。</dd> + <dt>{{DOMxRef("RTCPeerConnection.iceConnectionState")}} プロパティ</dt> + <dd>"RTCPeerConnection" と "iceConnectionState" を、他の関連するタグ、 "WebRTC", "WebRTC API", "API", "Reference" などと共にタグ付けしてください。 "ICE" もタグ付けすることを検討してください。</dd> +</dl> + +<h3 id="Technology_status" name="Technology_status">技術の状態</h3> + +<p>読者が技術の利用可能性を理解しやすくするため、技術の仕様の状態に関するラベルをページに付与するためにタグ付けします。これは、仕様がどのようなものであるか、技術が仕様プロセスにどれだけ届いているか (それは仕様表の役割) を実際に説明するほど詳細ではありませんが、読者が記事に書かれた技術を利用することが良いことかどうかを一目で判断するのに役立ちます。</p> + +<p>これらのタグとして有効な値は以下の通りです。</p> + +<dl> + <dt><code>{{Tag("Read-only")}}</code></dt> + <dd>読み取り専用のプロパティや属性を記すリファレンスページにこのタグを適用してください。</dd> + <dt><code>{{Tag("Non-standard")}}</code></dt> + <dd>このページで説明している技術や API が、実装しているブラウザーで安定しているかどうかにかかわらず、標準化されていないことを示します (安定していない場合は {{Tag("Experimental")}} を使用してください)。このタグを使用しない場合は、読者は技術が標準化されていると仮定します。ページ上の互換性テーブルで、どのブラウザーがこの技術や API に対応しているかを明確にしてください。</dd> + <dt><code>{{Tag("Deprecated")}}</code></dt> + <dd>このページで述べられている技術や API は、仕様の中で非推奨 (deprecated) とマークされ、削除される予定ですが、現在のバージョンのブラウザーでは一般的にまだ利用できるものです。</dd> + <dt><code>{{Tag("Obsolete")}}</code></dt> + <dd>この技術や API は廃止 (obsolete) とみなされており、最新ブラウザーの全てまたは多くから削除されて（または削除しようとされて）いるものです。</dd> + <dt><code>{{Tag("Experimental")}}</code></dt> + <dd>この技術は標準化されておらず、標準化されるかどうかわからない実験的な技術や API です。これが実装されるかどうかは、ブラウザーのエンジンの変更 (ふつうは1回) に依存します。その技術が (ドラフト版も含め) 仕様に加えられていない場合は、 {{tag("Non-standard")}} もタグ付けしてください。</dd> + <dt><code>{{Tag("Needs Privileges")}}</code></dt> + <dd>この API は、コードが実行される端末へのアクセス権限を要求します。</dd> + <dt><code>{{Tag("Certified Only")}}</code></dt> + <dd>この API は認証されたコードのみで動作します。</dd> +</dl> + +<p>これらでタグ付けしたとしても、記事の<a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables">互換性テーブル</a>を省略してよいことにはなりません。互換性テーブルは常にあるべきです。</p> + +<h3 id="Skill_level" name="Skill_level">スキルレベル</h3> + +<p>スキルレベルの種類のタグは、ガイドやチュートリアル (つまり <code>Guide</code> とタグ付けされたページ) にのみ使用し、ユーザーがその技術にどれほど慣れ親しんでいるかに基づいてチュートリアルを選択する手助けになります。これには3つの値があります。</p> + +<dl> + <dt><code>{{Tag("Beginner")}}</code></dt> + <dd>その技術を使ったことがなかったり、ちょっと触れただけの読者に紹介するために作られた記事です。</dd> + <dt><code>{{Tag("Intermediate")}}</code></dt> + <dd>その技術を使い始めているものの、エキスパートにはなっていない人を対象とした記事。</dd> + <dt><code>{{Tag("Advanced")}}</code></dt> + <dd>技術や読者の可能性を伸ばすための記事。</dd> +</dl> + +<h3 id="Document_metadata" name="Document_metadata">文書メタデータ</h3> + +<p>執筆コミュニティが、特定の種類の作業を必要とする記事にタグを使ってラベル付けをしています。よく使用しているものの一覧は以下の通りです。</p> + +<dl> + <dt><code>{{Tag("Draft")}}</code></dt> + <dd>記事が完全ではなく、少なくとも理論的には積極的に更新されています (ただし、忘れられている可能性もあります)。潜在的なコンテンツの衝突を避けるため、変更する前に最新の投稿者に確認してください。</dd> + <dt><code>{{Tag("NeedsCompatTable")}}</code></dt> + <dd>この記事はブラウザー間の機能の互換性を記述する表が必要です。ブラウザーの互換性に協力する際のガイドは<a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables">こちらを参照</a>してください。</dd> + <dt><code>{{Tag("NeedsContent")}}</code></dt> + <dd>記事はスタブであるか、情報が不足しているかです。このタグは、誰かが内容を見直して詳細を追加したり、記事を書き終えたりするべきであることを意味します。</dd> + <dt><code>{{Tag("NeedsExample")}}</code></dt> + <dd>記事には、その記事の要点を説明するために役立つ例が必要です。これらの例では、<a href="/ja/docs/Project:MDN/Contributing/How_to_help/Code_samples">ライブサンプルシステム</a>を利用してください。</dd> + <dt><code>{{Tag("NeedsLiveSamples")}}</code></dt> + <dd>この記事には、<a href="/ja/docs/Project:MDN/Contributing/How_to_help/Code_samples">ライブサンプルシステム</a>を使用するように更新する必要がある例があります。</dd> + <dt><code>{{Tag("NeedsMarkupWork")}}</code></dt> + <dd>この記事は、ページのマークアップを改善する必要があります (ふつうはページの内容のほとんどまたはすべてが {{HTMLElement("p")}} タグから成るため)。</dd> + <dt><code>{{Tag("NeedsSpecTable")}}</code></dt> + <dd>この記事には、この機能がどの仕様書で定義されたかを示す一覧表が必要です。</dd> + <dt><code>{{Tag("NeedsUpdate")}}</code></dt> + <dd>このコンテンツが古くなっており、更新する必要があります。</dd> + <dt><code>{{Tag("l10n:exclude")}}</code></dt> + <dd>このコンテンツはローカライズする価値がなく、ローカライズ状況ページに表示されません。</dd> + <dt><code>{{Tag("l10n:priority")}}</code></dt> + <dd>このコンテンツは重要であり、 MDN の翻訳者にとって重要だとマークするべきです。ローカライズ状況ページの優先度の高い記事の表に表示されます。</dd> +</dl> + +<h2 id="Putting_it_all_together" name="Putting_it_all_together">すべて一緒に設定する</h2> + +<p>それぞれのページについて、いくつかの異なるタイプのタグを指定することになるでしょう、例えば</p> + +<dl> + <dt>WebGL の初心者向けチュートリアル</dt> + <dd>{{Tag("WebGL")}}, {{Tag("Graphics")}}, {{Tag("Guide")}}, {{Tag("Beginner")}}</dd> + <dt>{{HTMLElement("canvas")}} のリファレンスページ</dt> + <dd>{{Tag("Canvas")}}, {{Tag("HTML")}}, {{Tag("Element")}}, {{Tag("Graphics")}}, {{Tag("Reference")}}</dd> + <dt>Firefox 開発ツールを列挙したランディングベージ</dt> + <dd>{{Tag("Tools")}}, {{Tag("Firefox")}}, {{Tag("Landing")}}</dd> +</dl> + +<h2 id="Tagging_and_search_filters" name="Tagging_and_search_filters">タグ付けと検索フィルター</h2> + +<p>検索フィルターは、 MDN のページを正しくタグ付けしないと正しく動作しません。検索フィルターと検索するタグの一覧表は以下の通りです。(検索フィルターは <a href="https://wiki.developer.mozilla.org">wiki</a> (編集) サイトでのみ使用されます。読み込み専用サイトではフィルターなしの別の検索システムを使用しています。)</p> + +<div class="blockIndicator note"> +<p><strong>注:</strong> もし「タグ名」のところに複数のタグがあった場合は、それらのタグのうち1つ以上が一致すれば検索されるという意味です。</p> +</div> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">フィルターグループ</th> + <th scope="col">検索フィルター名</th> + <th scope="col">タグ名</th> + </tr> + </thead> + <tbody> + <tr> + <th rowspan="22" scope="row" style="vertical-align: baseline;">トピック</th> + <td>API および DOM</td> + <td>{{Tag("API")}} || {{Tag("DOM")}} {{Deprecated_Inline}}</td> + </tr> + <tr> + <td>アドオンと拡張機能 {{Deprecated_Inline}}</td> + <td>{{Tag("Add-ons")}} || {{Tag("Extensions")}} || {{Tag("Plugins")}} || {{Tag("Themes")}} || {{Tag("WebExtensions")}}</td> + </tr> + <tr> + <td>CSS</td> + <td>{{Tag("CSS")}}</td> + </tr> + <tr> + <td>Canvas</td> + <td>{{Tag("Canvas")}}</td> + </tr> + <tr> + <td>Firefox</td> + <td>{{Tag("Firefox")}}</td> + </tr> + <tr> + <td>Firefox OS</td> + <td>{{Tag("Firefox OS")}}</td> + </tr> + <tr> + <td>ゲーム</td> + <td>{{Tag("Games")}}</td> + </tr> + <tr> + <td>HTML</td> + <td>{{Tag("HTML")}}</td> + </tr> + <tr> + <td>HTTP</td> + <td>{{Tag("HTTP")}}</td> + </tr> + <tr> + <td>JavaScript</td> + <td>{{Tag("JavaScript")}}</td> + </tr> + <tr> + <td>Marketplace {{Non-standard_Inline}}</td> + <td>{{Tag("Marketplace")}}</td> + </tr> + <tr> + <td>MathML</td> + <td>{{Tag("MathML")}}</td> + </tr> + <tr> + <td>Mobile</td> + <td>{{Tag("Mobile")}}</td> + </tr> + <tr> + <td>Open Web Apps {{Non-standard_Inline}}</td> + <td>{{Tag("Apps")}}</td> + </tr> + <tr> + <td>SVG</td> + <td>{{Tag("SVG")}}</td> + </tr> + <tr> + <td>ウェブ開発</td> + <td>{{Tag("Web Development")}}</td> + </tr> + <tr> + <td>ウェブ標準</td> + <td>{{Tag("Web")}}</td> + </tr> + <tr> + <td>WebExtensions</td> + <td>{{Tag("WebExtensions")}}</td> + </tr> + <tr> + <td>WebGL</td> + <td>{{Tag("WebGL")}}</td> + </tr> + <tr> + <td>ドキュメントの執筆</td> + <td>{{Tag("MDN Meta")}}</td> + </tr> + <tr> + <td>XPCOM {{Non-standard_Inline}}</td> + <td>{{Tag("XPCOM")}}</td> + </tr> + <tr> + <td>XUL {{Non-standard_Inline}}</td> + <td>{{Tag("XUL")}}</td> + </tr> + <tr> + <th rowspan="3" scope="row" style="vertical-align: baseline; white-space: nowrap;">{{anch("Skill level", "スキルレベル")}}</th> + <td>エキスパート</td> + <td>{{Tag("Advanced")}}</td> + </tr> + <tr> + <td>中級者</td> + <td>{{Tag("Intermediate")}}</td> + </tr> + <tr> + <td>学習中</td> + <td>{{Tag("Beginner")}}</td> + </tr> + <tr> + <th rowspan="7" scope="row" style="vertical-align: baseline; white-space: nowrap;">文書の種類</th> + <td>Docs</td> + <td><em>Hacks やその他の MDN コンテンツを除く、 docs コンテンツに限定して検索する。</em></td> + </tr> + <tr> + <td>デモ</td> + <td><em>この文書種別は MDN Web Docs では使われていません。</em></td> + </tr> + <tr> + <td>ツール</td> + <td>{{Tag("Tools")}}</td> + </tr> + <tr> + <td>コード例</td> + <td>{{Tag("Example")}}</td> + </tr> + <tr> + <td>How-To & Tutorial</td> + <td>{{Tag("Guide")}}</td> + </tr> + <tr> + <td>Developer Profiles</td> + <td><em>検索結果に MDN サイトの開発者プロフィールを入れます。</em></td> + </tr> + <tr> + <td>External Resources</td> + <td><em>開発チームはこれを判別中です...</em></td> + </tr> + </tbody> +</table> + +<h2 id="Tagging_problems_you_can_fix" name="Tagging_problems_you_can_fix">修正可能なタグ付けの問題</h2> + +<p>修正できるタグの問題が、次のように数種類あります:</p> + +<dl> + <dt>タグなし</dt> + <dd>一般的に記事には<em>少なくとも</em> "{{anch("Document category", "カテゴリー")}}" タグと "{{anch("Topic", "トピック")}}" タグが必要です。常にその他のタグもふさわしく、しかし最低限のタグがあるように手助けしていただけると、あなたは文書化のヒーローになります!</dd> + <dt>タグがタグ付けの規約に従っていない</dt> + <dd>タグがこのページの標準にそっていないページは修正してください。<br> + なお、たまにローカライズされたタグ (<code>Référence</code> のような) を英語ページ内に見かけることがあります。これは <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=776048">Kumaのバグ</a>のせいで、このバグのためにタグを消してもまた出てきます。このバグは<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=776048#c37">修正済みで</a>、残っているローカライズされたタグは指定されたら片付けられます。</dd> + <dt>正しくないタグ</dt> + <dd>HTML についての記事を探していてそれが "JavaScript" とタグ付けられていたら、多分間違いです! 同様に記事が Mozilla 内部のことを書いていて "Web" タグがあったら、これも多分間違いです。これらのタグを削除して、適切なタグが欠けていたら追加します。スペルミスのタグ (例 "Javascript" は、タグが大文字小文字を区別しないのでマッチしますが、間抜けになるのはやめましょう!)も訂正してください。</dd> + <dt>タグの欠落</dt> + <dd>記事のタグがあるけど必要なすべてはない場合、気軽に追加してください。例えば、 JavaScript リファレンスページが "JavaScript" だけで (正しく) タグ付けられている場合、同じく "Reference" とタグ付けするよう誘われています!</dd> + <dt>タグのスパム</dt> + <dd>この陰湿な獣は、すべての中で最も不愉快なタグの問題です: あるウェブ害虫が、その糞をページタグに堆積させています (例えば、"Free warez!" や "Hey I was browsing your site and wanted to ask you if you could help me solve this problem I'm having with Flash crashing all the time" など)。これらは直ちに削除する必要があります。彼らは醜い、醜いし、長く残ってしまうと管理不能となり、 {{Glossary("SEO")}} にも悪影響です。</dd> +</dl> + +<p>これらの問題を見かけたら、 <a href="/ja/docs/Project:MDN/Contributing/Getting_started#Logging_into_MDN">MDN にログインして</a> MDN ウィンドウの右上の編集をクリックします。エディターが読み込まれたら、ページの最下部までスクロールして、そこにタグボックスが見つかります。タグ付けのインターフェイスの詳細については、<a href="/ja/docs/MDN/Contribute/Editor">MDN エディターガイド</a>内の「<a href="/ja/docs/MDN/Contribute/Editor/Basics/Tags">タグボックス</a>」を参照してください。</p> diff --git a/files/ja/mdn/contribute/howto/tag_javascript_pages/index.html b/files/ja/mdn/contribute/howto/tag_javascript_pages/index.html new file mode 100644 index 0000000000..22a77ce10c --- /dev/null +++ b/files/ja/mdn/contribute/howto/tag_javascript_pages/index.html @@ -0,0 +1,76 @@ +--- +title: JavaScript ページのタグ付け方法 +slug: MDN/Contribute/Howto/Tag_JavaScript_pages +tags: + - Guide + - Howto + - JavaScript + - MDN Meta + - ガイド + - 入門 +translation_of: MDN/Contribute/Howto/Tag_JavaScript_pages +--- +<div>{{MDNSidebar}}</div> + +<p class="summary"><strong>タグ付け</strong>はページにメタ情報を追加することであり、検索ツール等において関連するコンテンツをグループ化することができます。</p> + +<dl> + <dt><strong>どこに設定すべき？</strong></dt> + <dd><a href="/en-US/docs/Web/JavaScript/Doc_status#No_tags">JavaScript 関連のページでタグの無いもの</a> (<a href="/ja/docs/MDN/Doc_status/JavaScript#No_tags">日本語版</a>)のどれか{{訳注("日本語版のステータスページにはタグの無いページのリストがありません")}}</dd> + <dt><strong>タグ付けするために知っておくべきことは？</strong></dt> + <dd>メソッドやプロパティとは何か、というような、基本的な JavaScript コーディングの知識。</dd> + <dt><strong>どんな手順でやればいいの？</strong></dt> + <dd> + <ol> + <li>上記リンクにあるリストから、対象のページを選びます。</li> + <li>記事のリンクをクリックして、ページをロードします。</li> + <li>ページがロードできたら、上の方にある <strong>編集</strong> ボタンを押します。するとMDNエディターが始まります。</li> + <li>最低でも <code>JavaScript</code> タグは付けるべきです。以下のようなタグも付けましょう。 + <table class="standard-table"> + <thead> + <tr> + <th scope="col">タグ</th> + <th scope="col">使う対象のページ</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>Method</code></td> + <td>メソッドのページ</td> + </tr> + <tr> + <td><code>Property</code></td> + <td>プロパティのページ</td> + </tr> + <tr> + <td><code>prototype</code></td> + <td>プロトタイプのページ</td> + </tr> + <tr> + <td>オブジェクトの型名</td> + <td>オブジェクトのメソッドのページ。例えば、 String.fromCharCode には <code>String</code> タグをつけるべき</td> + </tr> + <tr> + <td><code>ECMAScript6 </code> と <code>Experimental</code></td> + <td>新しい ECMAScript バージョンで追加される機能のページ</td> + </tr> + <tr> + <td><code>Deprecated</code></td> + <td>非推奨の (deprecated) 機能のページ (使うことが推奨されないが、まだサポートされている機能)</td> + </tr> + <tr> + <td><code>Obsolete</code></td> + <td>廃止された (obsolete) 機能のページ (最近のブラウザーがサポートしない機能)</td> + </tr> + <tr> + <td>その他</td> + <td>これ以外にどんなタグがあるのかは、 <a href="/ja/docs/MDN/Contribute/Howto/Tag">MDN タグ付け標準</a>をご覧ください。</td> + </tr> + </tbody> + </table> + </li> + <li>コメントを付けて保存します。</li> + <li>完了です！</li> + </ol> + </dd> +</dl> diff --git a/files/ja/mdn/contribute/howto/use_navigation_sidebars/index.html b/files/ja/mdn/contribute/howto/use_navigation_sidebars/index.html new file mode 100644 index 0000000000..c618e45ccb --- /dev/null +++ b/files/ja/mdn/contribute/howto/use_navigation_sidebars/index.html @@ -0,0 +1,91 @@ +--- +title: ナビゲーションサイドバーの使い方 +slug: MDN/Contribute/Howto/Use_navigation_sidebars +tags: + - Documentation + - Draft + - HTML + - MDN + - MDN Meta + - MDN Web Docs + - Macros + - Meta + - NeedsContent + - Tutorial + - sidebars + - マクロ +translation_of: MDN/Contribute/Howto/Use_navigation_sidebars +--- +<p>{{MDNSidebar}}{{Draft}}</p> + +<p>MDN の操作はよくサイドバーを用いて行われ、これは一連の記事や、同じ系列のドキュメントと MDN の他の領域の両方における関連コンテンツを列挙します。 <span class="seoSummary">MDN のサイドバーは自動的には生成されません。ページにサイドバーを入れるには、いくらかのマクロを作成し使用する必要があります。この記事では、 MDN サイドバーマクロの作成と記事内での使用方法の両方の手順を確認します。</span></p> + +<h2 id="Current_MDN_sidebar_macros" name="Current_MDN_sidebar_macros">現在の MDN のサイドバーマクロ</h2> + +<p>MDN には既に、サイドバーを生成するたくさんのマクロがあります。多くは MDN の特定のセクションに特化していますが、他に、特化したものがない文書領域のための一般的なサイドバーを生成するためのものがあります。</p> + +<dl> + <dt>{{TemplateLink("AddonSidebar")}}</dt> + <dd>アドオンの文書を操作するためのサイドバーを挿入します。これは主にブラウザー拡張機能の作成についてのコンテンツです。</dd> + <dt>{{TemplateLink("APIRef")}}</dt> + <dd>API インターフェイスのリファレンスページおよびサブページで使用されるサイドバーを挿入します。</dd> + <dt>{{TemplateLink("CanvasSidebar")}}</dt> + <dd>HTML/DOM Canvas の文書の中で使用されるサイドバーを挿入します。</dd> + <dt>{{TemplateLink("DefaultAPISidebar")}}</dt> + <dd>特化したサイドバーのタイプがない API の API 概要ページで使用することができる既定のサイドバーを挿入します。</dd> + <dt>{{TemplateLink("FirefoxSidebar")}}</dt> + <dd>Firefox に特化した文書で使用されるサイドバーを挿入します。</dd> + <dt>{{TemplateLink("GamesSidebar")}}</dt> + <dd>ウェブ技術を使ったゲーム開発に関する MDN のコンテンツを操作するサイドバーを挿入します。</dd> + <dt>{{TemplateLink("HTMLSidebar")}}</dt> + <dd>MDN の HTML 文書で使用されるサイドバーを挿入します。</dd> + <dt>{{TemplateLink("HTTPSidebar")}}</dt> + <dd>MDN の HTTP 文書内のページで使用するためのサイドバーを挿入します。</dd> + <dt>{{TemplateLink("JSSidebar")}}</dt> + <dd>JavaScript 文書で使用するためのサイドバーを挿入します。</dd> + <dt>{{TemplateLink("LearnSidebar")}}</dt> + <dd>学習エリアのサイドバーを挿入します。</dd> + <dt>{{TemplateLink("MDNSidebar")}}</dt> + <dd>MDN の「メタ文書」、つまり、 MDN Web Docs サイト自体の利用や編集に関する文書を操作するサイドバーを挿入します。このページで実際にマクロが使われているのを見ることができます。</dd> + <dt>{{TemplateLink("ServiceWorkerSidebar")}}</dt> + <dd>サービスワーカーについての文書で使用されるサイドバーを挿入します。</dd> + <dt>{{TemplateLink("SpiderMonkeySidebar")}}</dt> + <dd>SpiderMonkey (Mozilla の JavaScript エンジン) のページに使用するサイドバーを挿入します。</dd> + <dt>{{TemplateLink("ToolsSidebar")}}</dt> + <dd>Firefox 開発ツールについてのページを列挙するサイドバーを挿入します。</dd> + <dt>{{TemplateLink("WebAssemblySidebar")}}</dt> + <dd>WebAssembly に関するリンクを含むサイドバーを挿入します。</dd> + <dt>{{TemplateLink("WebExtAPISidebar")}}</dt> + <dd>ブラウザー拡張 (WebExtension) についての API リファレンス文書を操作するために使われるサイドバーを挿入します。</dd> + <dt>{{TemplateLink("WebGLSidebar")}}</dt> + <dd>WebGL に関するコンテンツの操作を提供するサイドバーを挿入します。</dd> + <dt>{{TemplateLink("WebRTCSidebar")}}</dt> + <dd>MDN の WebRTC 文書の操作を提供するコンテンツのサイドバーを挿入します。</dd> + <dt>{{TemplateLink("XSLTRef")}}</dt> + <dd>XSLT, EXSLT, XPath についての文書のサイドバーを挿入します。</dd> +</dl> + +<h2 id="Using_sidebars" name="Using_sidebars">サイドバーの使用</h2> + +<p>サイドバーをページに追加するには、正しいマクロを探し、それから、サイドバーを挿入したいページで、「編集」ボタンをクリックしてください。ページに {{HTMLElement("p")}} ブロックを追加して、中身はマクロを呼ぶだけにしてください。そうすれば、マクロ呼び出しを追加することができます。通常、サイドバーマクロは引数を必要としませんので、単に次のように書くことができます。</p> + +<pre class="brush: html; no-line-numbers notranslate"><p>\{{MDNSidebar}}</p></pre> + +<p>通常は、これを文書の最初の行に入れてください。一部の文書では、代わりに末尾に入っています。これはうまく動作しますが、一貫性を保証するために、できれば先頭に配置してみてください。</p> + +<p>すでにマクロを呼び出す {{HTMLElement("p")}} ブロックがページの先頭にある場合、例えばバナーを生成する <code>\{{Non-standard_Header}}</code> などがある場合は、次のように同じ {{HTMLElement("p")}} の中にサイドバーのマクロを入れることができます。</p> + +<pre class="brush: html; no-line-numbers notranslate"><p>\{{HTTPSidebar}}\{{Non-standard_Header}}</p></pre> + +<h2 id="Creating_sidebars" name="Creating_sidebars">サイドバーの作成</h2> + +<p><em>詳細は執筆中</em></p> + +<p>{{TemplateLink("SidebarUtilities")}} について触れておきます。</p> + +<p>サイドバーの構築に役立つマクロがいくつかあります。</p> + +<dl> + <dt>{{TemplateLink("ListSubpagesForSidebar")}}</dt> + <dd>指定されたページのサブページを使用して、サイドバー内で利用するために構築されたリンクのツリーを生成します。</dd> +</dl> diff --git a/files/ja/mdn/contribute/howto/write_a_new_entry_in_the_glossary/index.html b/files/ja/mdn/contribute/howto/write_a_new_entry_in_the_glossary/index.html new file mode 100644 index 0000000000..0927f045c1 --- /dev/null +++ b/files/ja/mdn/contribute/howto/write_a_new_entry_in_the_glossary/index.html @@ -0,0 +1,142 @@ +--- +title: 用語集の項目を書いたり参照したりするには +slug: MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary +tags: + - Contributing + - Definition + - Entry + - Glossary + - Guide + - Howto + - MDN Meta + - Term + - Word + - define +translation_of: MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p><span class="seoSummary">この記事では、 <a href="/ja/docs/Glossary">MDN Web Docs の用語集</a>に項目を追加したりリンクしたりする方法について説明します。また、用語集の項目のレイアウトと内容に関するガイドラインも提供します。</span>用語集には、ウェブやウェブ開発に関する MDN コンテンツを読む際に出くわすであろうすべての用語、専門用語、略語、頭字語の定義が記載されています。</p> + +<p>ウェブは常に変化しているため、用語集が完全ではない可能性があります。新しいエントリを投稿したり、問題を修正したりすることで、用語集の更新やギャップを埋めることができます。</p> + +<p>用語集に寄稿することは、誰にとってもウェブをより理解しやすくするための簡単な方法です。高度な技術的スキルは必要ありません。用語集の項目は、簡単で簡潔なものを意図しています。</p> + +<h2 id="How_to_write_an_entry" name="How_to_write_an_entry">項目を執筆する方法</h2> + +<p>用語集に項目が必要なトピックを探している場合は、<a href="/ja/docs/Glossary#Contribute_to_the_glossary">文書化されていない用語のリスト</a>が<a href="/ja/docs/Glossary">用語集のランディングページ</a>の最後にあるので確認してください。これらのリンクをクリックすると、クリックした項目の新しい用語ページが開きます。それから、次の手順に従ってください。</p> + +<p>新たなトピックについての考えがあるならば、新しいタブで以下のボタンを開き、ボタンよりも下にある手順通りにしてください。</p> + +<div class="align-center"><a class="button ignore-external mega positive" href="/en-US/docs/new?parent=4391">用語集に新しい項目を書く</a></div> + +<h3 id="Step_1_Select_a_term_to_explain" name="Step_1_Select_a_term_to_explain">ステップ1: 説明する用語を選ぶ</h3> + +<p>用語集に追加する用語を選択します。どの用語の定義が必要かわからない場合は、<a href="/ja/docs/Glossary#Contribute_to_the_glossary">提案の一覧</a>を見ることができます。いずれかの用語をクリックすると、始めることができます。すでにログインしている場合は、用語をクリックすると MDN エディターが開きます。</p> + +<h3 id="Step_2_Write_a_summary" name="Step_2_Write_a_summary">ステップ2: 要約を書く</h3> + +<p>用語集ページの最初の段落は、その用語の簡潔で短い説明です。できれば、2文以内にしてください。説明を読めばどんな人であってもただちに理解できるような説明であるようにしてください。</p> + +<div class="note"> +<p><strong>注:</strong> インターネット上にある他の定義やコンテンツをコピー＆ペーストしないでください。 (特にウィキペディアは、ライセンスの版の幅が小さいため、 MDN とは互換性がありません。) 用語集の項目は独自の内容にしてください。</p> +</div> + +<h4 id="Writing_a_good_glossary_entry" name="Writing_a_good_glossary_entry">良い用語集の項目を書く</h4> + +<p>必要であれば多少は段落を追加しても良いのですが、気が付くと記事全体を書いてしまいがちです。記事を書くことはすばらしいのですが、用語集の中には作成しないでください。記事をどこに書けばよいのかわからない場合は、気軽に<a href="/ja/docs/MDN/Community#Join_our_mailing_lists">相談してください</a>。</p> + +<p>より良い用語集の項目を書くために考慮すべき簡単なガイドラインがいくつかあります。</p> + +<ul> + <li>用語集の説明文で用語を使用するときや、略語を使用するときには、適切なリンクを作成してください。多くの場合、これは用語集の他のページへのリンクを作成するだけです。 (下記の <a href="#How_to_use_the_Glossary_macro">Glossary マクロの使い方</a>を参照してください。) 用語集の項目の用語に直接関連する用語については、 MDN Web Docs のメイン記事にリンクしてください。</li> + <li>用語集の項目では、記事を追いかけるのが難しくせずにできるのであれば、適切な関連用語 (リンク付きで) を使用してください。関連した有用なリンクのネットワークを持つことで、ページ、または一連のページを使いやすくすることができます。</li> + <li>このページを見つけたいと思ったときに、どのような検索用語を選ぶか考えてみてください。その用語を検索するために使用するすべての単語を使用してみてください。ただし、用語集の項目を無意味にしたり、長くしたり、読みにくくしたりしないようにしてください。</li> +</ul> + +<h4 id="Specifying_the_tooltip" name="Specifying_the_tooltip">ツールチップの設定</h4> + +<p>ほとんどの MDN リンクと同様に、用語集のリンクにカーソルを合わせると、ページの簡単な説明 (この場合、用語の定義の短い要約) が表示されます。既定ででは、ツールチップは用語集の項目の最初の段落全体のテキストを取ります。これはふつうは長すぎます。</p> + +<p>別の方法として、テキストの一部区間をページの概要として割り当てることもできます (これがツールチップのテキストにもなります)。用語の定義を要約する1～2文を選択し、選択されたテキストに <em>SEO Summary</em> スタイルを追加してください。これでツールチップのテキストが定義されます。また、これはページの内容の要約として検索エンジンに送信されるテキストに割り当てられます。そのため、ページの要約を具体的に選択することで、あなたの仕事が検索結果でより目に付くようになります。</p> + +<div class="note"> +<p><strong>注:</strong> できれば、 <em>SEO summary</em> で選択する文字列は 150-160 文字にしてください。多いよりは少ない方がいいことです。</p> +</div> + +<h3 id="Step_3_Expand_with_links" name="Step_3_Expand_with_links">ステップ3:リンクで拡張する</h3> + +<p>用語集の項目は常に<em>詳細情報</em>の節で終わらせてください。この節では、読者が先へ進むための手助けとなるリンクを含むようにしてください。例えば、さらなる詳細がわかるようになるもの、関連した技術を学ぶことができるものなどです。</p> + +<p>リンクは少なくとも以下の3つのグループに分けることをおすすめします。</p> + +<dl> + <dt>一般知識</dt> + <dd>その用語や主題についてのより高水準な情報を提供するリンク群です。例えば、関連する <a href="http://wikipedia.org/">Wikipedia</a> ページへのリンクです。</dd> + <dt>技術情報</dt> + <dd>MDN Web Docs もしくは外部サイトにある、より詳細な技術情報へのリンク群です。</dd> + <dt>学習素材</dt> + <dd>読者がその用語の背景にある技術の利用方法を学ぶことを支援する、チュートリアルや演習問題、その他の素材へのリンク群です。</dd> +</dl> + +<h2 id="Dealing_with_disambiguation" name="Dealing_with_disambiguation">曖昧な言葉の扱い</h2> + +<p>言葉によっては、文脈によって複数の意味を持つことがあります。曖昧さを解決するために、以下のガイドラインに従ってください。</p> + +<ul> + <li>用語の主ページは、 {{TemplateLink("GlossaryDisambiguation")}} マクロを含む曖昧さを表すページでなければなりません。</li> + <li>それぞれの文脈に応じた用語を定義する副ページを設置します。</li> +</ul> + +<p>例を用いて説明します。 <em>signature</em> という用語は、セキュリティ、関数、メールなど3種類以上の文脈で異なる意味持ちます。</p> + +<ol> + <li><a href="/ja/docs/Glossary/Signature">Glossary/Signature</a> のページは {{TemplateLink("GlossaryDisambiguation")}} マクロを含む曖昧さを表すページです。</li> + <li><a href="/ja/docs/Glossary/Signature/Security">Glossary/Signature/Security</a> ページはセキュリティの文脈における署名を定義しているページです。</li> + <li><a href="/ja/docs/Glossary/Signature/Function">Glossary/Signature/Function</a> ページは関数シグネチャを定義しているページです。</li> + <li><a href="/ja/docs/Glossary/Signature/Email">Glossary/Signature/Email</a> ページはメールの署名を定義しているページです。</li> +</ol> + +<h2 id="How_to_use_the_Glossary_macro" name="How_to_use_the_Glossary_macro">\{{Glossary}} マクロの使い方</h2> + +<p>用語集は、人々が他の文書からそこから移動することなしに定義にアクセスできると、より役立ちます。そこで、いつでも用語集にリンクできる {{TemplateLink("Glossary")}} マクロを使うことをおすすめします。</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">マクロ</th> + <th scope="col">結果</th> + <th scope="col">備考</th> + </tr> + </thead> + <tbody> + <tr> + <td>\{{Glossary("browser")}}</td> + <td>{{Glossary("browser")}}</td> + <td>テキストが定義されている用語に一致する場合は、マクロをそのまま使います。 (大文字小文字を区別しません。)</td> + </tr> + <tr> + <td>\{{Glossary("browser", "Web browser")}}</td> + <td>{{Glossary("browser","Web browser")}}</td> + <td>他のテキストを表示する場合は、第二引数に代わりのテキストを指定してください。</td> + </tr> + <tr> + <td>\{{Glossary("browser", "Web browser", 1)}}</td> + <td>{{Glossary("browser","Web browser",1)}}</td> + <td>オプションの第三引数に <code>1</code> を指定すると、下線付きヒントではなく、通常のリンクとしてリンクを表示します。</td> + </tr> + </tbody> +</table> + +<p>\{{Glossary}} マクロを用いて作成されたリンクは、用語集の項目における要約の段落、または <em>SEO summary</em> (前述の <a href="#Specifying_the_tooltip">ツールチップの設定</a> の節で解説) として定義されたテキストを含むツールチップを表示します。</p> + +<h3 id="Using_the_macro_wisely" name="Using_the_macro_wisely">マクロの賢い使用</h3> + +<p>多くの場合、 MDN のあらゆる場所でこのマクロを用いるのはまったく問題がありません。 \{{Glossary}} マクロを使用するには以下のガイドラインを考慮してください。</p> + +<ul> + <li>ある用語に既に MDN の適切なページへのリンクが設定されている場合は、用語集のリンクに<strong>置き換えないでください</strong>。</li> + <li><strong>記事の1つの節の中では、 \{{Glossary}} マクロは同じ用語に対して1度しか使わないでください。</strong>記事の節は常にタイトルから始まるので、見分けることができます。</li> +</ul> diff --git a/files/ja/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html b/files/ja/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html new file mode 100644 index 0000000000..6f8ae106d1 --- /dev/null +++ b/files/ja/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html @@ -0,0 +1,113 @@ +--- +title: ウェブ学習者に役立つ記事を書く方法 +slug: MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web +tags: + - Guide + - Howto + - Learn + - MDN Meta +translation_of: MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web +--- +<div>{{MDNSidebar}}</div> + +<p>MDN の<a href="/ja/docs/Learn">学習エリア</a>には、ウェブ開発の初心者向けの記事がまとまっています。ほとんどの内容が初心者向けであるため、知識を共有したりウェブへの入門者を手助けするのに良い場所となっています。ウェブ開発初心者でも内容を理解できることが大事なので、それについて特に注意を払っています。</p> + +<p><span class="seoSummary">この記事は<a href="/ja/docs/Learn">学習エリア</a>のページの書き方を説明しています。</span></p> + +<div class="note"> +<p>訳注: この記事は英語の学習エリア記事を新規作成する方法について述べています。日本語の記事は英語記事を翻訳して作成してください。英語ページに該当する記事がない場合は、まず英語記事を作成してください。</p> +</div> + +<h2 id="How_to_write_a_Learning_Area_article" name="How_to_write_a_Learning_Area_article">学習エリアの記事の書き方</h2> + +<p>知識を持って協力を始めるには、大きな緑色のボタンをクリックし、以下の5つのステップに従ってください。アイディアを探しているのであれば、 <a href="https://trello.com/b/LDggrYSV">Trello のチームのボード</a>を参考にしてみてください。</p> + +<div class="align-center"><a class="button ignore-external mega positive" href="/en-US/docs/new?parent=111819">学習エリアの記事を書く</a></div> + +<p>この記事の場所は正しくないかもしれませんが、少なくとも MDN 上にあります。もし正しい場所へ移動するために誰かと連絡を取りたい場合、<a href="/ja/docs/Learn#Contact_us">ご連絡ください</a>。</p> + +<h3 id="Step_1_Write_a_two-liner" name="Step_1_Write_a_two-liner">ステップ 1: 最初の2文を書く</h3> + +<p>記事の1文目には、書こうとしている主題の要約を書く必要があります。2文目には記事に書こうとしている項目をもう少し具体的に書きましょう。例えば下記のようになります。</p> + +<div class="summary"> +<p>{{glossary("HTML")}} ファイルが構造的なコンテンツを持つ一方、もうひとつの主要なウェブ技術である {{Glossary("CSS")}} は、コンテンツを望み通りの外見にします。この記事では、この技術がどのように動いているのかと、基本的な書き方のサンプルを紹介します。</p> +</div> + +<p>上記の例では、CSS がページをスタイルするためのウェブ技術の核であることを簡潔に説明しています。これにより、読者は記事が対象とする範囲を予想するのに十分な情報を得ることができます。</p> + +<p>学習エリアの主な対象者は初心者です。そのため個々の記事は、読者があまりにも多い情報に圧倒されないように、1 つの単刀直入なテーマを対象にすべきです。もし要約が 1行に収まらない場合、1 つの記事に過剰な内容を書こうとしているかもしれません！</p> + +<h3 id="Step_2_Add_a_top_box" name="Step_2_Add_a_top_box">ステップ 2: 上部ボックスを追加する</h3> + +<p><strong>上部ボックス</strong>を追加して、読者が学習プロセスのどこにいるのか理解しやすくしてください。これは<a href="/ja/docs/Learn/Understanding_URLs">「URL とは何か」</a>の上部ボックスの例です。記事を書く際に、この記事をモデルとして使用することができます。</p> + +<table class="learn-box standard-table"> + <tbody> + <tr> + <th scope="row">前提知識:</th> + <td>まず<a href="/ja/docs/Learn/Common_questions/How_does_the_Internet_work">インターネットの仕組み</a>、<a href="/ja/docs/Learn/Common_questions/What_is_a_web_server">ウェブサーバーとは何か</a>、および <a href="/ja/docs/Learn/Common_questions/What_are_hyperlinks">ウェブ上のリンクの背後にある概念</a>を知っておく必要があります。</td> + </tr> + <tr> + <th scope="row">到達目標:</th> + <td>URL の内容とウェブ上での URL の仕組みを学習します。</td> + </tr> + </tbody> +</table> + +<dl> + <dt>前提知識</dt> + <dd>読者が記事を読む際に事前に知っておくべきことを書きます。可能なら、個々の前提知識に、その概念を網羅する他の学習エリア記事のリンクをつけます (本当に初歩の記事で、前提知識を網羅する要求しない場合を除く)。</dd> + <dt>到達目標</dt> + <dd>読者が記事を読んだ後に何を学べるかを簡潔に書きます。記事の冒頭に書く要約とは少し違って、この到達目標の節では、読者が記事を読むことで達成を期待されるものを具体的に示します。</dd> +</dl> + +<div class="note"> +<p><strong>メモ:</strong> この表を作るには、上記の例をコピーして貼り付けるか、 MDN エディターの<a href="/ja/docs/MDN/Contribute/Editor/Tables">表ツール</a>を使用してください。表ツールを使う場合は、 CSS に <code>learn-box</code> クラスを、既定値の <code>standard-table</code> クラスに加えて追加する必要があります。このために、表のプロパティを作成または編集する際に、「高度な設定」パネルに行き<strong>スタイルシートクラス</strong>欄に "<code>standard-table learn-box</code>" を設定してください。</p> +</div> + +<h3 id="Step_3_Write_a_full_description" name="Step_3_Write_a_full_description">ステップ 3: 詳細説明を書く</h3> + +<p>次に、記事で最も強調したい概念についての徹底的な概要となるような、もっと長くて詳細な説明を書きましょう。なぜ読者が時間を費やしてこの記事を読み、その内容を学ぶべきかについての説明を忘れないように！</p> + +<h3 id="Step_4_Dig_deeper" name="Step_4_Dig_deeper">ステップ 4: 深掘りする</h3> + +<p>これまでの部分をやり終えたら、トピックを深掘りしましょう。記事を好きなように構造化して問題ありません (ただし、<a href="/ja/docs/MDN/Contribute/Content">スタイルガイド</a>を気軽に参照ください)。この部分はあなたの記事を輝かせるチャンスです！書こうとしている内容を詳しく説明しましょう。参考情報へのリンクを加え、その技術がどのように動くのかを詳しく説明し、文法や使い方の詳細などを書きましょう。すべてあなた次第です！</p> + +<p>ガイドとして、以下は初心者向けの書き方のコツです。</p> + +<ul> + <li>ひとつのトピックに集中しましょう。もし他のトピックについて書く必要性を感じたならば、前提知識の記述に漏れがあるか、複数の記事として分割する必要があることを示します。</li> + <li>シンプルな言葉を使いましょう。できるだけ専門的な用語は避けましょう。最低限、それらの用語の意味を定義し、適当なものがあれば<a href="/ja/docs/MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary#How_to_use_the_Glossary_macro">用語集へのリンクを貼る</a>ようにしましょう。</li> + <li>理論的な概念を簡単に理解できるように、単刀直入なサンプルを含めましょう。多くの人は実例を通じて最もよく学習できます。学術論文を書くより、初心者にとって読みやすい文章を優先しましょう。</li> + <li>視覚的な資料はより多くの情報を表し、理解の助けになることが多いです。なので画像、図表、動画、表を気軽に利用しましょう。図表やグラフにテキストを含めたいなら、我々の翻訳チームがローカライズに対応できるよう、 {{Glossary("SVG")}} を使用することをお勧めします。</li> +</ul> + +<p><a href="/ja/docs/Learn/JavaScript/Building_blocks/Functions">関数 — 再利用可能なコードブロック</a>の記事には良い説明が含まれています。参考にしてみてください。</p> + +<h3 id="Step_5_Provide_active_learning_material" name="Step_5_Provide_active_learning_material">ステップ 5: 「アクティブラーニング」の教材を提供する</h3> + +<p>記事を解説し読者の理解を助けるために、実習、チュートリアル、達成すべきタスクを提供しましょう。読者は記事で説明されている概念を実際に使ったり、実験したりしてみることで、脳内に情報を強く結びつけることができます。</p> + +<p>用例は<a href="/ja/docs/MDN/Contribute/Structures/Live_samples">ライブデモ</a>のように記事に直接含めることもできますし、<a href="/ja/docs/MDN/Contribute/Editor/Links">リンクする</a>こともできます。もしそういった価値のある教材の作成に興味があるなら、<a href="/ja/docs/MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web">インタラクティブな学習用教材を作成する方法</a>の記事を読んでみてください。</p> + +<p>もしアクティブラーニング教材へのリンクを提供できない (知らない・時間がなくて作れない) 場合は、記事に {{Tag("NeedsActiveLearning")}} タグを追加してください。そうすれば、他の協力者が、アクティブラーニングを必要とする記事を見つけやすくなり、収集するのを手伝うことができます。</p> + +<p><a href="/ja/docs/Learn/CSS/Introduction_to_CSS/Simple_selectors#Active_learning_Selecting_different_elements">実習: 別な要素の選択</a> をインタラクティブな学習用教材として、 <a href="/ja/docs/Learn/JavaScript/Building_blocks/Functions#Active_learning_Playing_with_scope">アクティブラーニング: scopeで遊んでみよう</a> をファイルをダウンロードし、編集するステップを踏みながら学んでいくような、別のスタイルの実習サンプルとして参考にしてください。</p> + +<h3 id="Step_6_Get_the_article_reviewed_and_put_into_the_Learning_Area_navigation_menu" name="Step_6_Get_the_article_reviewed_and_put_into_the_Learning_Area_navigation_menu">ステップ 6: 記事のレビューを受け、ナビゲーションメニューに追加する</h3> + +<p>記事を書き終えたら、我々が確認とレビューを行ない、改善点を提案できるように教えてください。再掲になりますが、連絡を取るための最善の方法は<a href="/ja/docs/Learn#Contact_us">連絡方法</a>の節をご覧ください。</p> + +<p>記事を完了するためのもうひとつのタスクは、その記事を学習エリアのメインナビゲーションメニューに追加することです。このメニューは、編集するのに特別な許可が必要な <a href="/ja/docs/Template:LearnSidebar">LearnSidebar macro</a> によって生成されています。そのため、追加するには我々のチームにご連絡ください。</p> + +<p>メニューは少なくとも、あなたの記事には追加すべきです。 — マクロの \{{LearnSidebar}} をページ最上部の段落に加えましょう。</p> + +<ul> +</ul> + +<h2 id="Suggested_articles" name="Suggested_articles">おすすめの記事</h2> + +<p>何か記事を書きたいけど、何を書けばいいか分からないでしょうか？</p> + +<p>学習エリアのチームは書くべき<a href="https://trello.com/b/LDggrYSV">記事のアイデアを Trello のボード</a>で管理しています。好きなものを選んで取りかかってください！</p> diff --git a/files/ja/mdn/contribute/howto/write_for_seo/index.html b/files/ja/mdn/contribute/howto/write_for_seo/index.html new file mode 100644 index 0000000000..b03503c0bf --- /dev/null +++ b/files/ja/mdn/contribute/howto/write_for_seo/index.html @@ -0,0 +1,71 @@ +--- +title: どのように MDN Web Docs で SEO を考慮するか +slug: MDN/Contribute/Howto/Write_for_SEO +translation_of: MDN/Contribute/Howto/Write_for_SEO +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}{{draft("私たちは最近、SEO を改善するためのいくつかの提案されたテクニックの評価を終了しました。この記事とその貢献者ガイドを更新する過程にあります。")}}</div> + +<p><span class="seoSummary">このガイドでは、ユーザーが必要なものに簡単にアクセスできるように、検索エンジンがコンテンツを簡単に分類して索引付けできるようにするための標準的なプラクティス、推奨事項、およびコンテンツの要件について説明します。</span></p> + +<h2 id="イントロダクション">イントロダクション</h2> + +<p>MDN を執筆する主な目標は、常にオープンな Web 技術について説明し、情報を提供することです。それにより開発者は実現したいことをするため、あるいはコードを完成させるために知っておく必要のある詳細を見つけるために学ぶことができます。彼らが、私たちが書いている資料を探し出せることが重要です。</p> + +<p>Since most readers reach content on MDN through search engines, as writers, we have to keep that in mind while we work. To do that, we are establishing a selection of "SEO guidelines," to help writers and editors on MDN ensure that each page they work on is reasonably well designed, written, and marked up to give search engines the context and clues they need to properly index articles.</p> + +<h2 id="この文書のステータス">この文書のステータス</h2> + +<p>We're currently in the midst of the early stages of what is intended to be a long-term project to improve search engine optimization ({{Glossary("SEO")}}) on MDN. We have recently completed a series of small-scale experiments to test theories and to determine what changes to make to our practices and to the contributor guidelines to help improve our SEO.</p> + +<p>We are still in the process of compiling our notes and updating this article and the rest of the contributor guide to incorporate our findings.</p> + +<h2 id="SEO_チェックリスト">SEO チェックリスト</h2> + +<p>The following is a list of things you should check while writing and reviewing content to help ensure that the page and its neighbors will be indexed properly by search engines.</p> + +<ul> + <li>Make sure the page's contents are <a href="/en-US/docs/MDN/Contribute/Howto/Write_for_SEO#Ensure_pages_aren't_too_similar">different enough from other pages</a> that search engines don't assume they're about the same thing.</li> +</ul> + +<h2 id="Ensure_pages_aren't_too_similar">Ensure pages aren't too similar</h2> + +<p>Each article should be as unique as possible. Articles that look similar to one another textually will wind up being considered to be about roughly the same thing, even if they aren't. For example, if an interface has the properties <code>width</code> and <code>height</code>, it's easy for the text to be surprisingly similar, with just a few words swapped out, and using the same example. This makes it hard for search engines to know which is which, and they wind up sharing page rank, resulting in both being harder to find than they ought to be.</p> + +<p>Understandably, writers confronted with two related properties like <code>width</code> and <code>height</code> (or any other set of functionally related features) are tempted to write the article on <code>width</code>, then copy that article and paste it into the one on <code>height</code>, replacing a few words. Done!</p> + +<p>Unfortunately, the result is two pages that, as far as search engines are concerned, may as well be the same thing.</p> + +<p>It's important, then, to ensure that every page has its own content. Here are some suggestions to help you accomplish that:</p> + +<ul> + <li>Consider use cases where there might be more differences than one would think. For instance, in the case of <code>width</code> and <code>height</code>, perhaps consider ways horizontal space and vertical space are used differently, and provide a discussion about the appropriate concepts. Perhaps you mention the use of width in terms of making room for a sidebar, while using height to handle vertical scrolling or footers or similar. Including information about accessibility issues is a useful and important idea as well.</li> + <li>Use entirely different examples on each page. Examples in these situations are often even more similar than the body text, since the examples may use both (or all) of the similar methods or properties to begin with, thereby requiring no real changes when reused. So throw out the example and write a new one, or at least provide multiple examples, with at least some of them different.</li> + <li>Include descriptions of each example. Both an overview of what the example does as well as coverage of how it works, in an appropriate level of detail given the complexity of the topic and the target audience, should be included.</li> +</ul> + +<p>The easiest way to avoid being overly similar is of course to write each article from scratch if time allows.</p> + +<h2 id="ページが短くなりすぎることは避ける">ページが短くなりすぎることは避ける</h2> + +<p>Articles that are too short (called "thin pages" in SEO parlance) are difficult to catalog accurately. Whenever possible, pages on MDN should avoid being shorter than around 300 words or so. Here are some basic guidelines to help you create pages that have enough content to be properly searchable without resorting to cluttering them up with unnecessary text.</p> + +<ul> + <li>Keep an eye on the convenient word counter located in the top-right corner of the editor's toolbar on MDN. This is not an exact representation of the true word count, since the true word count is based on the rendered page, not the page as you see it in the editor. That means macros that add a lot of words will result in a higher word count, while macros that insert nothing but adjust formatting will result in a lower word count.</li> + <li>Obviously, if the article is a stub, or is missing material, add it. We try to avoid outright "stub" pages on MDN, although they do exist, but there are plenty of pages that are missing large portions of their content.</li> + <li>Generally review the page to ensure that it's structured properly for the <a href="/en-US/docs/MDN/Contribute/Structures/Page_types">type of page</a> it is. Be sure every section that it should have is present and has appropriate content.</li> + <li>Make sure every section is complete and up-to-date, with no information missing. Are all parameters listed and explained? Make sure any exceptions are covered (this is a particularly common place where content is missing).</li> + <li>Be sure everything is fully fleshed-out. It's easy to give a quick explanation of something, but make sure that all the nuances are covered. Are there special cases? Known restrictions that the reader might need to know about?</li> + <li>There should be examples covering all parameters or at least the parameters (or properties, or attributes) that users from the beginner through intermediate range are likely to use, as well as any advanced ones that require extra explanation. Each example should be preceded with an overview of what the example will do, what additional knowledge might be needed to understand it, and so forth. After the example (or interspersed among pieces of the example) should be text explaining how the code works. Don't skimp on the details and the handling of errors in examples; readers <em>will</em> copy and paste your example to use in their own projects, and your code <em>will</em> wind up used on production sites! See <a href="/en-US/docs/MDN/Contribute/Structures/Code_examples">Code examples</a> and our <a href="/en-US/docs/MDN/Contribute/Guidelines/Code_samples">Code sample guidelines</a> for more useful information.</li> + <li>If there are particularly common use cases for the feature being described, talk about them! Instead of assuming the reader will figure out that the method being documented can be used to solve a common development problem, actually add a section about that use case with an example and text explaining how the example works.</li> + <li>Include proper {{htmlattrxref("alt", "img")}} text on all images and diagrams; this text counts, as do captions on tables and other figures.</li> + <li>Do <em>not</em> descend into adding repetitive, unhelpful material or blobs of keywords, in an attempt to improve the page's size and search ranking. This does more harm than good, both to content readability and to our search results.</li> +</ul> + +<h2 id="関連情報">関連情報</h2> + +<ul> + <li><a href="/en-US/docs/MDN/Contribute">Contributing to MDN</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Writing_style_guide">Writing style guide</a></li> +</ul> diff --git a/files/ja/mdn/contribute/howto/write_interface_reference_documentation/index.html b/files/ja/mdn/contribute/howto/write_interface_reference_documentation/index.html new file mode 100644 index 0000000000..5ac438ec39 --- /dev/null +++ b/files/ja/mdn/contribute/howto/write_interface_reference_documentation/index.html @@ -0,0 +1,99 @@ +--- +title: Mozilla インターフェイスのリファレンス文書の書き方 +slug: MDN/Contribute/Howto/Write_interface_reference_documentation +tags: + - Guide + - Howto + - MDN Meta +translation_of: MDN/Contribute/Howto/Write_interface_reference_documentation +--- +<p>{{MDNSidebar}}</p> + +<p>この記事では、 Mozilla のインターフェイスのために、適切にフォーマットされた有用なドキュメントを作成する方法を示します。それぞれのインターフェイスは、記事のタイトルをインターフェイスの名前にして、個別の記事で文書化されなければなりません。</p> + +<div class="blockIndicator warning"> +<p><strong>重要:</strong> 私たちは、Mozilla 内部のインターフェイス (ほとんどが nsI で始まる) を MDN 上で積極的にドキュメント化することはもうありません。これらのドキュメントが将来どこに置かれるべきかの最終決定はまだ検討中ですが、それまでの間、あなたの時間を使って MDN にドキュメントを書くことは一般的にお勧めしません。</p> +</div> + +<h2 id="Learn_by_example" name="Learn_by_example">Learn by example</h2> + +<p>See our <a href="/ja/docs/MDN/Contribute/Howto/Write_interface_reference_documentation/Sample_interface_document" title="Project:Sample_interface_document">sample interface document</a> for a fictional interface that implements all the features of a complete interface reference document. This article can serve as a helpful template when documenting an interface.</p> + +<h2 id="Interface_reference_sections" name="Interface_reference_sections">Interface reference sections</h2> + +<p>Each interface reference article has at least an introduction section (which has no heading). The introduction should provide an overview of what the interface is used for.</p> + +<p>Following the table of contents, use the {{TemplateLink("IFSummary")}} macro to describe the location and status of the interface in the source tree.</p> + +<p>The parameters to the <code>IFSummary</code> macro are:</p> + +<dl> + <dt>Path of the IDL file defining the interface</dt> + <dd>This is used to create a link to the interface's IDL on MXR so the reader can refer to it if they wish.</dd> + <dt>Parent interface</dt> + <dd>This is the name of the interface upon which the interface being documented is based. This will be turned into a link to that interface in the interface reference and displayed.</dd> + <dt>scriptable/not scriptable</dt> + <dd>A string indicating whether the interface is scriptable or not. You must use either "scriptable" or "not scriptable" (these are, however, case insensitive). This will be turned into an appropriate indicator in the box, colored green for scriptable interfaces or red for non-scriptable ones. The indicator will also include a link to an article explaining what this means.</dd> + <dt>Last changed in what Gecko version</dt> + <dd>This is a string indicating the version of Gecko in which the interface was last changed. It should be a string in standard Gecko version format, such as "1.9" or "1.9.2" or even "1.9.1.6".</dd> + <dt>Summary{{Optional_Inline}}</dt> + <dd>A brief textual summary of what the interface does. Should be just a sentence or two. This is only optional for backward compatibility with old interface documents using the now deprecated InterfaceStatus macro (which now calls through to this one). You should <em>always</em> provide this.</dd> + <dt>Version introduced{{Optional_Inline}}</dt> + <dd>If you know the version of Gecko in which the interface was introduced, include that here. This will trigger the inclusion of a version timeline diagram showing the availability of the interface in relation to the history of Gecko.</dd> + <dt>Version deprecated{{Optional_Inline}}</dt> + <dd>If the interface is deprecated, include that here. This will be used when drawing the version timeline diagram.</dd> + <dt>Version obsoleted{{Optional_Inline}}</dt> + <dd>Similarly, if the interface is obsolete and no longer available at all, include the Gecko version in which that took effect.</dd> +</dl> + +<dl> + <dd>{{todo("Should describe the 'Implemented by' section here")}}</dd> +</dl> + +<p>All other sections are usually optional, but may be necessary depending on the interface. The optional sections are:</p> + +<h3 id="Method_overview" name="Method_overview">Method overview</h3> + +<p>The method overview is a table that simply lists all the method signatures for each method provided by the interface. The method's name should be a clickable link to the method description itself. Ideally, the methods should be listed in alphabetical order.</p> + +<p>If a method supports multiple types for a given input parameter, you can list them using the format [type1, type2, ..., typeN].</p> + +<h3 id="Attributes" name="Attributes">Attributes</h3> + +<p>The attributes section consists of a three column table. The first column contains the names of each attribute offered by the interface. The second column indicates the types of each attribute; these types should be links for non-simple types. The third column should describe the attribute, explaining its use and providing any details needed. Please list the attributes in alphabetical order; you can sort the table after the fact by right-clicking in it; there's a "Sort Table" option in the contextual menu.</p> + +<h3 id="Constants" name="Constants">定数</h3> + +<p>Each group of constants should have a sub-section containing a table describing the relevant constants. The table should have three columns: Constant (the names of the constants), Value (their values), and Description (descriptive text explaining the use of the constant).</p> + +<h3 id="Methods" name="Methods">Methods</h3> + +<p>The methods section provides detailed documentation for each method offered by the interface. Within the methods section should be a subsection for each method. Each method's subsection name should include closing parentheses (such as "parseAsync()" in the {{Interface("nsIFeedProcessor")}} interface reference.</p> + +<p>The methods should be listed in the same order in which they appear in the "Method overview" section.</p> + +<p>Each method's subsection should begin with a description of what the method does, followed by the actual method signature itself. Each parameter to the method should be on a separate line for clarity.</p> + +<p>After the method signature should come a "Parameters" subsection. In order to avoid cluttering the table of contents for the page, we use <code><h5>Parameters</h5></code> to define the Parameters subsection's heading.</p> + +<p>The parameters are then listed with descriptions of each parameter using definition list format. If there are no parameters, write the word 'None' under the Parameters heading.</p> + +<p>If the method has a return value, include a "Return value" subsection, using the form <code><h5>Return value</h5></code>. This subsection should simply explain the return value, its type, and if applicable its possible values.</p> + +<p>If the method can throw exceptions, a similar "Exceptions thrown" subsection should be included, containing a definition list style list for each possible exception.</p> + +<h3 id="Remarks" name="Remarks">Remarks</h3> + +<p>Any general comments that apply to the interface as a whole may be placed in the Remarks section.</p> + +<h3 id="See_also" name="See_also">See also</h3> + +<p>If links to other interfaces, or to any other documents, might be helpful to the reader, these should be listed in the "See also" section.</p> + +<h2 id="Categorizing_articles" name="Categorizing_articles">Categorizing articles</h2> + +<p>Each article that documents an interface needs to be added to the Interfaces category by adding the "Interfaces" tag. Likewise, the article should have any other appropriate tags.</p> + +<h2 id="Finding_articles_that_need_help" name="Finding_articles_that_need_help">Finding articles that need help</h2> + +<p>Look through <a href="/ja/docs/tag/Interfaces" title="tag/Interfaces">the interface list</a> and see if any are marked as being in the category <a href="/ja/docs/tag/NeedsMarkupWork" title="tag/NeedsMarkupWork">NeedsMarkupWork</a>. These are interfaces that we know need to be reformatted into our new layout. If you clean one up, remove the line that adds it to that category.</p> diff --git a/files/ja/mdn/contribute/index.html b/files/ja/mdn/contribute/index.html new file mode 100644 index 0000000000..5d5be87fa3 --- /dev/null +++ b/files/ja/mdn/contribute/index.html @@ -0,0 +1,18 @@ +--- +title: MDN への貢献 +slug: MDN/Contribute +tags: + - Guide + - Landing + - MDN Meta +translation_of: MDN/Contribute +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p>ようこそ！このページを訪れることで、あなたは MDN 貢献者への第一歩を踏み出しました。</p> + +<p><span class="seoSummary">これらの解説ドキュメントは、MDN への貢献に関するありとあらゆる内容（スタイルガイド / エディタやツールの使い方など）を網羅しています。ページを編集したり作成したりする前に、<a href="https://www.mozilla.org/about/legal/terms/mozilla/">Mozilla の利用規約</a>をよく読んで（そして守って）ください。</span></p> + +<p>今まで MDN に貢献したことがない方は、<a href="/ja/docs/MDN/Getting_started">MDN を始めよう</a> のガイドをお読みください。あなたが参加するタスクを選ぶ助けになります。</p> + +<p>{{LandingPageListSubPages()}}</p> diff --git a/files/ja/mdn/contribute/localize/index.html b/files/ja/mdn/contribute/localize/index.html new file mode 100644 index 0000000000..ba4410e6e1 --- /dev/null +++ b/files/ja/mdn/contribute/localize/index.html @@ -0,0 +1,59 @@ +--- +title: MDN でのローカライズ +slug: MDN/Contribute/Localize +tags: + - Landing + - Localization + - MDN Meta + - l10n +translation_of: MDN/Contribute/Localize +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p>MDN は世界中の人々から、Firefox そのものと同様に、ウェブテクノロジーのリファレンスおよびガイドとして、使われています。ローカライズコミュニティは Mozilla プロジェクトの中で重要な役割を果たしています。コミュニティによる文書の翻訳および各国言語への対応が、世界各地の人々がオープンなウェブを開発する上で役に立っています。ローカライズについてもっとよく知りたい場合や、新しい言語のローカライズを開始したい場合は、ここがスタート地点です。</p> + +<h2 id="Types_of_localization_on_MDN" name="Types_of_localization_on_MDN">ローカライズの種類</h2> + +<p>MDN でのローカライズは、必要とするシステムや権限によって 3 つに分けることができます。</p> + +<dl> + <dt>MDN サイトのユーザーインターフェイス</dt> + <dd>各々の MDN 記事で表示され、記事本文の場所を示したり、ナビゲーション機能やユーザーコントロールで使われる文字列です。これらの文字列は <a href="https://pontoon.mozilla.org/project">MDN プロジェクト</a> にある Mozilla の <a href="https://developer.mozilla.org/ja/docs/Mozilla/Localization/Localizing_with_Pontoon">Pontoon</a> システムで翻訳することができます。もしお使いの言語が MDN になければ、Pontoon の管理者が有効化する必要があります。<a href="/ja/docs/MDN/Contribute/Localize/Starting_a_localization">MDN のローカライゼーションを開始する</a> を参照してください。</dd> + <dt>MDN 記事</dt> + <dd>リファレンス、ガイド、チュートリアルといった MDN 記事の本文です。これらの記事は <a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Localize/Translating_pages">MDN に組み込まれた翻訳機能</a> を使って翻訳します。翻訳先の言語一覧にお使いの言語がない場合、<a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Localize/Starting_a_localization">MDN のローカライゼーションを開始する</a> を参照してください。</dd> +</dl> + +<dl> + <dt>マクロ文字列</dt> + <dd>これらの文字列は<a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Structures/Macros">マクロテンプレート</a> によって出力され、ナビゲーションやメッセージ、文章構造を構築します。テンプレートの編集は広い範囲に破壊的な影響を及ぼすことが考えられるため、編集には <a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Template_editing">特別なアクセス権</a> が必要です。この権限を持っていない場合は、あなたが翻訳した文字列を権限を持った人に伝え、適用を依頼してください。</dd> +</dl> + +<p>以下のページでは、MDN 上の翻訳についてより詳しく説明しています:</p> + +<p>{{LandingPageListSubpages}}</p> + +<h2 id="Localization_communities_on_MDN" name="Localization_communities_on_MDN">MDN 上の翻訳コミュニティ</h2> + +<p>MDN の翻訳活動は、個人が独立しても (大半の Mozilla 翻訳コミュニティがしているでしょう)、グループで一緒にでも、どちらでも活動できます。MDN の翻訳プロジェクトは、 <strong>翻訳ドライバー</strong>によってリードされています。</p> + +<ul> + <li><a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Localize/Localization_projects">Localization projects</a></li> + <li><a href="https://developer.mozilla.org/ja/docs/MDN/Community/Roles/Localization_driver_role">Localization driver role</a></li> +</ul> + +<h2 id="Localization_tools" name="Localization_tools">ローカライズのためのツール</h2> + +<p>ローカライズの作業で使われる、便利なツールをいくつか紹介します:</p> + +<dl> + <dt><a href="/ja/docs/Mozilla/Localization/Localizing_with_Pontoon" title="/ja/docs/Mozilla/Localization/Localizing_with_Verbatim">Pontoon</a></dt> + <dd>文字列を翻訳するためのもので、Mozilla の複数のプロジェクトにまたがって使われます。MDN のユーザーインターフェイス (そして Firefox のユーザーインターフェイス) も対象です。</dd> + <dt><a href="http://transvision.mozfr.org/" title="http://transvision.mozfr.org/">Transvision</a></dt> + <dd>French Mozilla community によって提供されるユーテリティで、ある英語文字列の存在を Mozilla のプログラムコード全体から検索し、また目的の言語への様々な翻訳を見つけるのに使用できます。単語、フレーズの適切な訳 (定訳) を探すのに便利です。</dd> +</dl> + +<h2 id="See_also" name="See_also">関連項目</h2> + +<ul> + <li><a href="/ja/docs/Mozilla/Localization" title="/ja/docs/Mozilla/Localization">Mozilla でのローカライゼイション</a></li> +</ul> diff --git a/files/ja/mdn/contribute/localize/localization_projects/index.html b/files/ja/mdn/contribute/localize/localization_projects/index.html new file mode 100644 index 0000000000..1a4bf5e040 --- /dev/null +++ b/files/ja/mdn/contribute/localize/localization_projects/index.html @@ -0,0 +1,618 @@ +--- +title: 各言語のローカライズプロジェクト +slug: MDN/Contribute/Localize/Localization_projects +tags: + - MDN Meta + - Reference + - l10n + - コミュニティ + - ローカライゼーション +translation_of: MDN/Contribute/Localize/Localization_projects +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">MDN におけるすべてのローカライゼーションおよび翻訳作業は私たちの素晴らしいコミュニティボランティアに支えられています。この記事ではすべての言語のプロジェクトを列挙し、リーダー、貢献者、その他詳細を紹介します。</span></p> + +<p>飛び込んで翻訳を始めたい場合は、 <a href="/ja/docs/MDN/Contribute/Localize/Translating_pages">MDN ページの翻訳</a>を参照してください。</p> + +<div class="note"> +<p><strong>注:</strong> 特定のロケールにおいて、他の貢献者から連絡を受け付けることに興味がある場合は、気軽にあなたの名前をこのページに追加してください。 MDN プロフィールがあなたへの Twitter やその他のソーシャルメディアのような連絡手段として表示されることにご注意ください。過去12ヶ月に MDN への貢献がない人は、このページの名前が削除されます。</p> +</div> + +<details><summary> +<h2 id="ar_العربية_Arabic">ar: العربية [Arabic]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/ar/dashboards/revisions?locale=ar">最新の変更</a></li> + <li><a href="/ar/docs/MDN/Doc_status/Overview">ステータス概要</a></li> + <li>議論</li> + <li><a href="https://pontoon.mozilla.org/ar/contributors/">現在の貢献者</a></li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:ar">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/ar/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="bg_Български_Bulgarian">bg: Български [Bulgarian]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/bg/dashboards/revisions?locale=bg">最新の変更</a></li> + <li>ステータス概要</li> + <li><a href="https://pontoon.mozilla.org/bg/contributors/">現在の貢献者</a></li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:bg">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/bg/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="bm_Bamanankan_Bambara">bm: Bamanankan [Bambara]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/bm/dashboards/revisions?locale=bm">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:bm">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li>MDN インターフェイスの翻訳</li> +</ul> +</details> + +<details open><summary> +<h2 id="bn_বাংলা_বাংলাদেশ_Bengali">bn: বাংলা (বাংলাদেশ) [Bengali]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/bn-BD/dashboards/revisions?locale=bn-BD">最新の変更</a></li> + <li><a href="https://developer.mozilla.org/bn-BD/docs/MDN/Doc_status/Overview">ステータス概要</a></li> + <li>議論</li> + <li>現在の貢献者:</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:bn-BD">Mozilla のローカライズプロジェクト</a></li> + <li><a href="https://developer.mozilla.org/bn-BD/docs/Project:MDN/%E0%A6%85%E0%A6%AC%E0%A6%A6%E0%A6%BE%E0%A6%A8/mozillabd-l10n-team">MDN チームのページ</a></li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/bn_BD/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="ca_Català_Catalan">ca: Català [Catalan]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/ca/dashboards/revisions?locale=ca">最新の変更</a></li> + <li>ステータス概要</li> + <li>現在の貢献者</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:ca">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/ca/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="de_Deutsch_German">de: Deutsch [German]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/de/dashboards/revisions?locale=de">最新の変更</a></li> + <li><a href="https://developer.mozilla.org/de/docs/MDN/Doc_status/Overview">ステータス概要</a></li> + <li>現在の貢献者: {{userlink("fscholz")}}{{ref('*')}}, {{userlink("SebastianZ","Sebastian Zartner")}}, {{userlink("Shidigital")}}</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:de">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/de/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="el_Ελληνικά_Greek">el: Ελληνικά [Greek]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/el/dashboards/revisions?locale=el">最新の変更</a></li> + <li>ステータス概要</li> + <li>現在の貢献者</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:el">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/el/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="es_Español_Spanish">es: Español [Spanish]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/es/dashboards/revisions?locale=es">最新の変更</a></li> + <li><a href="https://developer.mozilla.org/es/docs/MDN/Doc_status/Overview">ステータス概要</a></li> + <li>現在の貢献者: {{userlink("maedca","Manuel Camacho")}}{{ref('*')}}, {{userlink("StripTM")}}, {{userlink("Jorge.villalobos")}}</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:es">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li><a href="https://developer.mozilla.org/es/docs/Project%3AGu%C3%ADa_de_estilo">規約</a></li> + <li><a href="https://pontoon.mozilla.org/es/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="fa_فارسی_Persian">fa: فارسی [Persian]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/fa/dashboards/revisions?locale=fa">最新の変更</a></li> + <li><a href="https://developer.mozilla.org/fa/docs/MDN/Doc_status/Overview">ステータス概要</a></li> + <li>現在の貢献者:</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:fa">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/fa/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="fi_suomi_Finnish">fi: suomi [Finnish]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/fi/dashboards/revisions?locale=fi">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:fi">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li>MDN インターフェイスの翻訳</li> +</ul> +</details> + +<details open><summary> +<h2 id="fr_Français_French">fr: Français [French]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/fr/dashboards/revisions?locale=fr">最新の変更 / Dernières éditions</a></li> + <li><a href="https://developer.mozilla.org/fr/docs/MDN/Doc_status/Overview">ステータス概要 / Statut de la localisation</a></li> + <li><a href="http://mozfr.org/mailman/listinfo/moz-fr/">議論 (moz-fr mailiing list)</a></li> + <li>現在の貢献者: {{userlink("Jeremie","Jeremie Patonnier")}}{{ref('*')}}, {{userlink("SphinxKnight", "Sphinx")}}{{ref('*')}}, {{userlink("BenoitL","Benoit Leseul")}}, {{userlink("tregagnon","Thierry Régagnon (tregagnon)")}}, {{userlink("Goofy")}}, {{userlink("Delapouite")}}</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:fr">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/fr/mdn/">MDN インターフェイスの翻訳 / Traduire l'interface</a></li> +</ul> +</details> + +<details><summary> +<h2 id="he_עברית_Hebrew">he: עברית [Hebrew]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/he/dashboards/revisions?locale=he">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者:</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:he">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li>MDN インターフェイスの翻訳</li> +</ul> +</details> + +<details><summary> +<h2 id="hi-IN_हिन्दी_भारत_Hindi">hi-IN: हिन्दी (भारत) [Hindi]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/hi-IN/dashboards/revisions?locale=hi-IN">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者:</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:hi-IN">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li>MDN インターフェイスの翻訳</li> +</ul> +</details> + +<details><summary> +<h2 id="hu_magyar_Hungarian">hu: magyar [Hungarian]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/hu/dashboards/revisions?locale=hu">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:hu">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/hu/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="id_Bahasa_Indonesia_Indonesian">id: Bahasa Indonesia [Indonesian]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/id/dashboards/revisions?locale=id">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者:</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:id">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/id/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details open><summary> +<h2 id="it_Italiano_Italian">it: Italiano [Italian]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/ig/dashboards/revisions?locale=it">最新の変更</a></li> + <li><a href="https://developer.mozilla.org/it/MDN/Doc_status/Overview">ステータス概要</a></li> + <li>議論: <a href="https://translate.googleusercontent.com/translate_c?depth=1&hl=en&rurl=translate.google.com&sl=auto&tl=en&u=http://forum.mozillaitalia.org/&usg=ALkJrhhzVkkb--9tarnQhoYRv6OonR79Tg">Mozilla Italia</a></li> + <li>現在の貢献者:</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:it">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li><a href="/it/MDN/Contribute/Localize/GuidaItaliano">支援方法</a></li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/it/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="ja_日本語_Japanese">ja: 日本語 [Japanese]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/ja/dashboards/revisions?locale=ja">最新の変更</a></li> + <li><a href="https://developer.mozilla.org/ja/docs/MDN/Doc_status/Overview">ステータス概要</a></li> + <li>議論: <a href="https://groups.google.com/forum/#!forum/mozilla-translations-ja">Mozilla.translations.ja</a></li> + <li>現在の貢献者: {{userlink("myakura","myakura (Masataka Yakura)")}}, {{userlink("yyss")}}, {{userlink("Marsf","Marsf (Masahiko Imanaka)")}}, {{userlink("Masayuki")}}, {{userlink("dynamis","dynamis (Tomoya Asai)")}}, {{userlink("mantaroh")}}, {{userlink("hamasaki")}}, {{userlink("mfuji09")}}</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:ja">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法: We are taking a bit long time in transition from old resources, <a href="https://developer.mozilla.org/ja/docs/Project:%E6%97%A5%E6%9C%AC%E8%AA%9E%E7%89%88">MDC Japan Project</a> (-2009), those include some useful information.</li> + <li><a href="/ja/docs/MDN/Contribute/Content/Writing_style_guide">規約</a></li> + <li><a href="https://pontoon.mozilla.org/ja/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="kab_Taqbaylit_Kabyle">kab: Taqbaylit [Kabyle]</h2> +</summary> + +<ul> + <li><a href="https://l10n.mozilla-community.org/webdashboard/?locale=kab">ステータス概要</a></li> + <li>議論</li> + <li>現在の貢献者</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:kab">Mozilla Kabyle localization project</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li>MDN インターフェイスの翻訳</li> + <li><a href="https://www.mozilla.org/kab/">Mozilla.org Kabyle</a></li> +</ul> +</details> + +<details><summary> +<h2 id="ko_한국어_Korean">ko: 한국어 [Korean]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/ko/dashboards/revisions?locale=ko">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論: <a href="https://groups.google.com/forum/#!forum/mdckorea">mdckorea</a></li> + <li>現在の貢献者:</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:ko">Mozilla のローカライズプロジェクト</a></li> + <li><a href="/ko/docs/Project:Korean_Contributors">MDN チームのページ</a></li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/ko/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="ms_Melayu_Malay">ms: Melayu [Malay]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/ms/dashboards/revisions?locale=ms">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:ms">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li>MDN インターフェイスの翻訳</li> +</ul> +</details> + +<details><summary> +<h2 id="my_မြန်မာဘာသာ_Myanmar">my: မြန်မာဘာသာ [Myanmar]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/my/dashboards/revisions?locale=my">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者:</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:my">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li>MDN インターフェイスの翻訳</li> +</ul> +</details> + +<details><summary> +<h2 id="nl_Nederlands_Dutch">nl: Nederlands [Dutch]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/nl/dashboards/revisions?locale=nl">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:nl">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/nl/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="pl_Polski_Polish">pl: Polski [Polish]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/pl/dashboards/revisions?locale=pl">最新の変更</a></li> + <li><a href="https://developer.mozilla.org/pl/docs/MDN/Doc_status/Overview">ステータス概要</a></li> + <li>議論</li> + <li>現在の貢献者:</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:pl">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/pl/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="pt-BR_Português_do_Brasil_Portuguese_Brazil">pt-BR: Português (do Brasil) [Portuguese, Brazil]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/pt-BR/dashboards/revisions?locale=pt-BR">最新の変更</a></li> + <li><a href="https://developer.mozilla.org/pt-BR/docs/MDN/Doc_status/Overview">ステータス概要</a></li> + <li>議論</li> + <li>現在の貢献者:</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:pt-BR">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li><a href="http://mzl.la/Odmaq9">Como ajudar a MDN</a></li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/pt-BR/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="pt-PT_Português_Europeu_Portuguese_Portugal">pt-PT: Português (Europeu) [Portuguese, Portugal]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/pt-PT/dashboards/revisions?locale=pt-PT">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:pt-PT">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/pt-PT/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details open><summary> +<h2 id="ru_Русский_Russian">ru: Русский [Russian]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/ru/dashboards/revisions?locale=ru">最新の変更</a></li> + <li><a href="https://developer.mozilla.org/ru/docs/MDN/Doc_status/Overview">ステータス概要</a></li> + <li>議論</li> + <li>現在の貢献者: {{userlink("bychekRU","Victor Bychek")}}</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:ru">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li><a href="/ru/docs/Project%3AWriter's_guide">規約</a></li> + <li><a href="https://pontoon.mozilla.org/ru/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="sv-SE_Svenska_Swedish">sv-SE: Svenska [Swedish]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/sv-SE/dashboards/revisions?locale=sv-SE">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:sv-SE">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/sv-SE/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="th_ไทย_Thai">th: ไทย [Thai]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/th/dashboards/revisions?locale=th">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:th">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/th/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="tr_Türkçe_Turkish">tr: Türkçe [Turkish]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/tr/dashboards/revisions?locale=tr">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:tr">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li>MDN インターフェイスの翻訳</li> +</ul> +</details> + +<details open><summary> +<h2 id="uk_Українська_Ukrainian">uk: Українська [Ukrainian]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/uk/dashboards/revisions?locale=uk">最新の変更</a></li> + <li>ステータス概要</li> + <li>議論</li> + <li>現在の貢献者: {{userlink("asmforce", "asmforce (Крутько Віталій)")}}</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:uk">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/uk/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details open><summary> +<h2 id="vi_Tiếng_Việt_Vietnamese">vi: Tiếng Việt [Vietnamese]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/vi/dashboards/revisions?locale=vi">最新の変更</a></li> + <li><a href="/vi/docs/MDN/Doc_status/Overview">ステータス概要</a></li> + <li>議論: <a href="https://gitter.im/mdn-vi-l10n">group chat on Gitter</a></li> + <li>現在の貢献者: see <a href="https://mdn-top-vi-contributors.netlify.com/">top vi contributors minisite</a> (created by {{userlink("trongthanh")}})</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:vi">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li><a href="https://developer.mozilla.org/vi/docs/MDN/Contribute/Localize/dich_trang">支援方法</a></li> + <li>規約</li> + <li><a href="https://pontoon.mozilla.org/vi/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details><summary> +<h2 id="zh-CN_中文_简体_Chinese_simplified">zh-CN: 中文 (简体) [Chinese, simplified]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/zh-CN/dashboards/revisions?locale=zh-CN">最新の変更</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Doc_status/Overview">ステータス概要</a></li> + <li>議論: {{page("/zh-CN/docs/MDN/Contribute/Localize/Localization_projects", "notes")}}</li> + <li>現在の貢献者: {{page("/zh-CN/docs/MDN/Contribute/Localize/Localization_projects", "leader")}}{{ref('*')}}; see the team page for other contributors.</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:zh-CN">Mozilla のローカライズプロジェクト</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Localize/Localization_projects">MDN チームのページ</a></li> + <li>支援方法</li> + <li><a href="/zh-CN/docs/MDN/Contribute/Content/Style_guide">規約</a></li> + <li><a href="https://pontoon.mozilla.org/zh-CN/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<details open><summary> +<h2 id="zh-TW_中文_繁體_Chinese_traditional">zh-TW: 中文 (繁體) [Chinese, traditional]</h2> +</summary> + +<ul> + <li><a href="https://developer.mozilla.org/zh-TW/dashboards/revisions?locale=zh-TW">最新の変更</a></li> + <li><a href="https://developer.mozilla.org/zh-TW/docs/MDN/Doc_status/Overview">ステータス概要</a></li> + <li>議論: 我們需要更多貢獻者，請到 <a href="https://groups.google.com/group/moztw-general">MozTW-general 郵件群組</a>與我們聯繫！</li> + <li>現在の貢献者: {{userlink("irvinfly")}}{{ref('*')}}, {{userlink("BobChao")}}, {{userlink("petercpg")}}</li> + <li><a href="https://wiki.mozilla.org/L10n:Teams:zh-TW">Mozilla のローカライズプロジェクト</a></li> + <li>MDN チームのページ</li> + <li>支援方法</li> + <li><a href="/zh-TW/docs/MDN/Contribute/Content/Style_guide">規約</a></li> + <li><a href="https://pontoon.mozilla.org/zh-TW/mdn/">MDN インターフェイスの翻訳</a></li> +</ul> +</details> + +<p><a href="/en-US/docs/MDN/Community/Roles/Localization_driver_role">翻訳リーダー</a>は {{ref('*')}} で示されています。これは MDN のローカライズコミュニティをリードし、特定のロケールやトピックのコンテンツのローカライズ作業を案内します。</p> + +<h2 id="Other_locales" name="Other_locales">他のロケール</h2> + +<p>以下のロケールは MDN 上に作られていませんが、作成に関心がある地域です。新しいロケールを作成したい場合は、<a href="/en-US/docs/MDN/Contribute/Localize/Starting_a_localization">新しく MDN のローカライズを始める</a>を参照してください。</p> + +<h3 id="gu_ગુજરાતી_Gujarati">gu: ગુજરાતી [Gujarati]</h3> + +<ul> + <li><a href="https://wiki.mozilla.org/L10n:Teams:gu-IN">Mozilla のローカライズプロジェクト</a></li> + <li>関心を持っているユーザー: {{userlink("prafull_satasiya")}}</li> +</ul> + +<h3 id="lo_ພາສາລາວ_Lao">lo: ພາສາລາວ [Lao]</h3> + +<ul> + <li><a href="https://wiki.mozilla.org/L10n:Teams:lo">Mozilla のローカライズプロジェクト</a></li> + <li>関心を持っているユーザー: {{userlink("rcampbelllaos","Robert M Campbell")}}</li> +</ul> + +<h3 id="si_සිංහල_Sinhalese">si: <strong>සිංහල [Sinhalese]</strong></h3> + +<ul> + <li><a href="https://wiki.mozilla.org/L10n:Teams:si">Mozilla のローカライズプロジェクト</a></li> + <li>関心を持っているユーザー: {{userlink("pkavinda")}}</li> +</ul> + +<h3 id="ur_اردو_Urdu">ur: اردو [Urdu]</h3> + +<ul> + <li><a href="https://wiki.mozilla.org/L10n:Teams:ur">Mozilla のローカライズプロジェクト</a></li> + <li>関心を持っているユーザー:</li> +</ul> + +<section id="Quick_Links"> +<ul> + <li><a href="/ja/docs/MDN/Contribute/Localize/Translating_pages">MDN のページの翻訳</a></li> + <li><a href="/ja/docs/MDN/Contribute/Localize/Starting_a_localization">新しく MDN のローカライズを始める</a></li> + <li><a href="/ja/docs/Mozilla/Localization">Mozilla のソフトウェアやウェブサイトのローカライズ</a></li> + <li><a href="/ja/docs/Mozilla/Localization/Localizing_with_Pontoon">Pontoon でのローカライズ</a></li> +</ul> +</section> diff --git a/files/ja/mdn/contribute/localize/starting_a_localization/index.html b/files/ja/mdn/contribute/localize/starting_a_localization/index.html new file mode 100644 index 0000000000..a09fa846de --- /dev/null +++ b/files/ja/mdn/contribute/localize/starting_a_localization/index.html @@ -0,0 +1,106 @@ +--- +title: MDN のローカライゼーションを開始する +slug: MDN/Contribute/Localize/Starting_a_localization +tags: + - Documentation + - Guide + - Localization + - MDN Meta + - l10n +translation_of: MDN/Contribute/Localize/Starting_a_localization +--- +<div>{{MDNSidebar}}</div> + +<p>MDN のコンテンツのローカライズは、単に英語が読める人だけでなく、より多くのウェブ開発者や潜在的なウェブ開発者に MDN のリーチを広げるのに役立ちます。したがって、ローカライズは MDN の使命を達成するために不可欠な要素です。</p> + +<p>MDN での新しいローカライズのリクエストは、その場に応じて評価され、いくつかの最低限の要件を満たす必要があります。考慮されるその他の要素としては、<em>その言語を話す人の数</em>や、<em>英語を読む人の割合</em>などがあります。この数については厳密なルールはありませんが、MDN のリーチを大幅に広げているロケールが優先されます。英語を読まない話者の人口が多い言語は、その多くが英語を読む話者の人口が少ない言語よりも優先されます。</p> + +<h2 id="Minimum_criteria" name="Minimum_criteria">最低条件</h2> + +<p>MDN にロケールを追加するための最低基準は以下の通りです。</p> + +<ul> + <li>MDN の外に、そのロケールに対応した Mozilla ローカリゼーションコミュニティが存在する。</li> + <li>そのロケールのローカライズリーダーが指定されており、そのロケールのローカライズ作業をリードすることを約束している。</li> + <li>MDN 用のロケールが Pontoon に追加され、コミュニティが文字列の 50% 以上を翻訳している。</li> + <li>コミュニティの中心的なメンバーが、ローカリゼーションリーダーを指導することに同意している (上記の追加要素やチームの作業量などを考慮して)。</li> +</ul> + +<h2 id="Process_to_start_a_localization" name="Process_to_start_a_localization">ローカライズを始めるプロセス</h2> + +<p>MDN をあなたの言語に翻訳するローカライズプロジェクトを開始したい場合、ここに起動して走りだすまで、従う手順があります。</p> + +<ol> + <li>Be a member of an active <a href="https://wiki.mozilla.org/L10n:Teams">Mozilla localization community</a>. If the Mozilla community for your locale is not active, work on building up that community before expanding it to include MDN.</li> + <li>Reach out to the MDN community to share your intention of starting a new MDN localization. (例えば、join the <a href="https://discourse.mozilla-community.org/c/mdn">MDN discussion forum</a> and the <a href="https://chat.mozilla.org/#/room/#mdn:mozilla.org">MDN Web Docs chat room</a> in <a href="https://wiki.mozilla.org/Matrix">Matrix</a>.) Core members of the MDN community, including <a href="mailto:mdn-admins@mozilla.org?subject=Starting%20a%20localization%20project">MDN staff</a>, can advise you on whether your proposed locale seems like a good fit for MDN.</li> + <li>Add a section for your language to the list of <a href="/ja/docs/MDN/Contribute/Localize/Localization_projects">localization projects</a>, and include anyone else who is planning to work on it.</li> + <li><a href="https://github.com/mdn/kuma/issues/new/choose">Submit a GitHub issue</a> to request activation of your locale for MDN in Pontoon. A Pontoon administrator must do this activation.</li> + <li>Work with your localization community to translate MDN UI strings in Pontoon. Don’t proceed to the next step until you have at least 50% of the strings translated. Keep communicating with the MDN community about your progress.</li> + <li><a href="https://github.com/mdn/kuma/issues/new/choose">Submit a GitHub issue</a> to request that the locale be added to the list of available locales on MDN. Indicate who will take the role of MDN localization leader, to be a point of contact between the MDN localization group and the rest of the MDN community. Usually, this is the person who submits the bug. In order for your request to be accepted, a member of the MDN community must be willing to mentor the localization leader, so good communication up to this point will pay off if you can show that: + <ol> + <li>Your Mozilla localization community is active, and has the organization and interest need to sustain working on MDN.</li> + <li>Your locale is a good fit for MDN.</li> + <li>As a localization leader, you are easy to work with and responsive to feedback.</li> + </ol> + </li> +</ol> + +<h2 id="Organizing_a_localization_project_MDN_mechanics" name="Organizing_a_localization_project_MDN_mechanics">ローカライゼーションプロジェクトを組織する</h2> + +<p>The basic structure of the page hierarchy in each of the localizations of MDN should be essentially the same. In general, you should try to maintain the same hierarchy of pages as the en-US (English) locale, so that each page in each language corresponds to a similar page in each locale.</p> + +<p>You are welcome to link to external local pages, write your own articles, and translate everything from the English wiki. If you do decide to write your own articles, it would be helpful if you could provide an English translation for the English wiki so it can then get translated into all of the other localized wikis.</p> + +<p>In adding local resources, you should keep a neutral point of view; that is, you shouldn't promote a particular perspective, and should instead simply provide the facts as best as possible (see information about the <a href="https://en.wikipedia.org/wiki/NPOV">NPOV</a> rule on Wikipedia). You should not link to commercial sites (like paid courses, web design companies, etc.). You should promote open standards and cross-browser compatibility over closed or proprietary methods wherever possible.</p> + +<div class="note"> +<p>Team leads are encouraged to monitor their locale's content for spam and other inappropriate materials and take steps to get them removed or corrected.</p> +</div> + +<p>There are lots of great tips from various existing translation teams; you should feel free to adopt any of these ideas you choose. In addition, please feel free to add your own suggestions as well. See <a href="/profiles/traducción">this template</a> in the Spanish wiki for an example.</p> + +<ul> + <li>Use a macro to identify articles that are in the process of being translated. The macro should provide an information box that includes a link to the original version of the article. You may also wish to use page tags to indicate pages that need more translation work. This helps track articles that are in the process of being translated.</li> + <li>Use a macro to include articles that need to be translated in article lists with a flag or marker next to them indicating that the article hasn't been translated yet. This is a way to advertise important articles in need of translation. See <a href="/profiles/tradúceme">this template</a> in the Spanish version of MDN for an example.</li> + <li>Use the "Needs technical review" and "Needs editorial review" flags, to mark articles that have been translated but should be double-checked for technical and grammatical accuracy.</li> + <li>Use the "junk" tag to mark pages that need to be deleted. Since only admins have access to delete articles, this provides a way to mark that an article is obsolete until the admins get the page deleted.</li> + <li>Be sure to include translations of these MDN "how to" pages, and include additional pages as necessary to explain your localization team's policies and practices.</li> +</ul> + +<p>To find help with your project, be sure to ask around on the <a href="https://discourse.mozilla-community.org/c/mdn">MDN discussion forum</a>, the <a href="irc://irc.mozilla.org/mdn">#mdn</a> IRC channel, and other MDN-related discussion areas. See "<a href="/ja/docs/Project:MDN/Contributing/Join_the_community">Join the MDN community</a>" for pointers to community discussion channels that will help you find others interested in joining your localization team.</p> + +<p>You may also be able to find others interested in helping you by attending local Web development events, at your local hacker space, and the like. Be creative!</p> + +<h2 id="Organizing_a_localization_community" name="Organizing_a_localization_community">ローカライズコミュニティを組織する</h2> + +<h3 id="Work_with_any_existing_Mozilla_localization_communities" name="Work_with_any_existing_Mozilla_localization_communities">既存の Mozilla ローカライズコミュニティとの作業</h3> + +<p>Experience has shown that the most active and successful localization communities on MDN are extensions of existing Mozilla localization communities. If you’re interested in starting a localization on MDN, and you’re not already in contact with the Mozilla community for your locale, <a href="https://wiki.mozilla.org/L10n:Teams">look them up</a> and get in touch. You’ll find some great folks with experience to share about Mozilla and localization.</p> + +<h3 id="Get_lots_of_people_involved" name="Get_lots_of_people_involved">多くの人を巻き込む</h3> + +<p>We’ve also seen that the more people are involved in a localization effort, the more likely it is to be self-sustaining. People come and go in a localization effort (like most things in life). The more people are involved, the more likely it is for the group to sustain through those changes. Efforts that are started by one person or a small group usually do not remain active longer than the initial members. Therefore, a big part of starting a localization effort is recruiting enough people so that the group keeps going even when some people drop out, as they inevitably do.</p> + +<h3 id="Meet_regularly_in_person_or_online" name="Meet_regularly_in_person_or_online">個人的に、またはオンラインで定期的に会議をする</h3> + +<p>Meeting regularly with other localizers can be a great way to build a sense of group cohesion, so that people want to keep participating. Meeting face-to-face is great if everyone is located closely together enough to be able to do that. You can meet virtually online if your group is spread too far apart to meet in person. Meeting on a regular schedule, such as once a month, is also important, so that members of the group can plan to attend. Some localizers may contribute only during a meet-up, and not at other times.</p> + +<h2 id="What_to_translate_first" name="What_to_translate_first">最初に翻訳すること</h2> + +<p>MDN has thousands of articles in many different topic areas. Maybe you are passionate about a particular topic — by all means, start there! But if you're looking for starting points, here are some suggestions:</p> + +<ul> + <li><a href="/ja/docs/tag/l10n%3Apriority">"l10n:priority" でタグ付けされたページ</a></li> + <li><a href="/ja/Learn">学習エリア</a>のガイド</li> + <li>The <a href="/ja/docs/Web/JavaScript/Guide">JavaScript ガイド</a></li> + <li>主要な要素の<a href="/ja/docs/Web/HTML/Reference">HTML リファレンス</a>ページ</li> + <li><a href="/ja/docs/Web/CSS">CSS ドキュメント</a></li> +</ul> + +<p>For some locales, localizers consider guides and tutorials to be a higher priority than reference pages. Web developers can often figure out code syntax from the English version of a page, even if they don't know much English. But learning new concepts is much more comfortable in one's native language. So, it may be important to translate tutorials first.</p> + +<h2 id="Policy" name="Policy">ポリシー</h2> + +<p>MDN 用に作成・翻訳されたすべてのものは、<a href="/ja/docs/Project:Copyrights">コピーライトとライセンスポリシー</a>に従うべきです。</p> + +<p>あらゆる問題 —技術的な、ポリシー、その他のもの— に出くわしたら、<a href="mailto:mdn-admins@mozilla.org?subject=Localization%20question" title="mailto:mdn-admins@mozilla.org?subject=Localization%20question">MDN 管理チーム</a>までご連絡ください。</p> diff --git a/files/ja/mdn/contribute/localize/top_100_articles/index.html b/files/ja/mdn/contribute/localize/top_100_articles/index.html new file mode 100644 index 0000000000..e75f4a520c --- /dev/null +++ b/files/ja/mdn/contribute/localize/top_100_articles/index.html @@ -0,0 +1,506 @@ +--- +title: 上位100記事 +slug: MDN/Contribute/Localize/Top_100_articles +tags: + - Localization + - MDN + - MDN Meta + - l10n +translation_of: MDN/Contribute/Localize/Top_100_articles +--- +<p>以下に、 MDN 上でトラフィック量の上位 100 記事のリストを示します。ローカライズを行う上で、ウェブ開発者が興味を持っていると思われるトピックをカバーしたい場合は、これらのページを翻訳するのも良いでしょう。</p> + +<p class="note">訳注: このページは英語版ページのトラフィック量を表していますが、ローカライズ状況を参考にするため、リンク先を日本語ページにしています。</p> + +<h2 id="Current_top_articles" name="Current_top_articles">現在の上位の記事</h2> + +<p><strong>最終更新:</strong> 2019-11-27</p> + +<p>前回の一覧に含まれていなかった項目は太字で、 "new" とタグ付けしています。</p> + +<table class="standard-table"> + <tbody> + <tr> + <td>/en-US (MDN のホームページで、 <a href="https://pontoon.mozilla.org/projects/mdn/">Pontoon</a> からローカライズする必要がある)</td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript">/ja/docs/Web/JavaScript</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/map">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/map</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/filter">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/filter</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/API/Fetch_API/Using_Fetch">/ja/docs/Web/API/Fetch_API/Using_Fetch</a>></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTTP/CORS">/ja/docs/Web/HTTP/CORS</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/find">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/find</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise">/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Date">/ja/docs/Web/JavaScript/Reference/Global_Objects/Date</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/splice">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/splice</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Guide/Regular_Expressions">/ja/docs/Web/JavaScript/Guide/Regular_Expressions</a></td> + </tr> + <tr> + <td>><strong><a href="/ja/docs/Web/HTTP/Status">/ja/docs/Web/HTTP/Status</a> NEW!</strong></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/slice">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/slice</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Object/keys">/ja/docs/Web/JavaScript/Reference/Global_Objects/Object/keys</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Map">/ja/docs/Web/JavaScript/Reference/Global_Objects/Map</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTML/Element/input">/ja/docs/Web/HTML/Element/input</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/API/Fetch_API">/ja/docs/Web/API/Fetch_API</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Object/assign">/ja/docs/Web/JavaScript/Reference/Global_Objects/Object/assign</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/sort">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/sort</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web">/ja/docs/Web</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/includes">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/includes</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Operators/typeof">/ja/docs/Web/JavaScript/Reference/Operators/typeof</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS">/ja/docs/Web/CSS</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Template_literals">/ja/docs/Web/JavaScript/Reference/Template_literals</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/API/EventTarget/addEventListener">/ja/docs/Web/API/EventTarget/addEventListener</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/API">/ja/docs/Web/API</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Classes">/ja/docs/Web/JavaScript/Reference/Classes</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTML">/ja/docs/Web/HTML</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Learn/Getting_started_with_the_web/JavaScript_basics">/ja/docs/Learn/Getting_started_with_the_web/JavaScript_basics</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify">/ja/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTML/Element">/ja/docs/Web/HTML/Element</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Functions/Arrow_functions">/ja/docs/Web/JavaScript/Reference/Functions/Arrow_functions</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Operators/Conditional_Operator">/ja/docs/Web/JavaScript/Reference/Operators/Conditional_Operator</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Statements/async_function">/ja/docs/Web/JavaScript/Reference/Statements/async_function</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/String/replace">/ja/docs/Web/JavaScript/Reference/Global_Objects/String/replace</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Set">/ja/docs/Web/JavaScript/Reference/Global_Objects/Set</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS/CSS_Flexible_Box_Layout/Aligning_Items_in_a_Flex_Container">/ja/docs/Web/CSS/CSS_Flexible_Box_Layout/Aligning_Items_in_a_Flex_Container</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/all">/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/all</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Statements/for...in">/ja/docs/Web/JavaScript/Reference/Statements/for...in</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/some">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/some</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTML/Element/input/file">/ja/docs/Web/HTML/Element/input/file</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Errors/Unexpected_type">/ja/docs/Web/JavaScript/Reference/Errors/Unexpected_type</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment">/ja/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/String">/ja/docs/Web/JavaScript/Reference/Global_Objects/String</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Operators/Spread_syntax">/ja/docs/Web/JavaScript/Reference/Operators/Spread_syntax</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/String/split">/ja/docs/Web/JavaScript/Reference/Global_Objects/String/split</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Object">/ja/docs/Web/JavaScript/Reference/Global_Objects/Object</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTML/Element/input/date">/ja/docs/Web/HTML/Element/input/date</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Errors/Not_defined">/ja/docs/Web/JavaScript/Reference/Errors/Not_defined</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Math/random">/ja/docs/Web/JavaScript/Reference/Global_Objects/Math/random</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Learn">/ja/docs/Learn</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/String/match">/ja/docs/Web/JavaScript/Reference/Global_Objects/String/match</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/A_re-introduction_to_JavaScript">/ja/docs/Web/JavaScript/A_re-introduction_to_JavaScript</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Guide/Working_with_Objects">/ja/docs/Web/JavaScript/Guide/Working_with_Objects</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/API/Document/querySelector">/ja/docs/Web/API/Document/querySelector</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Object/entries">/ja/docs/Web/JavaScript/Reference/Global_Objects/Object/entries</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTTP/Headers">/ja/docs/Web/HTTP/Headers</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse">/ja/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Date/parse">/ja/docs/Web/JavaScript/Reference/Global_Objects/Date/parse</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Statements/import">/ja/docs/Web/JavaScript/Reference/Statements/import</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/concat">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/concat</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/Events">/ja/docs/Web/Events</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS/Specificity">/ja/docs/Web/CSS/Specificity</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS/Reference">/ja/docs/Web/CSS/Reference</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Statements/for...of">/ja/docs/Web/JavaScript/Reference/Statements/for...of</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Statements/for...of">/ja/docs/Web/JavaScript/Reference/Statements/for...of</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp">/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTTP/Status/502">/ja/docs/Web/HTTP/Status/502</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTTP/Headers/X-Frame-Options">/ja/docs/Web/HTTP/Headers/X-Frame-Options</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTTP/Headers/Content-Type">/ja/docs/Web/HTTP/Headers/Content-Type</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/API/Document/getElementById">/ja/docs/Web/API/Document/getElementById</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS/position">/ja/docs/Web/CSS/position</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS/linear-gradient">/ja/docs/Web/CSS/linear-gradient</a></td> + </tr> + <tr> + <td><strong><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/Reduce">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/Reduce</a> NEW!</strong></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects">/ja/docs/Web/JavaScript/Reference/Global_Objects</a></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/Access-Control-Allow-Origin">/ja/docs/Web/HTTP/Headers/Access-Control-Allow-Origin</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Math">/ja/docs/Web/JavaScript/Reference/Global_Objects/Math</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/from">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/from</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/push">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/push</a></td> + </tr> + <tr> + <td><strong><a href="/ja/docs/Web/Progressive_web_apps">/ja/docs/Web/Progressive_web_apps</a> NEW!</strong></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/join">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/join</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTML/Element/input/checkbox">/ja/docs/Web/HTML/Element/input/checkbox</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Learn/Getting_started_with_the_web">/ja/docs/Learn/Getting_started_with_the_web</a><strong> </strong></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTML/Element/input/number">/ja/docs/Web/HTML/Element/input/number</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/every">/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/every</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Date/now">/ja/docs/Web/JavaScript/Reference/Global_Objects/Date/now</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Number">/ja/docs/Web/JavaScript/Reference/Global_Objects/Number</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Guide/Using_promises">/ja/docs/Web/JavaScript/Guide/Using_promises</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Learn/HTML/Introduction_to_HTML">/ja/docs/Learn/HTML/Introduction_to_HTML</a></td> + </tr> + <tr> + <td><strong><a href="/ja/docs/Web/JavaScript/Reference">/ja/docs/Web/JavaScript/Reference</a> NEW!</strong></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Errors/Not_a_function">/ja/docs/Web/JavaScript/Reference/Errors/Not_a_function</a></td> + </tr> + <tr> + <td></td> + </tr> + </tbody> +</table> + +<h2 id="Former_top_100_articles" name="Former_top_100_articles">以前上位100記事に入ったことがある記事</h2> + +<p>以下の一覧にある記事は、以前上位100記事に入っていたものです。将来的に上位100件に戻った際に、 "new" とタグ付けすることを防ぐために列挙しています。</p> + +<table class="standard-table" dir="ltr"> + <tbody> + <tr> + <td><a href="/ja/docs/Web/API/XMLHttpRequest">/ja/docs/Web/API/XMLHttpRequest</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/parseInt">/ja/docs/Web/JavaScript/Reference/Global_Objects/parseInt</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS/box-shadow">/ja/docs/Web/CSS/box-shadow </a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/API/History_API">/ja/docs/Web/API/History_API</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTTP/Status/400">/ja/docs/Web/HTTP/Status/400</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve">/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Tools">/ja/docs/Tools</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/then">/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise/then</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/API/WindowBase64/Base64_encoding_and_decoding">/ja/docs/Web/API/WindowBase64/Base64_encoding_and_decoding</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Tools/Debugger/Source_map_errors">/ja/docs/Tools/Debugger/Source_map_errors</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTML/Element/input/radio">/ja/docs/Web/HTML/Element/input/radio</a></td> + </tr> + <tr> + <td><a href="/ja/Apps/Progressive">/ja/Apps/Progressive</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Math/round">/ja/docs/Web/JavaScript/Reference/Global_Objects/Math/round</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Learn/HTML/Forms/Form_validation">/ja/docs/Learn/HTML/Forms/Form_validation</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_objects/Object/values">/ja/docs/Web/JavaScript/Reference/Global_objects/Object/values</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Tools/Page_Inspector/3-pane_mode">/ja/docs/Tools/Page_Inspector/3-pane_mode</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTTP/Basics_of_HTTP/MIME_types">/ja/docs/Web/HTTP/Basics_of_HTTP/MIME_types</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Data_structures">/ja/docs/Web/JavaScript/Data_structures</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Statements/let">/ja/docs/Web/JavaScript/Reference/Statements/let</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS/Media_Queries/Using_media_queries">/ja/docs/Web/CSS/Media_Queries/Using_media_queries</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/String/prototype">/ja/docs/Web/JavaScript/Reference/Global_Objects/String/prototype</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Guide/Functions">/ja/docs/Web/JavaScript/Guide/Functions</a><strong> </strong></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox">/ja/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Learn/JavaScript/Objects/JSON">/ja/docs/Learn/JavaScript/Objects/JSON</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS/CSS_Colors/Color_picker_tool">/ja/docs/Web/CSS/CSS_Colors/Color_picker_tool</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTTP">/ja/docs/Web/HTTP</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Statements/export">/ja/docs/Web/JavaScript/Reference/Statements/export</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Statements/try...catch">/ja/docs/Web/JavaScript/Reference/Statements/try...catch</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS/CSS_Backgrounds_and_Borders/Scaling_background_images">/ja/docs/Web/CSS/CSS_Backgrounds_and_Borders/Scaling_background_images</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Math/max">/ja/docs/Web/JavaScript/Reference/Global_Objects/Math/max</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions">/ja/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTTP/Headers/Cache-Control">/ja/docs/Web/HTTP/Headers/Cache-Control</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Operators/Comparison_Operators">/ja/docs/Web/JavaScript/Reference/Operators/Comparison_Operators</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Error">/ja/docs/Web/JavaScript/Reference/Global_Objects/Error</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTTP/Status/405">/ja/docs/Web/HTTP/Status/405</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS/Using_CSS_variables">/ja/docs/Web/CSS/Using_CSS_variables</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Operators/Logical_Operators">/ja/docs/Web/JavaScript/Reference/Operators/Logical_Operators</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/Guide/Events/Creating_and_triggering_events">/ja/docs/Web/Guide/Events/Creating_and_triggering_events</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Operators/await">/ja/docs/Web/JavaScript/Reference/Operators/await</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/API/Document/createElement">/ja/docs/Web/API/Document/createElement</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Learn/Common_questions/set_up_a_local_testing_server">/ja/docs/Learn/Common_questions/set_up_a_local_testing_server</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTML/Element/input/button">/ja/docs/Web/HTML/Element/input/button</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Operators/delete">/ja/docs/Web/JavaScript/Reference/Operators/delete</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/Function/apply">/ja/docs/Web/JavaScript/Reference/Global_Objects/Function/apply</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Operators/Spread_operator">/ja/docs/Web/JavaScript/Reference/Operators/Spread_operator</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/CSS/CSS_Grid_Layout">/ja/docs/Web/CSS/CSS_Grid_Layout</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/Security/Mixed_content/How_to_fix_website_with_mixed_content">/ja/docs/Web/Security/Mixed_content/How_to_fix_website_with_mixed_content</a></td> + </tr> + <tr> + <td>/en-U<a href="/ja/docs/Mozilla/Mobile/Viewport_meta_tag">S/docs/Mozilla/Mobile/Viewport_meta_tag</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/API/Window/localStorage">/ja/docs/Web/API/Window/localStorage</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTML/Element/center">/ja/docs/Web/HTML/Element/center</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/HTML/Element/marquee">/ja/docs/Web/HTML/Element/marquee</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Learn/HTML/Howto/Use_data_attributes">/ja/docs/Learn/HTML/Howto/Use_data_attributes</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Learn/Server-side/Express_Nodejs/mongoose">/ja/docs/Learn/Server-side/Express_Nodejs/mongoose</a></td> + </tr> + <tr> + <td><a href="/ja/Add-ons">/ja/Add-ons</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Learn/HTML/Forms/Sending_and_retrieving_form_data">/ja/docs/Learn/HTML/Forms/Sending_and_retrieving_form_data</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/API/Window/open">/ja/docs/Web/API/Window/open</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf">/ja/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/JavaScript/Reference/Statements/switch">/ja/docs/Web/JavaScript/Reference/Statements/switch</a></td> + </tr> + <tr> + <td><a href="/ja/docs/Web/API/Window/postMessage">/ja/docs/Web/API/Window/postMessage</a></td> + </tr> + <tr> + <td> <a href="/ja/docs/Web/CSS/overflow-wrap">/ja/docs/Web/CSS/overflow-wrap</a></td> + </tr> + </tbody> +</table> + +<div>{{MDNSidebar}}</div> diff --git a/files/ja/mdn/contribute/localize/translating_pages/index.html b/files/ja/mdn/contribute/localize/translating_pages/index.html new file mode 100644 index 0000000000..fc472b67c5 --- /dev/null +++ b/files/ja/mdn/contribute/localize/translating_pages/index.html @@ -0,0 +1,72 @@ +--- +title: MDN ページの翻訳 +slug: MDN/Contribute/Localize/Translating_pages +tags: + - Guide + - Localization + - MDN Meta + - Page Translation + - l10n + - ページ翻訳 +translation_of: MDN/Contribute/Localize/Translating_pages +--- +<div>{{MDNSidebar}}</div> + +<p>この記事は MDN のページを翻訳する際に参考にしていただく記事です。翻訳の手順や、コンテンツの内容に応じた適切な翻訳を行う際のヒントが含まれています。</p> + +<h2 id="Starting_a_new_page_translation" name="Starting_a_new_page_translation">ページの翻訳を始める</h2> + +<p>このサイトのページを日本語などに翻訳してみたいと思われたときは、以下の手順にしたがってください。</p> + +<ol> + <li><a href="https://developer.mozilla.org">読取専用の MDN サイト</a>にいるのであれば、 <strong>Edit in wiki</strong> ボタンをクリックして <a href="https://wiki.developer.mozilla.org">wiki サイト</a>に切り替えてください。</li> + <li><strong>Languages</strong> メニューをクリックし、 <strong>Add a Translation</strong> (メニューの最下部) をクリックすると、 Select Languages ページが現れます。<br> + {{訳注("英語 (English (US) (en-US)) のページからのみ選択できます。")}}</li> + <li>日本語など、あなたが新たに翻訳したい先の言語を選択します。翻訳用のビューが開かれ、その左側には翻訳前の記事が表示されます。</li> + <li><strong>翻訳についての説明</strong> では記事タイトルとスラグの翻訳をしていただけます。スラグはページの URL の最後の部分のことをいいます (例えばこの記事のスラグは "Translating_pages" になります)。スラグは翻訳するかどうかは各言語のコミュニティによりますが、翻訳しない場合は英語版のものを利用してください ({{訳注("日本語版では、記事タイトルは翻訳し、スラグは翻訳しないのが原則です")}})。他の日本語版の記事を参考にしながら翻訳の一般的な方法に従っておくといいでしょう。<strong>翻訳についての説明</strong>の横にあるマイナスのマークをクリックするとこれらの編集画面を閉じておいて、<strong>内容を翻訳</strong> の節のスペースを増やすことも可能です。</li> + <li><strong>内容を翻訳</strong> よりも下がページの記事本文です。翻訳を始めてください。</li> + <li>ページに付加する<strong> タグ </strong>を1つ以上付けます。</li> + <li>終わったら <strong>変更を保存</strong> をクリックして内容を保存します。</li> +</ol> + +<div class="note"><strong>Note:</strong> 翻訳ビューは最初は英語版のユーザインターフェイス(UI)で表示されます。次回以降に翻訳ビューを開いた場合、日本語版が使用可能であれば日本語版のUIで表示されます。 MDN の UI は <a href="https://pontoon.mozilla.org/projects/mdn/" title="https://pontoon.mozilla.org/projects/mdn/">Pontoon</a>を使用して日本語化が可能です。詳細とツールの使い方については <a href="/ja/docs/Mozilla/Localization/Localizing_with_Pontoon" title="/ja/docs/Mozilla/Localization/Localizing_with_Pontoon">Localizing with Pontoon</a> を御覧ください。</div> + +<div class="note">日本語翻訳向け UserScript のご紹介<br> +MDN 公式の機能ではなく翻訳コミュニティの成果ですが、下記の UserScript を導入すると処理の手間が省けます。<br> +<a href="https://groups.google.com/forum/#!topic/mozilla-translations-ja/0CxlXZDeJB4">Google Groups: MDN で新規翻訳する際に下ごしらえする UserScript</a><br> +<a href="https://github.com/mozilla-japan/translation/tree/master/MDN">UserScript のリポジトリ (インストールはこちらから)</a></div> + +<h2 id="Editing_a_translated_page" name="Editing_a_translated_page">翻訳されたページの編集</h2> + +<ul> + <li>(Wiki サイトの) 翻訳されたページで <strong>編集</strong> ボタンをクリックしてください。翻訳ビューが開きます。</li> +</ul> + +<p>翻訳が最後に更新された後で英語版が変更されている場合、「内容を翻訳」ビューには、英語版の変更点のソースレベルの「差分」が表示されます。これは、翻訳で何を更新する必要があるかを確認するのに役立ちます。</p> + +<h2 id="Tagging_translations" name="Tagging_translations">タグの翻訳</h2> + +<p>たとえ記事が英語版の翻訳であったとしても、すべてのページに少なくともひとつのタグを付ける必要があります。一般的に、オリジナル記事と同じタグを使うのがいい考えです。</p> + +<div class="blockIndicator warning"> +<p><strong>翻訳者とローカライザーへの注意事項:</strong> <a href="/ja/docs/MDN/Contribute/Howto/Tag">適切にタグづけする方法</a>に記載されているタグを翻訳しないでください。これらのタグは、検索フィルターの操作や、特定のサイト管理タスクや自動化されたデータ処理などの特定の目的のために使用されており、翻訳することでこれらのプロセスに支障をきたす可能性があります。</p> +</div> + +<p>なお、既存のタグが記事の中身を表せない場合には新たなタグを自由に作ることができます。</p> + +<h2 id="Tips_for_new_localizers" name="Tips_for_new_localizers">新しい翻訳者向け Tips</h2> + +<p>MDN のローカライズに慣れていない場合、いくつかヒントがあります:</p> + +<ul> + <li><a href="/ja/docs/Glossary">用語集</a>内の記事は、短くシンプルなので、新規翻訳者に良いです。</li> + <li><a href="/ja/docs/tag/l10n%3Apriority">"l10n:priority" とタグづけされた</a> 記事は優先度が高いと考えられています。また、一般に、チュートリアルと概念的な記事は、読者が新しい概念を学ぶ時に翻訳の必要性が最も高いために、リファレンスページと比べて高優先です。</li> + <li><code>\{{some-text("more text")}}</code> のように二重波括弧で囲まれたテキストを見かけたら、そのまま訳さずに、 句読点も変えずにおきます。これは<a href="/ja/docs/MDN/Contribute/Structures/Macros">マクロ</a>で、たぶんページの構造を作ったり、その他の役立つことを行っています。 マクロで生成された訳されないテキストが見えるでしょうが、もっと MDN の経験を踏むまで気にしないでください。 (マクロはとても強力なので、このテキストを変更するには<a href="/ja/docs/MDN/Contribute/Tools/Template_editing">特別な権限</a>が必要です。気になるなら、<a href="/ja/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros">よく使われるマクロ</a>を見て、マクロにできることを見てください。</li> + <li><a href="/ja/docs/MDN/Contribute/Localize/Localization_projects">Localization プロジェクトのページ</a>を見てあなたのロケールのローカライゼーションの詳細を発見してください。</li> +</ul> + +<h2 id="日本語版での翻訳作業について">日本語版での翻訳作業について</h2> + +<p>日本語版での翻訳作業の手順や役に立つ情報については、翻訳コミュニティのGitHub の Wiki にある「<a href="https://github.com/mozilla-japan/translation/wiki/Get-started-with-translation-of-Mozilla-documentations">Mozillaドキュメント翻訳の始め方</a>」というページにまとめられています。</p> + +<p>翻訳コミュニティの GitHub の <a href="https://github.com/mozilla-japan/translation/wiki">Wiki</a> の他のページや <a href="https://github.com/mozilla-japan/translation/issues">Issues</a> で募集されている翻訳なども参考にしてください。</p> diff --git a/files/ja/mdn/contribute/onboarding/index.html b/files/ja/mdn/contribute/onboarding/index.html new file mode 100644 index 0000000000..097e2bd38b --- /dev/null +++ b/files/ja/mdn/contribute/onboarding/index.html @@ -0,0 +1,99 @@ +--- +title: 'MDN web docs: 搭乗ガイド' +slug: MDN/Contribute/Onboarding +tags: + - MDN Meta + - ガイド + - ドキュメント + - 初心者 + - 書き方 +translation_of: MDN/Contribute/Onboarding +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p><span class="seoSummary">この文書では、 MDN でフルタイムで作業するプロのライターが、始めるにあたって知っておくべきトピックについて説明します。気軽な態度で MDN に協力する場合は、気にする必要はありません。</span>いきなり<a href="/ja/docs/MDN/Getting_started">始める</a>ことができます。また、興味があるのであれば暇な時に読んでいただいても構いません。</p> + +<h2 id="What_is_MDN_web_docs" name="What_is_MDN_web_docs">MDN web docs とは</h2> + +<ul> + <li><a href="https://wiki.mozilla.org/MDN/">Mission and vision</a> (英語)</li> + <li><a href="https://wiki.mozilla.org/Engagement/MDN_Durable_Team">Mozilla's MDN staff team</a> (英語)</li> +</ul> + +<h2 id="Guidelines" name="Guidelines">ガイドライン</h2> + +<p>以下は、プロのライターが一般的に新しい環境で働き始める前に知りたいと思うことです。</p> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Does_this_belong_on_MDN">MDN に含まれるものは何か</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Editorial">編集方針</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Writing_style_guide">執筆スタイルガイド</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines">その他のガイドライン</a></li> +</ul> + +<h2 id="Basic_usage_of_the_MDN_wiki" name="Basic_usage_of_the_MDN_wiki">MDN wiki の基本的な使い方</h2> + +<p>以下の記事は、 MDN でコンテンツの作成を始めるのに必要な基本的な情報を説明しています。</p> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Howto/Create_an_MDN_account">アカウントの作成</a> — 連携組織の従業員の場合は、従業員であることが分かるメールアドレスを使用して登録することを推奨します。</li> + <li><a href="/ja/docs/MDN/Contribute/Howto/Write_an_API_reference">API リファレンスの書き方</a></li> + <li><a href="/ja/docs/MDN/Contribute/Editor">MDN エディター UI の利用</a></li> + <li><a href="/ja/docs/MDN/Contribute/Editor/Source_mode">ソースモードの使い方</a></li> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types">ページの種類</a></li> + <li><a href="/ja/docs/MDN/Contribute/Howto/Tag">ページのタグ付け方法</a></li> + <li><a href="/ja/docs/MDN/Contribute/Structures/Macros">マクロの使用</a></li> + <li><a href="/ja/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros">よく使われるマクロ</a></li> + <li><a href="/ja/docs/MDN/Contribute/Troubleshooting">トラブルシューティング</a></li> +</ul> + +<h2 id="Advanced_usage" name="Advanced_usage">高度な使い方</h2> + +<p>以下の記事では、 MDN wiki の機能のうち、すぐには必要ないかもしれませんが、最終的には遭遇する可能性のある機能について説明しています。</p> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Structures/Code_examples">コード例を追加する方法</a></li> + <li><a href="/ja/docs/MDN/Contribute/Structures">文書の構造</a></li> + <li>ブラウザーの互換性情報: <a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables">Github ベースの JSON</a> またはef="/ja/docs/MDN/Contribute/Structures/Old_compatibility_tables">旧形式のページ内の表</li> + <li><a href="/ja/docs/MDN/Contribute/Editor/Images">画像の添付</a>と<a href="/ja/docs/MDN/Contribute/Editor/Basics/Attachments">添付ウィジェット</a>の使用 — SVG 画像を添付するには特殊な権限が必要です。詳しくは Mozilla の MDN スタッフメンバーに問い合わせてください。</li> + <li><a href="/ja/docs/MDN/Contribute/Structures/Quicklinks">QuickLinks によるサイドバー</a></li> + <li><a href="/ja/docs/MDN/Contribute/Tools/Page_moving">ページの移動</a></li> + <li><a href="/ja/docs/MDN/Contribute/Localize/Translating_pages">ページの翻訳</a></li> + <li><a href="/ja/docs/MDN/Contribute/Tools/Add-ons_and_plug-ins">MDN に関するアドオン</a></li> +</ul> + +<h2 id="Processes_and_communication" name="Processes_and_communication">プロセスとコミュニケーション</h2> + +<p>この節では、 MDN コミュニティで使用されているチャンネルや、 Mozilla MDN スタッフチームで使用されているプロセスについて解説します。</p> + +<ul> + <li><a href="https://wiki.mozilla.org/Engagement/MDN_Durable_Team/Processes">Mozilla MDN staff team processes</a></li> + <li><a href="https://wiki.mozilla.org/MDN/Meetings">Public meetings</a></li> + <li><a href="/ja/docs/MDN/Community/Conversations">MDN に関するコミュニケーションチャンネル</a> + <ul> + <li><a href="https://discourse.mozilla-community.org/c/mdn">MDN ディスカッションフォーラム</a>に参加し、自己紹介をして、どのような作業をしようとしているのかを伝えてください。</li> + </ul> + </li> + <li>Kuma (MDN wiki プラットフォーム) への改良提案の方法: + <ol> + <li><a href="https://bugzilla.mozilla.org">bugzilla.mozilla.org</a> に、 Github ログインを使用してアカウントを作成してください。</li> + <li><a href="https://bugzilla.mozilla.org/form.mdn">MDN feedback form</a> を使用して、バグレポートを解こうしたり、機能や機能改善のリクエストを行ってください。</li> + <li>(任意) 次の <a href="https://wiki.mozilla.org/MDN/Meetings">MDN Dev Triage meeting</a> に参加してください。毎週 18:30 UTC です。</li> + </ol> + </li> + <li><a href="/ja/docs/MDN/Community/Working_in_community">コミュニティ内の作業</a></li> + <li><a href="/ja/docs/MDN/Contribute/Howto/Write_an_API_reference/Find_info_in_specifications">仕様書内の情報の探し方</a></li> +</ul> + +<h2 id="MDN_web_docs_topic_areas" name="MDN_web_docs_topic_areas">MDN web docs トピックエリア</h2> + +<ul> + <li><a href="/ja/docs/MDN/Doc_status/Overview">トピック別の翻訳状況の概要</a></li> + <li>HTML の<a href="/ja/docs/MDN/Doc_status/HTML">翻訳状況</a></li> + <li>CSS の<a href="/ja/docs/MDN/Doc_status/CSS">翻訳状況</a></li> + <li>JavaScript/ECMAScript の<a href="/ja/docs/MDN/Doc_status/JavaScript">翻訳状況</a></li> + <li>API の<a href="/ja/docs/MDN/Doc_status/API">翻訳状況</a></li> + <li>SVG の<a href="/ja/docs/MDN/Doc_status/SVG">翻訳状況</a></li> +</ul> diff --git a/files/ja/mdn/contribute/persona_sign-in/index.html b/files/ja/mdn/contribute/persona_sign-in/index.html new file mode 100644 index 0000000000..94a28d3e88 --- /dev/null +++ b/files/ja/mdn/contribute/persona_sign-in/index.html @@ -0,0 +1,32 @@ +--- +title: MDNへのPersonaでのサインインについて +slug: MDN/Contribute/Persona_sign-in +tags: + - Documentation + - MDN + - MDN Meta + - Mozilla + - Persona +translation_of: Archive/MDN/Persona_sign-ins +--- +<div>{{MDNSidebar}}</div><div class="warning"> +<p>MDNへのサインインを継続できるように、<a href="/docs/MDN/Contribute/Howto/Link_a_GitHub_account">今すぐあなたのMDNプロフィールとGitHubを紐付けてください</a>。</p> +</div> + +<p>現在、貢献者は、MozillaのPersonaとGitHubという、異なる2つの認証方法でMDNにサインインできます。しかし、2016年11月1日からは、ログインのための選択肢からPersonaが除外されます。従って、MDNへログインできなくなるのを防ぐために、あなたのアカウントでGitHubでの認証を有効化していただく必要があります。</p> + +<p>ご不便をおかけして申し訳ありませんが、仕方のないことなのです。</p> + +<h2 id="なぜPersonaは除外されるのか">なぜPersonaは除外されるのか</h2> + +<p>MozillaはPersonaプロジェクトを終了しており、サーバが2016年11月1日に無効化されるためです。Mozilla Wikiで、Personaを廃止するという<a href="https://wiki.mozilla.org/Identity/Persona_Shutdown_Guidelines_for_Reliers#FAQs">Mozillaのこの決定についてより詳しく知る</a>ことができます。</p> + +<h2 id="Personaはいつ除外されるのか">Personaはいつ除外されるのか</h2> + +<p>私たちは、2016年11月1日に、認証方法としてのPersonaの利用を無効化します。言い換えれば、Personaを使ってMDNにサインインできるであろう最後の日は、2016年10月31日となるでしょう。 私たちは今後、<a href="/docs/MDN/Contribute/Howto/Link_a_GitHub_account">MDNプロフィールにGitHubアカウントを加える</a>ためのお知らせを、頻度を上げながら、かつ緊急性の度合いを増しながら発行していきます。MDNアカウントへのアクセスを失うようなあらゆるリスクを防ぐために、なるべく早く紐付けを行ってください。</p> + +<h2 id="MDNが他の認証方法を採用する予定はありますか">MDNが他の認証方法を採用する予定はありますか?</h2> + +<p>とてもそうしたいところですが、私たちの要求を満たすような他の認証方法をまだ見つけられていません。さらに、他の認証方法を採用するのに必要な開発者資源を現在私たちは持っていません。当面、貢献者としてのMDNへのアクセスを保つための<em>唯一の</em>選択肢は、<a href="/docs/MDN/Contribute/Howto/Link_a_GitHub_account">MDNプロフィールにGitHubアカウントを紐付ける</a>ことのみとなります。</p> + +<p>もちろん、私たちのコンテンツを読むだけの場合、MDNにサインインする必要はありません。しかし、貢献のためのアカウントを持っていてかつ、今後も貢献できるようにしておきたいと思っているなら、2016年10月31日になる前に、<em><strong>なるべく早くあなたのプロフィールにGitHubアカウントを追加</strong></em>してください。</p> diff --git a/files/ja/mdn/contribute/processes/browser_information_resources/index.html b/files/ja/mdn/contribute/processes/browser_information_resources/index.html new file mode 100644 index 0000000000..9338fc48eb --- /dev/null +++ b/files/ja/mdn/contribute/processes/browser_information_resources/index.html @@ -0,0 +1,67 @@ +--- +title: ブラウザー特有の情報源 +slug: MDN/Contribute/Processes/Browser_information_resources +tags: + - Guide + - MDN Meta + - Processes + - ガイド + - プロセス +translation_of: MDN/Contribute/Processes/Browser_information_resources +--- +<p>{{MDNSidebar}}</p> + +<p>各ブラウザーの開発元では、ソフトウェアの開発、課題の追跡、議論の記録のために、様々なツールや手法を用いています。<span class="seoSummary">この記事では、 MDN のドキュメントを書いたり、互換性に関するデータを MDN に提供したりする際に役立つ、主要なブラウザーごとのツールや情報源を列挙しています。</span></p> + +<h2 id="Chrome">Chrome</h2> + +<p><em>コンテンツ作成中...</em></p> + +<h2 id="Edge">Edge</h2> + +<p><em>コンテンツ作成中...</em></p> + +<h2 id="Firefox">Firefox</h2> + +<p>Mozilla は常にすべての詳細を簡単に見つけられるようにしているわけではありませんが、 Firefox プロジェクトに関する基本的なことはすべてオープンな状態で行われているので、すべてのものが公開されています。 Firefox のすべてのリリースのソースコードには、昔、 Netscape から最初にフォークされたときまでさかのぼって完全にアクセスすることができます。 Mozilla のバグデータベースにもアクセスすることができます。メーリングリストや Mozilla の Discourse サーバー、 IRC チャンネルでの議論にアクセスできます。ソフトウェアの更新が作成され、議論され、最終的にソースリポジトリにマージされたときに、レビューノートの交換にアクセスすることができます。</p> + +<p>重要なのは、必要な情報をすべての情報から正確に切り分けることです。目の前に広がっているのは、 Mozillian たちが皮肉を込めて「Mozilla の火の海」と呼んでいる、広大なものです。利用可能な様々なリソースのそれぞれから何を学べるのかを説明するのではなく、学ぶことができるようになるために必要なものを見つけ、求める答えを見つけることができる利用可能なリソースを通る道を特定してみましょう。</p> + +<h3 id="Source_code" name="Source_code">ソースコード</h3> + +<p><a href="/ja/docs/Mozilla/Developer_guide/Source_Code/Mercurial">Mercurial</a> を介してソースコードにアクセスする通常の方法に加えて、ローカルコピーを手元に置かずにソースコード内の情報を検索する方法があります。</p> + +<h4 id="DXR">DXR</h4> + +<p>ソースコードに素早くアクセスする最も簡単な方法は <a href="https://dxr.mozilla.org">DXR</a> を使うことで、これは Mozilla のソースツリー全体を閲覧して強力な検索を行うことができます。他のツリーに切り替えるオプションもあるので、過去のブランチにさかのぼって見ることができ、たとえば <code>mozilla1.9.2</code> は Firefox 3.6 に対応します。また、 Firefox ESR の各リリースのコードを見ることもできます。</p> + +<p>検索は特殊な演算子に対応しています。例えば、"<code>connect</code>" という単語を検索することはできますが、 "<code>connect file:.webidl</code>" を使うと、 WebIDL ファイルのみを考慮して検索することができます。</p> + +<h4 id="Unified_Firefox_repository" name="Unified_Firefox_repository">Firefox の統合リポジトリ</h4> + +<p>Firefox のソースコードにアクセスするもう一つの便利な方法が Mozilla 統合リポジトリ (<a href="https://hg.mozilla.org/mozilla-unified/"><code>mozilla-unified</code> リポジトリ</a>) です。このリポジトリには、Firefox 3 に対応する Gecko 1.9 までの Firefox のソース履歴があります。興味のある<a href="https://hg.mozilla.org/mozilla-unified/tags">バージョンに対応する Mercurial タグ</a>を見つけることで、特定のバージョンの Firefox のソースコードを見ることができます。 DXR では、いくつかの非常に古いバージョンの Firefox を見ることができますが、ほとんどのバージョンを見る方法は提供されていないので、これは貴重なものです。このリポジトリではすべてのリリースを見ることができます。</p> + +<p>タグの命名システムは時間の経過とともにあちこちで変更されているので、探しているものを見つけるにはちょっとした探索が必要になります。原則として、次のようなタグを探してください。</p> + +<ul> + <li><code>FIREFOX_<em>n</em>_release</code></li> + <li><code>FIREFOX_RELEASE_<em>n</em>_END</code></li> + <li><code>FIREFOX_RELEASE_<em>n</em>_BASE</code></li> + <li><code>FIREFOX_RELEASE_<em>n</em></code></li> + <li><code>RELEASE_BASE_<em>n</em></code></li> + <li><code>RELEASE_BASE_<em>date</em></code></li> +</ul> + +<p>特定のリリースを確認したら、通常のツールを使ってコードを閲覧したり検索したり、 changelog と pushlog オプションを使って、リリースにどのような変更が加えられたかを確認することができます。</p> + +<h4 id="Searchfox">Searchfox</h4> + +<p><a href="https://searchfox.org/">Searchfox</a> のウェブサイトでは、Firefox のソースコードを検索するための別の方法を提供しています。 Searchfox は Firefox のリポジトリをインデックス化するツールです (最も便利なのは、メインの <a href="https://searchfox.org/mozilla-central/source">mozilla-central ソースコード</a> と、興味深いことに <a href="https://searchfox.org/whatwg-html/source">WHATWG HTML 仕様書</a>もインデックス化されていることです)。</p> + +<h2 id="Opera">Opera</h2> + +<p><em>コンテンツ作成中...</em></p> + +<h2 id="Safari">Safari</h2> + +<p><em>コンテンツ作成中...</em></p> diff --git a/files/ja/mdn/contribute/processes/cross-team_collaboration_tactics/index.html b/files/ja/mdn/contribute/processes/cross-team_collaboration_tactics/index.html new file mode 100644 index 0000000000..70ca0612ad --- /dev/null +++ b/files/ja/mdn/contribute/processes/cross-team_collaboration_tactics/index.html @@ -0,0 +1,64 @@ +--- +title: 文書作成のためのチーム間協力作戦 +slug: MDN/Contribute/Processes/Cross-team_collaboration_tactics +tags: + - Collaborating + - Guide + - MDN Meta + - Processes +translation_of: MDN/Contribute/Processes/Cross-team_collaboration_tactics +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">私たちが MDN で学んだことのひとつは、開発チームと文書作成チームが共にあるプロジェクト、API、またはある技術について密接に協力して文書を作成した場合、その文書の品質が素晴らしいということです。このガイドは開発者と文書作成者が手と手を取って協力するための戦略を示唆するものです。</span></p> + +<div class="note"> +<p>この記事は今も作成中の、生きた文書です。もしもあなたの関わる開発者/文書作成者の協力の過程で別の方法を見出したなら、是非ここにそのアイディアを追加してください!</p> +</div> + +<h2 id="つながり始める">つながり始める</h2> + +<p>理想的には、新しいテクノロジーやプロジェクトが開発され始める時に、開発チームはライターチームに対し文書化の必要のある何かが出てくると知らせるでしょう。ときどきそうはならず、MDNチームはBugzillaを監視して文書化が必要な成果がないのか見ています。しかし完全な世界では、直接的な方法で進歩していきます。</p> + +<p>MDN チームに新プロジェクトを知らせるための最良な方法は<a href="https://bugzilla.mozilla.org/form.doc">文書化リクエストのバグを報告する</a>ことです。 質問の問い合わせ先のリストがあると助かります! プロジェクトに関連するバグのリンクが入っていてもとても助かります。</p> + +<h2 id="情報を共有する">情報を共有する</h2> + +<p>情報共有の便利な方法がいくつかあります。このようなものです。</p> + +<h3 id="バグ">バグ</h3> + +<p>単に文書化チームに文書化に影響するバグでフラグを立てることですごく助かります。dev-doc-needed キーワードとコメントタグを適切に使すうのは長くかかることもあります。詳細は<a href="/ja/docs/Developer_Guide/Getting_documentation_updated">文書を最新化する</a>を見てください。</p> + +<h3 id="ミーティング">ミーティング</h3> + +<p>開発チームは通常ミーティングをします。それが可能で役立つときには (役立つ場面は多いです)、MDN チームはミーティングに誰かを出席させようとします。何が起きているか、スケジュールはどうか、などを知るのは良い方法です。</p> + +<p>加えて、ライターは大きな文書化エリア(例えば Web API 文書)で作業し、その文書化の状況のためだけにミーティングすることもしばしばあります。ライターは開発チーム代表がこうしたミーティングに出るのを<strong>好感します</strong>; 関係する全員にとって極めて有益です。</p> + +<p>典型的にこれは短いチェックインのミーティングで、次のようなアジェンダを伴います:</p> + +<ol> + <li>貢献するライターの短い状況更新。</li> + <li>開発チームからライターへの質問/更新: 特定文書の状況の質問や、特に急ぐ特定コンテンツの情報や、既存コンテンツの問題への注意などを含みます。</li> + <li>ライターから開発チームへの質問/更新: 特定のバグがもうすぐ解決しそうか否かとか、特定の文書のレビューが可能になったりするかとか、ある API の質問に答えられるエンジニアがいるのかどうかとか、ライターがそんな種類の質問をできるチャンスです。</li> +</ol> + +<p><a href="https://docs.google.com/document/d/1N-1dYkev064CDdWFh-Ho7bDWsaFShKY3oOwVD-6GIZ0/edit#heading=h.m6id8awidm4o">Developer Content Coordination Meeting</a> は毎週火曜日の太平洋時間 9 AM に、Vidyo テレビ会議システムの <a href="https://v.mozilla.com/flex.html?roomdirect.html&key=gMM1xZxpQgqiQFNkUR3eBuHgxg">"mdn" チャンネル</a> (音声のみもあり)で開催されます。このミーティングでは、MDNライターコミュニティ、開発関係チーム、API ドキュメントチーム、その他が集まって作業がどこまで進んだかや、何が出てきたかや、開発者と共有すべき最重要事項は何かといった情報交換を行います。これにより、全員がプロモーションの優先度やトピックの文書化のための同じページに乗ることができて、開発者にとって役立つ方法で知らせることのできるフィートバックを返すことにもなります。全員がそこから多くを得て、通常は30分か、少ないかくらいの時間で終わります。</p> + +<h3 id="集中作業週間">集中作業週間</h3> + +<p>開発チームに集中作業週間やミートアップがあれば、関連ドキュメントのライターの招待を真剣に考えるべきです。これは多くの利益があり、次のようなものです:</p> + +<ul> + <li>起こっていることを初めて扱うライターを派遣することによって、コミュニケーションが向上する</li> + <li>ライターと開発者がお互いを良く知ることによって、関係が改善する</li> + <li>ライターが正しい話し相手を見つけるのに便利なアクセスが得られる</li> + <li>質問や問題解決のための1対1の会話をする、時別な機会が得られる</li> +</ul> + +<p>集中作業週間があって、あなたのトピック領域の担当のライターがいるかどうかわからない場合、<a href="mailto:jperrier@mozilla.com?subject=Writer%20for%20work%20week">ドキュメントチームのリーダーにeメールしてください</a>(Jean-Yves Perrier まで)、そして彼が誰か派遣できるか確認します。行ける人を探します (あるいは、もっと良い場合、あなたのプロジェクト担当のライターのことも)! ただ覚えてほしいのは、しかしライティングチームは小さく、集中作業週間に参加できる人がちょっとした注意で見つかることはトリッキーです。</p> + +<h3 id="文書化の状態を表示するページ">文書化の状態を表示するページ</h3> + +<p>MDN の大き目の文書化プロジェクトでは<a href="/ja/docs/Project:MDN/Contributing/Doc_status_page">文書化ステータスページ</a>を使って、作業を完了させるのに何をしないといけないか、また何がすでに完了しているか、追跡しています。このページは達成する必要があるタスクと、各タスクのステータスとを一覧にしています。</p> diff --git a/files/ja/mdn/contribute/processes/index.html b/files/ja/mdn/contribute/processes/index.html new file mode 100644 index 0000000000..0927b9c486 --- /dev/null +++ b/files/ja/mdn/contribute/processes/index.html @@ -0,0 +1,15 @@ +--- +title: 文書作成のプロセス +slug: MDN/Contribute/Processes +tags: + - Landing + - MDN Meta + - Processes + - TopicStub +translation_of: MDN/Contribute/Processes +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p>MDN 文書作成プロジェクトは非常に大規模です。カバーするべき莫大な数の技術があり、数百人の貢献者が世界中に散らばっています。秩序をもたらすために、従うべき標準の手順を定め、特定の文書化関連の作業を行うときにはこれに従います。ここでは、これらの手順についてのガイドを紹介します。</p> + +<p>{{LandingPageListSubPages()}}</p> diff --git a/files/ja/mdn/contribute/processes/requesting_elevated_privileges/index.html b/files/ja/mdn/contribute/processes/requesting_elevated_privileges/index.html new file mode 100644 index 0000000000..85cce731eb --- /dev/null +++ b/files/ja/mdn/contribute/processes/requesting_elevated_privileges/index.html @@ -0,0 +1,24 @@ +--- +title: 上位権限の申請 +slug: MDN/Contribute/Processes/Requesting_elevated_privileges +tags: + - Guide + - MDN Meta + - Processes + - ガイド + - 手続 +translation_of: MDN/Contribute/Processes/Requesting_elevated_privileges +--- +<div>{{MDNSidebar}}</div> + +<p>MDN の一部のツールや操作では、通常のユーザーでは利用できない昇格したアクセス権限が必要です。</p> + +<p>ツール使用の権限が欲しい、または必要な場合には以下の手順に従ってください。</p> + +<ol> + <li><a href="mailto:mdn-admins@mozilla.org">mdn-admins@mozilla.org</a> へ (英語で) メールを書き、何が必要かと、その理由をも説明してください。 <strong>MDN アカウント名を書いてください。</strong></li> + <li>権限を求めるそれぞれのツールについて、なぜあなたがその権限を得る条件を満たしているのかを説明していることを確認してください。分からない点は、そのツールの「<a href="/en-US/docs/MDN/Contribute/Tools/Page_moving#Conditions_for_gaining_this_privilege">この権限を得る条件</a>」の節を参照してください。</li> + <li>申請が承認されると、 <a href="/ja/docs/MDN/Community/Roles/Admins">MDN 管理者</a>の一人がそのツールに必要な権限を付与します。</li> +</ol> + +<p>誤った使用、濫用、重大な問題 (ツールに危険なバグが新たに発見された等) があった場合は、管理者がツールへのアクセスを停止することがあります。</p> diff --git a/files/ja/mdn/contribute/processes/trello/index.html b/files/ja/mdn/contribute/processes/trello/index.html new file mode 100644 index 0000000000..6404404c6e --- /dev/null +++ b/files/ja/mdn/contribute/processes/trello/index.html @@ -0,0 +1,94 @@ +--- +title: Trello +slug: MDN/Contribute/Processes/Trello +translation_of: Archive/Meta_docs/Trello +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">MDN コミュニティは <a href="https://trello.com/b/HAhl54zz/mdn-content-team-status">Trello 掲示板</a> を使用して改善する必要のあるもの、更新する必要のあるもの、そしてコンテンツに追加する必要のあるものを組織化し、その進行を管理しています。このガイドは Trello が何なのか、どのように使うのかを知る助けになるでしょう。</span></p> + +<p>Having a tool like this to maintain a public task list lets our entire community participate in planning, and helps everyone understand what we're working on. That way, both MDN staff writers and our amazing community of volunteer contributors can know what's going on at a glance. Our board is public, meaning that <a href="https://trello.com/b/HAhl54zz/mdn-content-team-status">everyone can see it</a>. If you already have an account on Trello, you can star (favorite/bookmark) the board so that you can get to it quickly whenever you connect to Trello.</p> + +<h2 id="Trello_の紹介">Trello の紹介</h2> + +<p>The Trello software is a Web application (created by Trello, Inc.) which you can access using your Web browser or an <a href="https://trello.com/platforms">app on your mobile device</a> (Android, iOS, Kindle Fire, and Windows 8 are among the supported platforms). This lets you check or update the Trello board at your convenience. For more information, you can read their <a href="https://trello.com/about">"about" page</a>.</p> + +<h3 id="Trello_掲示板">Trello 掲示板</h3> + +<p>A board is composed of <strong>lists</strong>, and each list is composed of <strong>cards</strong>. Every card represents an "action item", which is a task that needs to be accomplished. You can add comments, due dates, detailed lists of sub-tasks, etc. on every card. But most importantly, you can drag and drop a card from a list to another, which means the task has changed status; for instance, you might drag a card from the "Doing" column to the "Review needed" column, which indicates that you've finished the task and would like for someone to review your work.</p> + +<p><img alt="Screenshot of the MDN content Trello board." src="https://mdn.mozillademos.org/files/10351/mdn_board.JPG" style="border-style: solid; border-width: 1px; height: 460px; width: 968px;"></p> + +<h4 id="Lists">Lists</h4> + +<p>A list is a set of cards; while you can assign whatever meaning you wish to each column, the MDN team uses each column to represent the status of the task. The farther to the right the column is, the closer to complete the task is. This is similar to the <a href="http://hamberg.no/gtd/">GTD method</a> or the <a href="https://en.wikipedia.org/wiki/Kanban#Kanban_cards">Kanban methodology</a>.</p> + +<p>We have the following primary lists (other lists may crop up temporarily from time to time):</p> + +<dl> + <dt>On Hold</dt> + <dd>The tasks here have been accepted as something that need to be done, but are not currently being actively worked on. When work begins on a task, it should advance to the next column.</dd> + <dt>Doing</dt> + <dd>The tasks in this column are actively being worked on.</dd> + <dt>Review Needed</dt> + <dd>The tasks in this list have been completed but the writer(s) would like someone to review the work to ensure that it's accurate and/or stylistically/grammatically.</dd> + <dt>No Update in the last 14 days</dt> + <dd>Bugs in this list have been languishing with no new information for more than two weeks. These bugs are in danger of being moved back into the On Hold list unless their status is updated soon.</dd> + <dt>Completed in...</dt> + <dd>We create lists of bugs created in specific months to help us track our rate of progress and to be able to provide achievement lists</dd> +</dl> + +<p>Lists are simply are a collection of cards with a title, used to organize cards.</p> + +<h4 id="Cards">Cards</h4> + +<p>A card has much more content in it. As mentioned earlier, a card corresponds to a specific task or project. The card is described by its title which is displayed on the "front" of the card when you're looking at the board. Clicking on a card "flips" the card, showing you a panel with additional details. The detail view looks something like this:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/10353/screenshot-trello%20com%202015-04-02%2013-20-54.png" style="height: 603px; width: 510px;"></p> + +<p>A card's detail view has these sections:</p> + +<dl> + <dt>1. Members</dt> + <dd>The members of the board that are assigned to this task/card. These are the Trello users that are working on the task in some way. Here, we can see that four people are involved with this task.</dd> + <dt>2. Labels</dt> + <dd>You can think of labels as themes or categories that can apply to more than one list. Here, we can see that this card is related to "Open Web Docs" (a category), "Q1 Delivery" (a planning tag), "Learning Area" (a tag indicating a<a href="/en-US/Learn"> section of MDN</a>), etc. These labels are used for organizational purposes, but are also helpful for filtering; see {{anch("Filters")}} below.</dd> + <dt>3. Due date</dt> + <dd>You can add a due date for a card to help with planning. This date can also be used for sorting and filtering. Trello can also be configured to display a calendar showing items that are due in a given time period, but this feature is not currently enabled on the MDN Content Team Status board.</dd> + <dt>4. Content</dt> + <dd>In this example, the card has a checklist to detail the precise actions that are needed to complete the task. You might also find comments and attachments inside a card. So if someone wants to put a note for this card, one can add a comment and so on. Usually, checklists are used to break down a task in smaller units which do not need to be displayed for everyone on the board.</dd> +</dl> + +<h4 id="Filters">Filters</h4> + +<p>If you look back at the <a href="https://mdn.mozillademos.org/files/10351/mdn_board.JPG">first screenshot</a>, you can see that there are a lot of cards. While working on some project, you might want to focus on specific ones (such as those associated with a particular technology or project). To make the board clearer and to find the right cards more efficiently, you can use filters.</p> + +<p>For example, if you only want to see the cards representing tasks or projects that are first quarter goals, you can turn on the corresponding filter on the label "Q1 Deliverables" and get this as a result:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/10355/screenshot-trello%20com%202015-04-02%2013-43-10.png" style="border-style: solid; border-width: 1px; height: 349px; width: 753px;"></p> + +<p>Experiment with filters! You can filter on members (to find work being done by specific people), due dates, and more.</p> + +<h2 id="Trello_の使い方">Trello の使い方</h2> + +<p>Every member of the writing staff is a member of this board. In addition, volunteers can easily get access too. See {{anch("Getting involved")}} to learn how.</p> + +<p>Once you have access, you can either create cards representing proposed or ongoing projects, and you can add yourself to a card to indicate that you intend to work on that task. You can then update cards with new details such as new comments, attachments, or changes to to-do lists on the cards.</p> + +<h2 id="参加するには">参加するには</h2> + +<p>We encourage you to join us and <a href="/en-US/docs/MDN/Contribute">contribute</a> to these tasks! Pick a task that is described on one of the cards and <a href="/en-US/docs/MDN/Getting_started">start working on it</a>. Once you are working on it, you'll need to be able to edit the corresponding card. For this you'll need to have a Trello account, which is free. Then you will need an administrator of the board to add you to the board. To contact an administrator, you can:</p> + +<ul> + <li><a href="mailto:mdn-admins@mozilla.org?subject=MDN%20Content%20Trello%20board%20write%20access%20request&body=I%20would%20like%20write%20access%20for%20the%20MDN%20Content%20Trello%20board.%0A%0AI%20plan%20to%20work%20on%3A%20%3Cadd%20details%20here%3E%0A%0AMy%20Trello%20username%20is%3A%20%3Cadd%20username%20here%3E" title="Email the MDN administration team">Email the MDN administration team</a></li> + <li>Or just drop into the <a href="https://chat.mozilla.org/#/room/#mdn:mozilla.org">MDN Web Docs chat room</a> any time and politely ask if an admin is around. Typically there will be at least one around between around 5 AM and 5 PM Pacific time.</li> +</ul> + +<h2 id="こちらもご覧ください">こちらもご覧ください</h2> + +<ul> + <li><a href="https://trello.com/b/p56Gwq46/mdndev-rocks">MDN 開発チームの Trello 掲示板</a></li> + <li><a href="https://trello.com/b/LDggrYSV/learning-area-glossary">The Learning Area Trello board</a></li> + <li><a href="https://trello.com/guide">The Trello Guide</a></li> + <li><a href="/en-US/docs/MDN/Community/Whats_happening">Following what is happening on MDN</a></li> +</ul> diff --git a/files/ja/mdn/dashboards/editors/index.html b/files/ja/mdn/dashboards/editors/index.html new file mode 100644 index 0000000000..5001a43f0c --- /dev/null +++ b/files/ja/mdn/dashboards/editors/index.html @@ -0,0 +1,21 @@ +--- +title: 編集者 +slug: MDN/Dashboards/Editors +tags: + - MDN Meta + - MDN プロジェクト + - ダッシュボード + - ドキュメンテーション +translation_of: MDN/Dashboards/Editors +--- +<div>{{MDNSidebar}}</div> + +<h2 id="編集者の総数">編集者の総数</h2> + +<p><img alt="The amount of editors grows quickly at the beginning of the MDN history from 2005-2007, then went down and stayed flat until 2010 where it started to grow a bit. A complete changed happened in 2012 and the line grows steadily to more than 1000 editors." src="https://docs.google.com/spreadsheets/d/1IgumrIGuS2v6HVHz0Ko1SlX2dNvqwTj6rq6eldtr1EI/pubchart?oid=37&format=image" style="height: 361px; width: 645px;"></p> + +<h2 id="タイプ別エディタ">タイプ別エディタ</h2> + +<p><img alt="" src="https://docs.google.com/spreadsheets/d/1IgumrIGuS2v6HVHz0Ko1SlX2dNvqwTj6rq6eldtr1EI/pubchart?oid=19&format=image" style="height: 259px; width: 524px;"><img alt="" src="https://docs.google.com/spreadsheets/d/1IgumrIGuS2v6HVHz0Ko1SlX2dNvqwTj6rq6eldtr1EI/pubchart?oid=21&format=image" style="height: 265px; width: 428px;"></p> + +<p><img alt="" src="https://docs.google.com/spreadsheets/d/1IgumrIGuS2v6HVHz0Ko1SlX2dNvqwTj6rq6eldtr1EI/pubchart?oid=20&format=image" style="height: 257px; width: 519px;"><img alt="" src="https://docs.google.com/spreadsheets/d/1IgumrIGuS2v6HVHz0Ko1SlX2dNvqwTj6rq6eldtr1EI/pubchart?oid=22&format=image" style="height: 254px; width: 411px;"></p> diff --git a/files/ja/mdn/dashboards/index.html b/files/ja/mdn/dashboards/index.html new file mode 100644 index 0000000000..a78d68bf76 --- /dev/null +++ b/files/ja/mdn/dashboards/index.html @@ -0,0 +1,17 @@ +--- +title: ダッシュボード +slug: MDN/Dashboards +tags: + - Draft + - MDN Meta + - ダッシュボード + - 概要 +translation_of: MDN/Dashboards +--- +<div>{{MDNSidebar}}{{Draft}}</div> + +<p class="summary">いくつかの指標を表示するダッシュボードがいくつかあります。</p> + +<p><a href="/ja/docs/MDN/Dashboards/Editors">編集者の詳細について詳細を知る</a></p> + +<p>{{SubpagesWithSummaries}}</p> diff --git a/files/ja/mdn/editor/basics/attachments/index.html b/files/ja/mdn/editor/basics/attachments/index.html new file mode 100644 index 0000000000..3c9b5bf8af --- /dev/null +++ b/files/ja/mdn/editor/basics/attachments/index.html @@ -0,0 +1,79 @@ +--- +title: MDN エディターの添付ファイル +slug: MDN/Editor/Basics/Attachments +tags: + - Beginner + - Guide + - MDN Meta + - editor + - エディター + - ガイド + - 初心者 +translation_of: MDN/Editor/Basics/Attachments +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">MDN エディターの添付ファイルの節では、現在の文書でどのファイルが使用されているのかを確認できるとともに、MDN コンテンツで使用するファイルを MDN にアップロードすることができます。</p> + +<div class="note"> +<p>この節は、ページにファイルを添付するのに必要な権限を持っている場合にのみ表示されます。既定ではユーザーはこの権限を持っていませんので、ファイルを添付する必要がある場合は、 <a href="/ja/docs/MDN/Contribute/Processes/Requesting_elevated_privileges">MDN 管理者にメール</a>で権限を申請してください。</p> +</div> + +<p>添付ファイルの節が表示されるのは、既存の文書を編集する場合だけです。新しい記事を編集するためのエディターには表示されません。</p> + +<h2 id="Workflow_for_attachments" name="Workflow_for_attachments">添付ファイルのワークフロー</h2> + +<p>添付ファイルアップロード機能の動作は、それぞれのアップロード後に再表示されるページの中に結果が表示されます。この時点でページに行った保存前の編集があった場合は、失われる可能性があります。したがって、添付ファイルをアップロードする前にまず編集結果を保存するのがいいでしょう。</p> + +<p>良いワークフローは以下の通りです。</p> + +<ol> + <li>編集を行い、画像を挿入したい場所にプレイスホルダーのテキストを作成する。</li> + <li>編集を保存する。</li> + <li>画像を添付する。</li> + <li>プレイスホルダーの場所に画像を挿入する。</li> + <li>作業を再び保存して確認する。</li> +</ol> + +<p>添付ファイルをアップロードする際に未公開の編集がある場合は、下書きとして保存され、編集ボックスの上部にある<strong>下書きを復元</strong>リンクをクリックすることで復元することができます。また、添付ファイルをアップロードする前に<strong>公開して編集を継続</strong>をクリックしても構いません。しかし、時間が長すぎたり復元を忘れたりすると失われる可能性があるので、上記のワークフローをお勧めします。</p> + +<h2 id="The_attachments_UI" name="The_attachments_UI">添付ファイルのユーザーインターフェイス</h2> + +<p>ページに添付ファイルを追加するには、<strong>ファイルをアップロード</strong>ボタンをクリックしてください。添付ファイルの節はこのように表示されます。</p> + +<p><img alt="エディターの添付ファイルの節のスクリーンショット、ファイルのアップロードのためのコントロール付き" src="https://mdn.mozillademos.org/files/16486/attachments-no-files-ja.png" style="border-style: solid; border-width: 2px; height: 280px; width: 1227px;"></p> + +<p>ご覧のとおり表があり、アップロードするファイルを選択し、タイトルと、任意で概要および追加のコメントを設定することができます。タイトルは必須で、ファイルを説明して文脈との関連付けが理解できるようにしてください。欄を埋めたらファイルを選択し、<strong>アップロード</strong>ボタンを押して MDN に送信してください。</p> + +<p>添付ファイルの最も一般的な利用法は、ページへの画像の追加です。画像をアップロードする際は、画像最適化ツールを使用してファイルのダウンロードができるだけ小さくなるようにしてください。これはページの読み込み時間を改善し、全体的な MDN の性能を助けます。お持ちであればお好みのツールを使用してください。そうでなければ、手軽なウェブツールとして <a class="external external-icon" href="https://tinypng.com/">TinyPNG</a> を提案します。</p> + +<div class="note"> +<p>MDN の添付ファイルとして許可されているのは、 GIF, JPEG, PN , HTML などのわずかなファイルタイプのみです。 Photoshop 画像は許可されていますが、非常に特殊な場合を除いて避けてください。他のファイルタイプはアップロードフォームで許可されていません。 SVG ファイルのアップロードには特殊な権限が必要ですので、 SVG ファイルをアップロードする必要があるのであれば、 <a href="mdn-admins@mozilla.org">MDN 執筆チームに相談</a>してください。</p> +</div> + +<p>気軽に<a class="new" href="/ja/docs/MDN/Contribute/Editor/Basics/Attachments$edit" title="/ja/docs/Project:MDN/Contributing/Editor_guide$edit">このページをエディターで開き</a>、最下部の添付ファイル一覧を見てみてください。</p> + +<p>ファイルが添付されると、記事に画像を追加する際に<strong>画像のプロパティ</strong>ダイアログボックスに (フォームで指定したタイトルで) 現れます。このインターフェイスの詳細は、<a href="/ja/docs/MDN/Contribute/Editor/Images">画像</a>を参照してください。</p> + +<h2 id="Restricted_access" name="Restricted_access">アクセス制限</h2> + +<p>MDN Web Docs に属さない画像のアップロードは、破壊行為やスパムにつながる可能性があることは明らかですので、このツールはすべてのユーザーが利用できる訳ではありません。</p> + +<h3 id="Roles_that_have_this_privilege" name="Roles_that_have_this_privilege">この権限を持つロール</h3> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Admins"><strong>Admins</strong></a></li> + <li><a href="/ja/docs/MDN/Contribute/Topic_driver_role"><strong>Topic drivers</strong></a></li> + <li><a href="/ja/docs/MDN/Contribute/Localization_driver_role"><strong>Localization drivers</strong></a></li> +</ul> + +<h3 id="Conditions_for_gaining_this_privilege" name="Conditions_for_gaining_this_privilege">この権限を得るための条件</h3> + +<p>以下の条件を満たせば、このツールへのアクセス権を得ることができます。</p> + +<ul> + <li><strong>日常的に</strong>アップロードを行う必要がある (例えば、いくつもの画像の添付ファイルを必要とする一連のページで活発に作業している場合)。たまにしか画像を添付する必要がないのであれば、管理者に依頼してください。</li> + <li>日常的に MDN を編集しており、建設的な協力の記録がある場合。</li> +</ul> + +<p>この権限を取得する手続については、<a href="/ja/docs/MDN/Contribute/Processes/Requesting_elevated_privileges">上位権限の申請</a>を参照してください。</p> diff --git a/files/ja/mdn/editor/basics/index.html b/files/ja/mdn/editor/basics/index.html new file mode 100644 index 0000000000..0dda9a4017 --- /dev/null +++ b/files/ja/mdn/editor/basics/index.html @@ -0,0 +1,73 @@ +--- +title: エディターの UI 要素 +slug: MDN/Editor/Basics +tags: + - Beginner + - Documentation + - Guide + - MDN + - MDN Meta + - editor + - 要更新 +translation_of: MDN/Editor/Basics +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">MDN に組み込まれた WYSIWYG エディターは、記事やサイト内のほとんどの作成、編集、改良ができるだけ楽になるように設計されています。エディターウィンドウには、8つのキーエリアがあります。このページは、全ての編集環境の使い方がわかるように、各セクションの情報を提供します。</span></p> + +<div class="note"> +<p>私たちは常に MDN を改良しているため、この文書やスクリーンショットがやや時代遅れになる事もあります。定期的にこの文書を更新して、使い物にならないほど遅れるのを防ぐつもりです。</p> +</div> + +<p><img alt="Screenshot of the editor UI (August 2017) with each section labeled" src="https://mdn.mozillademos.org/files/15261/edit-page-with-labels.png" style="border-style: solid; border-width: 2px; height: 723px; width: 808px;"></p> + +<p>上に示した通り、エディター UI は下記の部分から成っています。エディターの各部分については、下記のリンクをクリックして読んでください。</p> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Editor/Basics/Page_info">ページ情報</a></li> + <li><a href="/ja/docs/MDN/Contribute/Editor/Basics/Page_controls">ページコントロール</a></li> + <li><a href="/ja/docs/MDN/Contribute/Editor/Basics/Toolbar">ツールバー</a></li> + <li><a href="/ja/docs/MDN/Contribute/Editor/Edit_box">編集ボックス</a></li> + <li><a href="/ja/docs/MDN/Contribute/Editor/Basics/Tags">タグ</a></li> + <li><a href="#Revision_comment">リビジョンコメント</a></li> + <li><a href="#Review_requests">レビュー要求</a></li> + <li><a href="/ja/docs/MDN/Contribute/Editor/Basics/Attachments">添付ファイル</a></li> +</ul> + +<h2 id="Edit_box" name="Edit_box">編集ボックス</h2> + +<p>編集ボックスは、もちろん、あなたが実際に執筆をするところです。</p> + +<p>編集ボックスを右クリックすると、クリックの状況に応じて適切な追加オプションが表示されます。たとえば、テーブル内を右クリックするとテーブル関連のオプションが表示され、リスト内を右クリックするとリスト関連のオプションが表示されます。既定では、エディターを右クリックしたときに独自のコンテキストメニューを使用します。(Firefox のスペルチェッカーの推奨修正リストにアクセスするためなど) ブラウザーの既定のコンテキストメニューにアクセスするには、 <kbd>Shift</kbd> キーまたは <kbd>Control</kbd> キー (Mac OS X では <kbd>Command</kbd> キー) を押しながらクリックしてください。</p> + +<p>編集ボックスで作業するときは、<a href="/ja/docs/MDN/Contribute/Editor/Keyboard_shortcuts">キーボードショートカット</a>を使用できます。</p> + +<h2 id="Revision_comment" name="Revision_comment">リビジョンコメント</h2> + +<p>記事を編集した後、リビジョン (変更) にコメントを追加することを強く推奨します。これはページのリビジョン履歴に表示され、同様にあなたの<a href="/ja/dashboards/revisions">リビジョンダッシュボード</a>にも表示されます。これは作業を後でレビューする可能性がある人に、自分の変更の説明や正当化をするのに有用です。リビジョンコメントを追加するには、ページ最上部か最下部の<strong>公開</strong>ボタンを押す前に、リビジョンのコメントボックスにコメントを入力するだけです。</p> + +<p>これが役立つ理由がいくつかあります。</p> + +<ul> + <li>変更の理由が分かりにくい場合、メモによって他の人へ理由を説明できます。</li> + <li>変更が技術的に複雑な場合、その背景にある論理を他の編集者に説明することができます。例えば、他の編集者が詳細情報を参照することができるように、バグ番号を含めることができます。</li> + <li>変更が大量のコンテンツを削除するためのものであった場合、削除の正当性を主張できます (例えば "記事Xにコンテンツを移動した")</li> +</ul> + +<h2 id="Review_requests" name="Review_requests">レビュー要求</h2> + +<p>MDN コミュニティは MDN のコンテンツの監視や品質の向上の為に、<strong>レビュー</strong>を使用しています。これは記事にフラグを設定することで動作し、この記事がレビューを必要としているということを知らせます。<a href="/ja/docs/MDN/Contribute/Howto/Do_a_technical_review">技術レビュー</a>や<a href="/ja/docs/MDN/Contribute/Howto/Do_an_editorial_review">編集レビュー</a>については、 <a href="/ja/docs/MDN/Contribute/Howto">How to</a> ガイドで知ることができます。</p> + +<p>作業している記事にレビューを求めるには、必要なレビューの隣のチェックボックスをオンにします。技術レビューは技術的なものがどのように動作するのかの説明を変更した場合に要求するべきであり、編集レビューは変更を行い、誰かに記述やスタイルの選択についてレビューしてほしい時に要求するのが良い考えでしょう。</p> + +<p>レビューのチェックボックスを選択して、記事が<a href="/ja/docs/needs-review/technical">技術レビュー待ち</a>や<a href="/ja/docs/needs-review/editorial">編集レビュー待ち</a>のリストに追加されても、誰かが記事を直ちにレビューしてくれる保証はありません。技術レビューについては、関連する技術領域の<a href="/ja/docs/MDN/Community/Roles/Subject-matter_experts">主題のエキスパート</a>に直接連絡を取るのが良いでしょう。編集レビューについては、 <a href="https://discourse.mozilla.org/c/mdn">MDN discussion forum</a> (英語) に投稿して、誰かに変更をレビューするよう求めることができます。</p> + +<p>レビューの要求を確定するには、チェックを入れた後に必ず<strong>公開</strong>ボタンのどれかを押してください。</p> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li><a href="https://docs.ckeditor.com/">CKEditor User's Guide</a></li> +</ul> + +<h6 id="EditorGuideQuicklinks">{{EditorGuideQuicklinks}}</h6> diff --git a/files/ja/mdn/editor/basics/page_controls/index.html b/files/ja/mdn/editor/basics/page_controls/index.html new file mode 100644 index 0000000000..577473bc91 --- /dev/null +++ b/files/ja/mdn/editor/basics/page_controls/index.html @@ -0,0 +1,37 @@ +--- +title: MDN エディターページコントロール +slug: MDN/Editor/Basics/Page_controls +tags: + - Beginner + - Guide + - MDN Meta + - editor +translation_of: MDN/Editor/Basics/Page_controls +--- +<div>{{MDNSidebar}}</div><p>ページコントロールはページ全体に影響を与えるいくつかのボタンです。エディタービューの最上部と最下部の両方にあって、過度のスクロールを省きます。4つのページコントロールボタンがあります:</p> + +<div class="note"> +<p>If you try to save your page and your changes are rejected as invalid, but the content is in fact appropriate for MDN, you should <a href="mailto:mdn-spam-watch@mozilla.com?subject=MDN%3A%20Content%20Rejection%20Appeal&body=%3CDescribe%20the%20content%20you%20were%20trying%20to%20save%20and%20where%20you%20were%20trying%20to%20place%20it.%3E">email the writing team</a> for help getting your content posted.</p> +</div> + +<dl> + <dt>公開して編集を続行</dt> + <dd>Saves and publishes the page without closing the editor; this lets you periodically save your work, creating an entry in the page history that you can revert to if you need to, or in case you need to stop working and come back to it later. This option is not available when creating new pages. See <a href="/en-US/docs/MDN/Contribute/Editor/Basics#The_revision_comment_box">The revision comment box</a> to learn how to include a revision comment on your saved article.</dd> + <dt>公開</dt> + <dd>Saves and publishes the page and closes the editor, returning you to view the page in standard browsing mode. See <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Basics#The_revision_comment_box">The revision comment box</a> to learn how to include a revision comment on your saved article.</dd> + <dt>プレビュー</dt> + <dd>Opens a new tab or window showing the page as it exists in your private editor, but rendered as it would appear if you were browsing to it if it were public. This includes executing any <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Content/Macros">macros</a> and <a href="https://developer.mozilla.org/en-US/docs/MDN/Kuma/Introduction_to_KumaScript#Template_Syntax">templates</a> you use within the content. Note that your work is not saved yet when you use this option. This button lets you check, <span style="line-height: 1.5;">before your changes are made public, that</span> you haven't made any errors in your macros, templates, or formatting that may prevent the page from rendering correctly. If you do see scripting errors, refer to <a href="/en-US/docs/MDN/Contribute/Troubleshooting#Scripting_error_while_previewing_a_page">Troubleshooting scripting error while previewing a page</a>.</dd> + <dd> + <div class="warning" style="font-size: 14px;"> + <p><strong>Warning:</strong> Currently some macros and templates don't execute properly in Preview-mode, leaving the Preview page missing some of its content (such as sidebars), and thus with somewhat distorted page layout; i.e. not totally WYSIWYG. Further, if <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Basics#scayt">SCAYT</a> (Spell-Check As You Type) is enabled (and possibly if the page contains certain valid macros or templates), Preview mode may still give a scripting error.</p> + </div> + </dd> + <dt><br> + <a id="DiscardChanges" name="DiscardChanges">破棄</a></dt> + <dd>Cancels your edit, disposing of any changes you've made without saving them. You're returned to the page in standard browsing mode.</dd> + <dd> + <div class="warning" style="font-size: 14px;"> + <p><strong>Warning:</strong> Occasionally <strong>Discard</strong> can malfunction and start acting more like a partial "discard," undoing many of your changes without exiting the editor. If this happens to you, you should save, exit, and re-enter the editor.</p> + </div> + </dd> +</dl> diff --git a/files/ja/mdn/editor/basics/page_info/index.html b/files/ja/mdn/editor/basics/page_info/index.html new file mode 100644 index 0000000000..46b3cbbaba --- /dev/null +++ b/files/ja/mdn/editor/basics/page_info/index.html @@ -0,0 +1,48 @@ +--- +title: エディターUIのページ情報部 +slug: MDN/Editor/Basics/Page_info +tags: + - Beginner + - Guide + - MDN Meta + - editor +translation_of: MDN/Editor/Basics/Page_info +--- +<div>{{MDNSidebar}}</div><p>ページ情報部分にはページの情報を含みますが、追加の情報を拡張することも出来ます。</p> + +<p>このページは英語版のUIを説明しています</p> + +<h2 id="既存のページ">既存のページ</h2> + +<p>既定では、既存のページを編集する時、ページタイトルを表示します。</p> + +<p><strong>Edit Page Title and Properties</strong> のリンクをクリックして、追加のページコントロールの表示を切り替えることができます。この表示は次のようなものです:</p> + +<p><img alt="Page info fields for an existing article" src="https://mdn.mozillademos.org/files/15263/Expanded-page-info.png" style="border-style: solid; border-width: 2px; height: 190px; width: 751px;"></p> + +<p>この表示は次の設定を変更できます:</p> + +<dl> + <dt>Title</dt> + <dd>ブラウザーのタイトルバー (やタブバー) に表示されるタイトルと、記事の最上部とパンくずリストにあるページのタイトル。これはページの URL には影響しません。</dd> + <dt>TOC(目次)</dt> + <dd>記事の見出しレベルが、目次でどれだけ深くページに自動表示されるかを決めるレベル。既定では、見出しレベル<a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/h2" title="Heading elements implement six levels of document headings, <h1> is the most important and <h6> is the least. A heading element briefly describes the topic of the section it introduces. Heading information may be used by user agents, for example, to construct a table of contents for a document automatically."><code><h2></code></a> から<a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/h4" title="Heading elements implement six levels of document headings, <h1> is the most important and <h6> is the least. A heading element briefly describes the topic of the section it introduces. Heading information may be used by user agents, for example, to construct a table of contents for a document automatically."><code><h4></code></a> が目次となり、よって目次は3段階の深さになります。しかし、これをどのようにも設定できて、"No TOC" (目次を全く表示しない、例えばランディングページのように) でも、目次を全レベル表示するようにもできます。</dd> + <dt>Rendering max age</dt> + <dd>このページが自動的に再レンダリングされる頻度を決めます。大半の場合において、この設定はゼロのままにします。</dd> + <dt>Lookup</dt> + <dd>ローカライズされたページでは、この項目はページの正統版から「みなしご」になったページを再度関連付けるのに役立ちます。英語が MDN ではデファクトの正統な言語であるため、英語のページでは役立ちません。</dd> +</dl> + +<h2 id="新規のページ">新規のページ</h2> + +<p><a href="/MDN/Contribute/Howto/Create_and_edit_pages#Getting_page_creation_permission">ページ作成権限</a> を取得している場合、新規のページを作成できます。<a href="/ja/docs//MDN/Contribute/Howto/Create_and_edit_pages#Creating_a_new_page">ページを作成/編集する方法</a>を見て、ページ作成のさまざまなテクニックを見てください。新規のページでは、ページ情報欄はこのようになります:</p> + +<p><img alt="Page info fields for a new page" src="https://mdn.mozillademos.org/files/15265/New-page-info.png" style="border-style: solid; border-width: 2px; height: 214px; width: 739px;"></p> + +<p>ここに、<strong>Title(タイトル)</strong> と<strong>TOC(目次)</strong> フィールドを、既存ページと同様にセットできて、ページの <strong>Slug</strong> もセットできます。slug はページを表現する URL の最後の部分です。(<strong>Parent(親ページ)</strong> が読み取り専用項目として表示され、URL のサイトのルート以降の残りで表現します) テキスト項目に入力すると、Slug 項目はタイトルと同じテキストで、スペースをアンダースコアに置換しつつ自動入力されます。</p> + +<div class="note"> +<p>短い slug と詳しいタイトルに価値があります; 例えば、エディターページコントロールのタイトルは "MDN editor page controls" ですがその URL は <code>MDN/Contribute/Editor/Basics/Page_controls</code> であり、<code>Page_controls</code> がページを表現する slug です。</p> +</div> + +<p> </p> diff --git a/files/ja/mdn/editor/basics/tags/index.html b/files/ja/mdn/editor/basics/tags/index.html new file mode 100644 index 0000000000..0b9b11d04b --- /dev/null +++ b/files/ja/mdn/editor/basics/tags/index.html @@ -0,0 +1,41 @@ +--- +title: MDN エディターのタグ +slug: MDN/Editor/Basics/Tags +tags: + - Beginner + - Guide + - MDN Meta +translation_of: MDN/Editor/Basics/Tags +--- +<div>{{MDNSidebar}}</div><p>Page tags help categorize and organize information for searching and index pages, and they help identify pages that need special attention. Tags are also used to mark pages that are obsolete and may need to be deprecated or even deleted. It's incredibly useful to have good, clean tags on pages, so be sure to have good tags on articles you contribute to.</p> + +<p>The tag box is near the bottom of the editor page. It displays any existing tags on the page, as well as an empty box in which you can type a new tag:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15275/tag-area-3-tags.png" style="border-style: solid; border-width: 2px; height: 136px; width: 832px;"></p> + +<h2 id="タグを追加する">タグを追加する</h2> + +<p>To add a new tag, click in the "New tag" box and start typing:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15277/new-tag-before-enter.png" style="border-style: solid; border-width: 2px; height: 237px; width: 825px;"></p> + +<p>As you type, the editor displays existing tags that match the characters you have typed so far. You can save a few key strokes by selecting one of the displayed tags, or just use it as a reference to ensure that you spell the tag the same way as it appears on other pages.</p> + +<p>When you press <kbd>Enter</kbd> or <kbd>Tab</kbd> key (or comma), the new tag is committed to the list, and a new "New Tag" box appears:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15279/new-tag-after-enter.png" style="border-style: solid; border-width: 2px; height: 133px; width: 825px;"></p> + +<p>For a list of recommended tags, as well as a usage guide for specific tags, please see <a href="/en-US/docs/Project:MDN/Contributing/Tagging_standards">MDN tagging standards</a>.</p> + +<h2 id="タグを削除する">タグを削除する</h2> + +<p>There are two ways to remove a tag:</p> + +<ul> + <li>Click on the "x" icon next to its name in its button.</li> + <li>If it is the last tag in the list, click in the "New Tag" box and press the <kbd>Backspace</kbd> key on your keyboard.</li> +</ul> + +<h2 id="変更をコミットする">変更をコミットする</h2> + +<p>Your changes are not saved until you click one of the <strong>Publish</strong> buttons.</p> diff --git a/files/ja/mdn/editor/basics/toolbar/index.html b/files/ja/mdn/editor/basics/toolbar/index.html new file mode 100644 index 0000000000..6076640c10 --- /dev/null +++ b/files/ja/mdn/editor/basics/toolbar/index.html @@ -0,0 +1,257 @@ +--- +title: MDN エディターのツールバー +slug: MDN/Editor/Basics/Toolbar +tags: + - Beginner + - MDN Meta + - Reference + - editor +translation_of: MDN/Editor/Basics/Toolbar +--- +<div>{{MDNSidebar}}</div><p class="summary">エディターのツールバーは、作業時に記事の見た目や流れを調整する機能を提供します。この記事ではツールバーの各コントロールについて記述します。</p> + +<p>2行のボタンがあり、3列目はあなたがどこにいるかを導くHTML要素があります。下記のスクリーンショットでは、例えば、トップレベルの <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p" title="The HTML <p> element represents a paragraph of text."><code><p></code></a> ブロックを編集しています。</p> + +<p><img alt="Screenshot of the toolbar, with labels for the button groups" src="https://mdn.mozillademos.org/files/15269/toolbar-labeled.png" style="border-style: solid; border-width: 2px; float: right; height: 142px; width: 725px;">ツールバーボタンは9つのグループに別れます。それぞれ見ていきましょう; 各グループのボタンを左から順に詳しく見ていきます。</p> + +<ul> + <li><a href="#Document_group">Document</a></li> + <li><a href="#Edit_functions_group">Edit functions</a></li> + <li><a href="#Text_processing_group">Text processing</a></li> + <li><a href="#Display_group">Display</a></li> + <li><a href="#Inline_styles_group">Inline styles</a></li> + <li><a href="#Hyperlinking_group">Hyperlinking</a></li> + <li><a href="#Custom_styles_group">Custom styles</a></li> + <li><a href="#Blocks_group">Blocks</a></li> + <li><a href="#Lists_and_flow_group">Lists and flow</a></li> + <li><a href="#Media_group">Media</a></li> +</ul> + +<h2 id="Document_group" name="Document_group">ドキュメント(Document)グループ</h2> + +<p>ドキュメントグループはドキュメントレベルの操作オプションを提供します。</p> + +<dl> + <dt>ソース</dt> + <dd>The <strong>Source</strong> button lets you toggle between editing using the WYSIWYG interface and editing in raw HTML source mode. We <em>strongly</em> request that you try to avoid using source mode, as it's very easy to wind up with content that doesn't match our style guide or, worse, doesn't work right at all. Currently, though, the editor has some quirks that make it impossible to do certain things without resorting to source mode. See <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Source_mode">Using source mode in the MDN editor</a> for details on how to use source mode and the dos and don'ts involved.</dd> + <dt>公開</dt> + <dd>メインの <strong>公開</strong> ボタンと同様</dd> +</dl> + +<div class="note"> +<p>If you try to save your edit and your changes are rejected as invalid, but the content is in fact appropriate for MDN, you should <a href="mailto:mdn-spam-watch@mozilla.com?subject=MDN%3A%20Content%20Rejection%20Appeal&body=%3CDescribe%20the%20content%20you%20were%20trying%20to%20save%20and%20where%20you%20were%20trying%20to%20place%20it.%3E">email the writing team</a> for help getting your content posted.</p> +</div> + +<dl> + <dt>プレビュー</dt> + <dd>メインの <strong>プレビュー</strong> ボタンと同様</dd> +</dl> + +<h2 id="Edit_functions" name="Edit_functions">編集機能(Edit functions)グループ</h2> + +<p>編集機能はよくあるアプリケーションの<strong>編集</strong>メニューの対応オプションに似ています。</p> + +<dl> + <dt>貼り付け</dt> + <dd>システムクリップボードの中身をエディターペインに貼り付ける</dd> + <dt>プレーンテキストとして貼り付け</dt> + <dd>テキスト貼り付けのダイアログを表示する; テキストは全てスタイリングがはがされ、その結果気づかずに望まないスタイリングをサイトのコンテンツに入れることがなくなります。テキストを貼り付けたら、(追加で) 変更もできて、次にボタンをクリックして作業中の記事に挿入します。</dd> + <dd> + <div class="note"> + <p>When pasting content into MDN, please be aware that, if pasting styled content (including, for example, syntax highlighting in code being copied from another site), you may be bringing along unwanted and unneeded additional styles or classes. Please be careful not to do this; if necessary, review your edit in source mode to remove these unnecessary styles and classes (or check it before pasting, or use the "Paste as plain text" option instead).</p> + </div> + </dd> + <dt>元に戻す</dt> + <dd>最後の操作を元に戻します</dd> + <dt>やり直す</dt> + <dd>最後にもとに戻した操作をやり直します</dd> +</dl> + +<h2 id="Text_processing" name="Text_processing">テキスト処理(Text processing)グループ</h2> + +<p>テキスト処理グループではテキスト操作のオプションを提供します。</p> + +<dl> + <dt>検索</dt> + <dd>Opens the <strong>Find</strong> dialog box in "Find" mode, which lets you search your document for a specified string.</dd> + <dt>置換</dt> + <dd>Opens the <strong>Find</strong> dialog box in "Find and replace" mode, allowing you to find strings and replace them with new ones.</dd> +</dl> + +<p>The <strong>Find</strong> and <strong>Replace</strong> buttons both take you to the same dialog box, which offers several configurable options for finding and optionally replacing text.</p> + +<dl> + <dt>スペルチェック</dt> + <dd>This button opens a menu with several items: + <dl> + <dt>Enable SCAYT/Disable SCAYT</dt> + <dd>Activates or deactivates Spell Check As You Type (SCAYT)</dd> + <dt>Options</dt> + <dd>If SCAYT is activated, this opens the SCAYT dialog box to the tab containing options you can configure for SCAYT.</dd> + <dt>Languages</dt> + <dd>If SCAYT is activated, this opens the SCAYT dialog box to the Languages tab, where you can select what language to use for spell-checking dictionary.</dd> + <dt>Dictionaries</dt> + <dd>If SCAYT is activated, this opens the SCAYT dialog box to the Dictionaries tab, where you can specify a personal dictionary to use with SCAYT.</dd> + <dt>About SCAYT</dt> + <dd>If SCAYT is activated, this opens the SCAYT dialog box to the About tab.</dd> + <dt>Check Spelling</dt> + <dd>This opens a Spell Checker dialog box, in which you can check spelling in batch mode on an entire document. You can use the Grammar tab to check for grammar mistakes, or use the Thesaurus tab to search for synonyms of words in the document.</dd> + </dl> + </dd> +</dl> + +<h2 id="Display" name="Display">表示(Display)グループ</h2> + +<p>表示グループはエディター画面の表示に影響するオプションを提供します。</p> + +<dl> + <dt>最大化</dt> + <dd>このボタンは、エディターインターフェイス(つまり、ツールバーと編集ボックス) をブラウザーウィンドウ全体に拡大し、記述スペースを最大限使えます。</dd> + <dt>ブロック表示</dt> + <dd>このボタンは、文書内のブロック要素の外枠を出現させます。これはソースモードを使わずに文書構造を手軽にチェックする方法です。</dd> +</dl> + +<h2 id="インラインスタイルInline_stylesグループ">インラインスタイル(Inline styles)グループ</h2> + +<p>インラインスタイルグループは、テキストの塊に対して適用する、よくあるインラインスタイルを含みます。</p> + +<dl> + <dt>太字</dt> + <dd>Toggles <strong>boldface</strong> text mode. It creates a {{htmlelement("strong")}} element.</dd> + <dt>斜体</dt> + <dd>Toggles <em>italic</em> text mode. It creates an {{htmlelement("em")}} element.</dd> + <dt>下線</dt> + <dd>Toggles <u>underlined</u> text mode. It creates a {{htmlelement("u")}} element.</dd> + <dt>打ち消し線</dt> + <dd>Toggles <s>strikethrough</s> mode. It creates an {{htmlelement("s")}} element.</dd> + <dt>下付き</dt> + <dd>Toggles subscript mode. It creates a {{htmlelement("sub")}} element.</dd> + <dt>上付き</dt> + <dd>Toggles superscript mode. It creates a {{htmlelement("sup")}} element. Please note that we don't use footnotes on MDN, so you should rarely if ever need this button.</dd> + <dt>書式を解除</dt> + <dd>Removes the current inline styles from the selection.</dd> + <dt>コード</dt> + <dd>Toggles <code>code </code>mode. It creates a {{htmlelement("code")}} element. This is used for inline presentation of variable names, function names, object names, filenames, and so forth.</dd> +</dl> + +<h2 id="Hyperlinking" name="Hyperlinking">ハイパーリンク(Hyperlinking)グループ</h2> + +<p>ハイパーリンクグループは、ハイパーリンクに関するオプションを提供します。</p> + +<dl> + <dt>リンク挿入/編集</dt> + <dd>Creates a new link. This button opens the link editor dialog, which is covered in <a href="/en-US/docs/MDN/Contribute/Editor/Links#Using_the_toolbar">Links using the toolbar</a>.</dd> + <dt>リンクを削除</dt> + <dd>Removes the link at the insertion point.</dd> + <dt>アンカー挿入/編集</dt> + <dd>Creates an anchor at the insertion point. Note that you don't need an anchor to link to a heading; the MDN editor automatically creates an <code>{{htmlattrxref("id")}}</code> for each heading that is the same as the heading text, with spaces replaced by underscores. For example, the heading of this section has an <code>id</code> whose value is <code>Hyperlinking_group</code>.</dd> + <dt>リダイレクトを作成</dt> + <dd>Inserts a redirect from this page to another. See <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Redirects#Creating_redirects">Creating redirects</a> for further information.</dd> +</dl> + +<h2 id="Custom_styles" name="Custom_styles">カスタムスタイル(Custom styles)グループ</h2> + +<p><strong>Styles</strong> ボタンは、特別なフォーマットオプションの選択を提供するドロップダウンメニューです。</p> + +<h3 id="Block_styles">Block styles</h3> + +<dl> + <dt>None</dt> + <dd>現ブロックの全てのスタイリングを削除します</dd> + <dt>Note box</dt> + <dd>下記のような註記のボックスを作ります。註記ボックスでは太字の "<strong>註記:</strong>" で開始します。</dd> +</dl> + +<div class="note"> +<p>This is a note box.</p> +</div> + +<dl> + <dt>Warning box</dt> + <dd>下記のような警告ボックスを作成します。太字の "<strong>警告:</strong>" で開始します。</dd> +</dl> + +<div class="warning"> +<p><strong>Warning:</strong> This is a warning box.</p> +</div> + +<dl> + <dt>Two columns</dt> + <dd>選択テキストや現ブロックのを1カラムから2カラムに、これをサポートするブラウザーでは、変更します。</dd> + <dt>Three columns</dt> + <dd>選択テキストや現ブロックのを1カラムから3カラムに、これをサポートするブラウザーでは、変更します。</dd> + <dt>Article summary</dt> + <dd>This style places its contents in a specially formatted call-out block that should contain a summary of the article. See the first paragraph of this article for an example.</dd> + <dt>Syntax box</dt> + <dd>Creates a syntax box, such as the one shown below. You need to use the "PRE" button as well, to create a <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/pre" title='The HTML &amp;amp;lt;pre> element represents preformatted text. Text within this element is typically displayed in a non-proportional ("monospace") font exactly as it is laid out in the file. Whitespace inside this element is displayed as typed.'><code><pre></code></a> block inside it. You probably won't see the yellow box until you do.</dd> + <dt>Hidden when reading</dt> + <dd>Creates a block that is visible only in edit mode, not when normally displayed. This is not the same as an HTML comment, which is visible only in source mode.</dd> +</dl> + +<h3 id="Inline_styles">Inline styles</h3> + +<dl> + <dt>SEO summary</dt> + <dd>This special style is used to indicate a sentence or two that should be used as the article's summary for SEO purposes. It's also used by macros that automatically construct landing pages. If you don't specify this, MDN automatically uses the first paragraph of your article, but sometimes that's not the optimal text (or it's too much text), so this lets you override that.</dd> +</dl> + +<h2 id="Blocks" name="Blocks">ブロック(Blocks)グループ</h2> + +<p>ブロックグループは、HTML標準や、Kuma 独自となる、その他のブロックスタイルを提供します。</p> + +<dl> + <dt>ブロック引用文</dt> + <dd>Inserts a blockquote. <strong>Please do not use this</strong>. Blockquotes are not part of our standard style guide, and this button will be removed in the near future.</dd> + <dt>Preformatted Text</dt> + <dd>Inserts a {{htmlelement("pre")}} block, or turns the current block into one. All code samples or examples of text output to a terminal should be in one of these blocks.</dd> + <dt>Headings</dt> + <dd>The heading buttons let you insert a heading. Click one of these buttons to create a new heading at the corresponding depth. By default, H2 through H4 are included in the table of contents, but you can change this, as described in the <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Basics/Page_info">page info box</a>.</dd> + <dt>構文ハイライター</dt> + <dd>The syntax highlighter lets you choose a language for which to apply syntax highlighting to the {{htmlelement("pre")}} (preformatted text) block; if you're not already in such a block, this will create one for you. Choose the language used in the block, and it will be highlighted appropriately.</dd> + <dt>コードサンプルテンプレートを挿入</dt> + <dd>This button is used by the live sample system to help you quickly insert a new live sample. You don't need to use it, but it's there for convenience. See <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Live_samples#Using_the_live_sample_system">Using the live sample system</a> for details on using this and other live sample features.</dd> + <dt>コードサンプルの iFrame を挿入</dt> + <dd>Inserts into the document the appropriate macro to display a given live sample. See <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Live_samples#Using_the_live_sample_system">Using the live sample system</a> for details on using this and other live sample features.</dd> +</dl> + +<h2 id="Lists_and_flow_group">Lists and flow group</h2> + +<p>このブロック構造グループは、標準のブロック構造を作成、編集するオプションを提供します。</p> + +<dl> + <dt>番号つきリスト</dt> + <dd>Creates or removes a numbered list from your article. Once you're working in a numbered list, each time you press return, you will start a new bullet. The <kbd>Tab</kbd> key can be used to indent a level, and <kbd>Shift</kbd> + <kbd>Tab</kbd> will outdent a level. Pressing return on an empty bullet will exit numbered list mode. Right-clicking the list offers the option to open the properties dialog for the list; the properties include the style of the numbers (numbers, letters, Roman numerals, etc, and what number to start with).</dd> + <dt>番号なしリスト</dt> + <dd>Creates or removes a bulleted list from your article. Once you're working in a bulleted list, each time you press return, you will start a new bullet. The <kbd>Tab</kbd> key can be used to indent a level, and <kbd>Shift</kbd> + <kbd>Tab</kbd> will outdent a level. Pressing return on an empty bullet will exit bullet list mode. Right-clicking on the list lets you choose to edit the list's properties (specifically, the shapes of the bullets).</dd> + <dt>Definition List</dt> + <dd>Creates a new definition list. Definition lists consist of a series of titles and definitions (this list you're reading right now is an example).</dd> + <dt>Definition Term</dt> + <dd>Creates a new term block in a definition list. If you're not already editing a definition list, a new one is created for you. Pressing return after entering a definition title automatically starts you editing a definition description.</dd> + <dt>Definition Value</dt> + <dd>Creates a new value block in a definition list. Pressing return on a description line automatically starts a new title. Pressing return twice will exit definition list mode.</dd> + <dt>インデント解除</dt> + <dd>Shifts the indentation level to the left once; this is the same as pressing <kbd>Shift</kbd> + <kbd>Tab</kbd> while in a list.</dd> + <dt>インデント</dt> + <dd>Shifts the indentation level to the right once; this is the same as pressing tab while in a list.</dd> + <dt>テキストの向き：左から右へ</dt> + <dd>Sets LTR as the current text typing direction. Used only when covering localization/internationalization topics. For example, if you are working in an Arabic document, you might use this to display some English text.</dd> + <dt>テキストの向き：右から左へ</dt> + <dd>Sets RTL as the current text typing direction. Used only when covering localization/internationalization topics. For example, if you are working in an English text, you might use this to display some Arabic text.</dd> +</dl> + +<h2 id="Media" name="Media">メディア(Media)グループ</h2> + +<p>メディアグループはメディアを表示・フォーマットするオプションを提供します。</p> + +<dl> + <dt>イメージ</dt> + <dd>Inserts a new image into the article. See <a href="/en-US/docs/MDN/Contribute/Editor/Images">Images</a> for details on how to use this option.</dd> + <dt>表</dt> + <dd>Inserts a table into the article. See <a href="/en-US/docs/MDN/Contribute/Editor/Tables">Tables</a> for more information on tables in articles.</dd> + <dt>YouTube 動画を埋め込み</dt> + <dd>Opens a dialog box in which you can specify a YouTube URL. From this information it creates a call to the EmbedYouTube macro. This is a secure way to embed video content.</dd> + <dt>Insert MathML based on (La)TeX</dt> + <dd>Opens a dialog box in which you can insert code in TeX or LaTeX. This code will be converted into <a href="/en-US/docs/Web/MathML">MathML</a> and inserted into the document in a {{htmlelement("math")}} block.</dd> +</dl> + +<p> </p> diff --git a/files/ja/mdn/editor/images/index.html b/files/ja/mdn/editor/images/index.html new file mode 100644 index 0000000000..5efe16a213 --- /dev/null +++ b/files/ja/mdn/editor/images/index.html @@ -0,0 +1,70 @@ +--- +title: 画像 +slug: MDN/Editor/Images +tags: + - Guide + - MDN Meta +translation_of: MDN/Editor/Images +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">記事に画像を混ぜるのはしばしば便利です。画像は例えば、スクリーンショットや、レンダリングがどのようになるかの例や、プログラムフローのSVG図です。この記事ではMDNのコンテンツに画像を使う方法を記します。</span></p> + +<div class="note"><strong>Note: </strong>When uploading an image, please be sure to use an image optimization tool to make the file as small to download as possible. This improves page load time and helps MDN's performance overall. You may use your preferred tool, if you have one. Otherwise, we suggest <a href="https://tinypng.com/">TinyPNG</a>, a handy Web tool.</div> + +<p id="Adding_images_to_an_article">いったん画像をページに添付したら ({{SectionOnPage("/en-US/docs/MDN/Contribute/Editor/Basics", "The attachments box")}} を見てください)、記事内で使用できます。MDN上のどこの画像にもリンクできます。画像を挿入するには、ツールバーの "イメージ" ボタンを使用し、それはこのようなものです: <img alt="" src="https://mdn.mozillademos.org/files/5349/image-icon.png" style="height: 19px; width: 22px;"></p> + +<p>画像のプロパティダイアログが、次のように出てきます:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/5331/image-properties-empty.png" style="height: 617px; width: 483px;"></p> + +<p>3つのタブがあります。最初 (で最もよく使う) は画像情報タブです。残り2つはリンクと、高度な設定タブです。</p> + +<h2 id="画像情報">画像情報</h2> + +<p>ここにはたくさんのオプションがあります:</p> + +<dl> + <dt>添付ファイル</dt> + <dd>このポップアップメニューはページの添付ファイル一覧を表示します。現在の編集セッションでアップロードしたものか、既にページの他の場所で使われているものだけが表示されます。</dd> + <dt>URL</dt> + <dd>添付ファイル一覧にない画像を使いたい場合 (例えば、MDNの他の場所で使われているものや、以前の編集セッションでアップロードされたもの)、この欄にURLを入力できます。</dd> + <dt>代替テキスト</dt> + <dd>画像が表示されない場合に表示される代替テキスト。このテキストは、スクリーンリーダーでも使われるので、アクセシビリティのためにも、適切な記述を入れてください。</dd> + <dt>幅 / 高さ</dt> + <dd>記事に表示される画像の幅と高さをここで調整できます。デフォルトでは、比率がロックされていますが、ロックアイコンをクリックして解除できます。</dd> + <dt>枠線の幅</dt> + <dd>オプションとして、画像の周りに黒い枠線を指定できます。ここには 0 (や未入力のまま) または 1 を入れて<strong>ください</strong>、そうすると画像の背景が透明で、記事の背景から目立たせる場合に、枠線を使うかどうかの選択になります。</dd> + <dt>水平間隔 / 垂直間隔</dt> + <dd>これは、画像を囲む空白の長さを、水平/垂直それぞれ指定するものです。通常は、下記の行揃えオプションを使う場合にのみ必要となるでしょう。</dd> + <dt>行揃え</dt> + <dd>デフォルトでは、画像は独自ブロックに単独で表示されます。しかし、テキストをラップ可能にすることで、ここでは画像をフロートとして左/右寄せできます。めったにこうしません。つまり画像がとても小さく(またはとても幅が狭く縦が長い)て、その横に整形するのに十分な長さのテキストがある、特別な場合のみ使われます。少し判断が要ります。このオプションを使った場合、たぶんテキストと画像が近づき過ぎないように、水平間隔と垂直間隔をセットしたくなるでしょう。通常はそれぞれを6か8とするとうまくいきます。</dd> +</dl> + +<p>プレビューボックスは、今の設定で画像がどうなるかを例示します。</p> + +<h2 id="リンク">リンク</h2> + +<p>The Link options tab for images lets you set a URL to go to when the image is clicked on. This is most commonly used to simply link to a larger version of the image itself (by providing the same URL as in the Image Info tab). The Link panel looks like this:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/5333/image-properties-link.png" style="height: 525px; width: 479px;"></p> + +<p>Other than the URL field, in which you place the URL of the link's destination, you can set a target. However, <strong>please do not do so</strong>. We prefer all links to open in the same tab.</p> + +<h2 id="サポートされる画像の種類">サポートされる画像の種類</h2> + +<p>You may upload GIF, JPEG, and PNG images, as well as SVG diagrams. For screenshots, we prefer PNG, and we're trying to transition to using SVG for diagrams because they can be translated into other languages more easily than other image types.</p> + +<p>Photoshop files may also be uploaded. <strong>However</strong>, they may not be used as images inline in content. They are only available for download.</p> + +<h2 id="画像を削除変更する">画像を削除/変更する</h2> + +<p>To remove an image from the article, you can simply select it and press your delete key, or place the cursor after it and press delete.</p> + +<div class="note"> +<p><strong>Note:</strong> You cannot delete attachments on MDN; we will eventually have a mechanism for this, but at this time, they remain on the server for potential later re-use.</p> +</div> + +<p>You can also revise the image properties for an image by double-clicking it, or right-clicking on it and choosing "Image Properties" from the context menu that appears. This will present the same dialog as above.</p> + +<p>{{EditorGuideQuicklinks}}</p> diff --git a/files/ja/mdn/editor/index.html b/files/ja/mdn/editor/index.html new file mode 100644 index 0000000000..ab597839dc --- /dev/null +++ b/files/ja/mdn/editor/index.html @@ -0,0 +1,21 @@ +--- +title: MDN エディター UI のガイド +slug: MDN/Editor +tags: + - Documentation + - Guide + - Landing + - MDN + - MDN Meta + - ガイド +translation_of: MDN/Editor +--- +<div>{{MDNSidebar}}</div> + +<p class="summary"><span class="seoSummary">MDN Web Docs Wiki が提供する <abbr title="What You See Is What You Get">WYSIWYG</abbr> (what-you-see-is-what-you-get) エディターで、簡単に新しいコンテンツの協力ができます。 MDN エディターガイドでは、エディターの使い方とともに、あなたの生産性を改善する有用な特徴についての情報を提供します。編集や新規ページ作成をする前に、<a href="https://www.mozilla.org/ja/about/legal/terms/mozilla/">Mozilla ウェブサイトの利用規約</a>を読んで (そして従って) 下さい。</span></p> + +<p><a href="/ja/docs/MDN/Contribute/Content/Style_guide" title="MDN スタイルガイドを読む">MDN スタイルガイド</a>は、コンテンツそのものの書式やスタイルの作り方について、推奨する文法や記述の規則も含めて、情報を提供します。</p> + +<p>{{LandingPageListSubpages}}</p> + +<p>{{EditorGuideQuicklinks}}</p> diff --git a/files/ja/mdn/editor/keyboard_shortcuts/index.html b/files/ja/mdn/editor/keyboard_shortcuts/index.html new file mode 100644 index 0000000000..7d0926b4fa --- /dev/null +++ b/files/ja/mdn/editor/keyboard_shortcuts/index.html @@ -0,0 +1,141 @@ +--- +title: MDN エディターのショートカットキー +slug: MDN/Editor/Keyboard_shortcuts +tags: + - MDN Meta + - Reference + - Reference + - editor + - エディター + - エディター +translation_of: MDN/Editor/Keyboard_shortcuts +--- +<p>作業中にキーボードから手を離さなくて済むように、多数の便利なキーボードショートカットが利用できます。ショートカットは Windows と Linux 用の一覧で、Mac では <kbd>Control</kbd> キーの代わりに <kbd>Command</kbd> キーを使用できます。</p> + +<table class="standard-table"> + <colgroup> + <col style="width: 15em;"> + </colgroup> + <tbody> + <tr> + <th>ショートカット</th> + <th>説明</th> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>A</kbd></td> + <td>全て選択</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>C</kbd></td> + <td>クリップボードにコピー</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>V</kbd></td> + <td>クリップボードから貼り付け</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd></td> + <td>クリップボードから整形されていないプレーンテキストとして貼り付け</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>X</kbd></td> + <td>カット</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Z</kbd></td> + <td>やり直し</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Y</kbd></td> + <td>再実行</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>K</kbd></td> + <td>リンクエディターを開く/新しいリンクを追加</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>K</kbd></td> + <td>現在のカーソル位置からリンクを削除する</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>B</kbd></td> + <td>太字</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>I</kbd></td> + <td>イタリック</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>O</kbd></td> + <td><code><code></code> スタイルをトグルする</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>O</kbd></td> + <td> + <p>ソース表示モードの切り替え</p> + + <div class="note">ソースモードでの編集は注意してください; コンテンツ標準に引き続き従う必要があります。詳しくは<a href="/ja/docs/MDN/Contribute/Editor/Source_mode">エディターのソースモードのガイド</a>を見て、ソースモードの使い方と、どの場面に使用すべき/でないのか、との両方を見てください。</div> + </td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>P</kbd></td> + <td>現在ブロックの <code><pre></code> スタイルのオン/オフをトグルする</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>U</kbd></td> + <td>下線</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>S</kbd></td> + <td>変更を保存してエディターを閉じる</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd></td> + <td>エディターを閉じないで変更を保存する</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>0</kbd></td> + <td>選択エリアのフォーマットを削除する ("O"の文字ではなくて、数字のゼロです).</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>2</kbd> から <kbd>Ctrl</kbd> + <kbd>6</kbd></td> + <td>2 から 6 で見出しをつける。レベル 1 の見出しは、記事の最上部に表示されるページタイトルに予約されている。</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>L</kbd></td> + <td>段落のフォーマットとして、黒丸リストと番号つきリストを切り替える。</td> + </tr> + <tr> + <td><kbd>Tab</kbd></td> + <td>インデントモードではインデントレベルを増やし、それ以外では 2 つのスペースをタブとして挿入する。テーブル内では、次のセルにカーソルを移動するか、次のセルがなければ新しい行を追加する。カーソルがページタイトルか見出しにある場合、次のパラグラフにジャンプする。</td> + </tr> + <tr> + <td><kbd>Shift</kbd> + <kbd>Tab</kbd></td> + <td>インデントモードではインデントを減らす。テーブル内では、前のセルにジャンプするか、前のセルがなければ新しい行を追加する。カーソルがページタイトルか見出しにある場合、次のパラグラフにジャンプする。</td> + </tr> + <tr> + <td><kbd>Shift</kbd> + <kbd>Space</kbd></td> + <td>ノーブレークスペース (<code>&nbsp;</code>) を挿入する。</td> + </tr> + <tr> + <td><kbd>Shift</kbd> + <kbd>Enter</kbd></td> + <td> + <p>現在のブロックを抜ける。例えば、<code><pre></code> ブロックを編集している場合、<kbd>Shift</kbd> + <kbd>Enter</kbd> でブロックを抜けて、記事の本文に戻る。</p> + + <div class="note style-wrap"> + <p>現在は実装されていません; {{bug('780055')}} を見てください。</p> + </div> + </td> + </tr> + </tbody> +</table> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Editor/Basics">エディターの UI 要素</a></li> + <li><a href="/ja/docs/MDN/Contribute">MDN に協力する</a></li> + <li><a href="/ja/docs/MDN/Getting_started">MDN を始めよう</a></li> +</ul> + +<div>{{MDNSidebar}}</div> diff --git a/files/ja/mdn/editor/links/index.html b/files/ja/mdn/editor/links/index.html new file mode 100644 index 0000000000..87fff92133 --- /dev/null +++ b/files/ja/mdn/editor/links/index.html @@ -0,0 +1,182 @@ +--- +title: リンク +slug: MDN/Editor/Links +tags: + - Guide + - MDN Meta + - editor + - ガイド + - 編集者 +translation_of: MDN/Editor/Links +--- +<div>{{MDNSidebar}}</div> + +<p id="Creating_and_editing_links"><span class="seoSummary">多くの文書間だけでなく、単一の文書内でも、リンクは wiki において重大な構成要素であり、 MDN はそれにかなり依存しています。運の良いことに、リンクは作成が簡単でもありますが、更にたくさんの作り方があります!</span></p> + +<div class="blockIndicator note"> +<p><strong>メモ:</strong> 特に<a href="/ja/docs/MDN/Contribute/Guidelines/Writing_style_guide#Links">リンクの推奨される方法</a>があります。これらは<a href="/ja/docs/MDN/Contribute/Guidelines/Writing_style_guide"> MDN 書式ガイド</a>で説明されています。</p> +</div> + +<h2 id="Using_the_toolbar" name="Using_the_toolbar">ツールバーの使用</h2> + +<p>リンクを作成するのに最も分かりやすい方法は、ツールバーの「リンク」ボタンをクリックするか、 <kbd>Ctl</kbd>+<kbd>K</kbd> (Mac では <kbd>Command</kbd>-<kbd>K</kbd>) を押してリンク作成することです。リンクボタンは <img alt="The link button (as of 2015-12-04)" src="https://mdn.mozillademos.org/files/12003/link-button.png" style="height: 16px; width: 16px;"> のような外見です。この機能を使用して、最初からリンクを作成したり、既存の選択したテキストにリンクを追加したりすることができます。</p> + +<h3 id="Creating_a_link_from_scratch" name="Creating_a_link_from_scratch">最初からリンクを作成する</h3> + +<p>リンクボタンをクリックすると、次のようなハイパーリンクエディターのダイアログが表示されます。</p> + +<p><img alt="Screenshot of the Link dialog box, showing the Link Info tab" src="https://mdn.mozillademos.org/files/15289/link-info.png" style="border-style: solid; border-width: 1px; height: 320px; width: 335px;"></p> + +<p>ここで新規のリンクを作ることができます。ダイアログ内のコントロールは次の通りです。</p> + +<dl> + <dt>リンクタイプ</dt> + <dd>作成しているリンクのタイプ。既定は「URL」で、 MDN またはサイト外のウェブ上のどこかの URL です。「ページ内のアンカー」または「E-Mail」を選択することもできます。「ページ内のアンカー」を使用すると、ツールバーの<strong>アンカー</strong>ボタンを使用して以前に挿入したアンカーにリンクすることができます。「E-Mail」を使用すると、受信者の電子メールアドレス、件名、および既定のメッセージ内容を入力して <code>mailto:</code> URL を設定できます。ほとんどの場合は「URL」を使用します。</dd> + <dt>記事タイトル検索/リンクテキスト</dt> + <dd>このフィールドには2つの目的があります。まず、リンク先として使用される特定のテキストを指定します (または、ダイアログボックスを開く前にドキュメント内のテキストを選択していた場合、そのテキストがリンク先として表示されます)。ここに入力されたテキストは、入力した内容と一致する MDN 上の記事を検索して、可能な宛先ページを見つけるために使用されます。たとえば、このボックスに "Array" と入力すると、次のように表示されます。<br> + <img alt='Screenshot of the Link dialog box, showing a lookup menu for the text "Array"' src="https://mdn.mozillademos.org/files/15291/link%20dialog%20with%20lookup%20menu.png" style="border-style: solid; border-width: 1px; height: 388px; width: 496px;"></dd> +</dl> + +<dl> + <dd>ここに、入力したテキストがタイトルに含まれる MDN のすべてのページのリストが表示されます。リストをスクロールしてそれらのページの1つを選択するか、入力を続けてリストを絞り込むことができます。一覧の項目にはロケールが表示されます(この場合、"[en-US]")。そのテキストはリンク先のテキストでは使用されませんが、編集中のロケールと同じロケールの記事にリンクしていることを確認するのに役立ちます。</dd> + <dt>添付ファイル</dt> + <dd>また、このリストから添付ファイルを選択して、リンクを現在のページに添付されているファイルのいずれかへのリンクにすることもできます。これはコードサンプルなどをダウンロードするためのリンクを提供する素晴らしい方法です。</dd> + <dt>URL</dt> + <dd>最後に、 URL フィールドで実際に URL を直接入力できます。「<strong>記事タイトル検索</strong>」または「<strong>添付ファイル</strong>」メニューで選択した URL も表示されます。一般的な方法は、 MDN の他の場所で作業しているページに URL を貼り付けることです。 MDN の別の記事にリンクする場合は、 URL の先頭からドメイン名 ("https://developer.mozilla.org") を削除してください。</dd> +</dl> + +<p>リンクを設定したら、 <strong>OK</strong> ボタンをクリックしてそれを挿入します。</p> + +<div class="note"> +<p>注意していると、ハイパーリンクエディターダイアログに2番目のタブ (<strong>Advanced</strong>、高度な設定) があることがわかります。少なくとも現時点では、定期的に使用することをお勧めするオプションはありません。将来はリンクのための代替スタイルが存在する可能性がありますが、新しいツールバーウィジェットを追加して、それらの機能が利用可能になったらそれを使用する可能性があります。</p> +</div> + +<h3 id="Linking_existing_text" name="Linking_existing_text">既存テキストのリンク</h3> + +<p>既存のテキストをリンクにする場合は、プロセスをいくらか簡略化することができます。ハイパーリンクエディタを開く前に、リンクにするテキストを選択します。<strong>記事タイトル検索/リンクテキスト</strong>フィールドに選択したテキストがあらかじめ入力されます。たとえば、次のテキストがあるとします。</p> + +<blockquote> +<p>このプロジェクトの作業中に JavaScript 配列を使用すると便利です。</p> +</blockquote> + +<p>"arrays" を適切なコンテンツへのリンクにする必要があります。その単語を選択してリンクエディタを起動するだけです。前のケースと同様の事前入力済みのダイアログが表示されます。提案された記事の上にマウスを「ホバーする」と、相対スラグ (<code>developer.mozilla.org</code>を基準にした相対 URL) が表示され、その場所と記事の種類をより正確に把握できます。</p> + +<p><img alt="ルックアップメニューとURLのツールチップを表示する[Link]ダイアログボックスのスクリーンショット" src="/files/15293/Rollover%20of%20lookup%20menu.png" style="height: 387px; width: 493px;"></p> + +<p>ここでは一致候補として提案された記事のうち、"Arrays" は良い選択のように見えるので、それを選択することができます。これは自動的に URL フィールドに入力されるので、 <strong>OK</strong> をクリックすれば、テキストは次のようなリンクに変わります。</p> + +<blockquote> +<p>このプロジェクトの作業中に JavaScript の<a href="/ja/docs/Learn/JavaScript/First_steps/Arrays">配列</a>を使用すると便利です。</p> +</blockquote> + +<h2 id="Using_link_macros" name="Using_link_macros">リンクマクロを使う</h2> + +<p>MDN は<a href="/ja/docs/Project:MDN/Contributing/Editor_guide#Using_macros">マクロ</a>を大量に使用しており、与えられた用語に適切なコンテンツへのリンクを自動的に作成したり、スタイルガイドに従ってスタイルを設定したりしています。これを考えてみましょう。私たちのスタイルガイドは、API の用語名、HTML の要素と属性、 CSS のプロパティ、関数名などは {{HTMLElement("code")}} 要素でスタイリングする必要があることを示しています。それらはまた、通常は、 MDN の適切なページへのリンクにする必要があります。</p> + +<p>マクロを使用してこれらのリンクを作成するには少し慣れが必要ですが、多くの利点があります。</p> + +<ul> + <li>適切なスタイルがあなたのために適用されます</li> + <li>リンクがあなたのために作成されます — 将来 MDN がどのように構成されていくかを将来的に見直すことができます</li> + <li>適切なツールチップをあなたのために作成することもできます</li> +</ul> + +<p>これらのマクロはたくさんありますが、ここではそれらをすべて見ないようにします。代わりに、最も一般的なもののいくつかの特定の例を見ていきます。詳細なリストについては、 <a href="/ja/docs/Project:MDN/Contributing/Custom_macros">MDN のカスタムマクロ</a>ガイドの<a href="/ja/docs/Project:MDN/Contributing/Custom_macros#Creating_hyperlinks">ハイパーリンクの作成</a>を参照してください。これらのマクロのいずれかの <a href="/ja/docs/Project:Introduction_to_KumaScript">KumaScript</a> ソースコードをいつでも見ることができます。ほとんどは、どのように動作するのか、もしあれば、さまざまなパラメータが何であるかを説明するコメントを先頭に付けています。</p> + +<h3 id="Linking_to_documentation_for_APIs" name="Linking_to_documentation_for_APIs">API 文書へのリンク</h3> + +<p>API へのスタイル付きリンクを作成するために非常に役立つマクロが多数あります。ここには最も有用なものがいくつかあります。いずれの場合も、 (<code><code></code> スタイリングの自動追加を抑制するなど) 出力をより詳細に制御できるようにパラメータを追加することができます。下の各マクロ名をクリックすると、マクロコード自体を読むことができます。それらはすべて、どのように動作するのか、すべてのパラメータが何であるかを説明するコメントを先頭に付けています。</p> + +<dl> + <dt>{{TemplateLink("HTMLElement")}}</dt> + <dd>適切にスタイル付けされ、リンクされた HTML 要素の名前を挿入します。たとえば、 <code>\{{HTMLElement("table")}}</code> は {{HTMLElement("table")}} を生成します。</dd> + <dt>{{TemplateLink("cssxref")}}</dt> + <dd>CSS リファレンスの CSS プロパティ、 @-規則、セレクターの文書を挿入します。たとえば、 <code>\{{cssxref("background-color")}}</code> は {{cssxref("background-color")}} になります。</dd> + <dt>{{TemplateLink("domxref")}}</dt> + <dd>指定された API 用語の Web API リファレンスへのリンクを挿入します。たとえば、 <code>\{{domxref("window")}}</code> は {{domxref("window")}} を生成し、 <code>\{{domxref("window.scrollBy()")}}</code> は {{domxref("window.scrollBy()")}} を挿入します。テキストをオーバーライドする追加のパラメータを指定することもでき、 <code>\{{domxref("window.scrollBy", "scrollBy()")}}</code> は {{domxref("window.scrollBy", "scrollBy()")}} になります。</dd> + <dt>{{TemplateLink("SVGElement")}}</dt> + <dd>SVG 要素の名前を適切にスタイル付けしてリンクしたものを挿入します。たとえば、 <code>\{{SVGElement("circle")}}</code> は {{SVGElement("circle")}} を生成します。</dd> +</dl> + +<h3 id="同じ記事のセクションにリンクする">同じ記事のセクションにリンクする</h3> + +<p>同じ記事内のセクションにリンクするには、anch マクロを使用できます。構文は簡単です: <code>\{{anch("宛先セクション名")}}</code>。デフォルトでは、表示されているリンクテキストはそのセクションのタイトルですが、代わりに使用する代替テキストを示す2番目のオプションのパラメータを追加できます。いくつかの例を示します。</p> + +<ul> + <li><code>\{{anch("Using the toolbar")}}</code> は {{anch("Using the toolbar")}} のようになります。</li> + <li><code>\{{anch("Using the toolbar", "この記事の前半")}}</code> は {{anch("Using the toolbar", "この記事の前半")}} のようになります。</li> +</ul> + +<h3 id="バグにリンクする">バグにリンクする</h3> + +<p>{{TemplateLink("bug")}} マクロを使って、Mozilla の Bugzilla データベースのバグにリンクすることができます。このマクロは、リンクするバグ番号という単一のパラメータを受け入れます。たとえば、<code>\{{bug(765642)}}</code> は {{bug(765642)}} のようになります。</p> + +<p>同様に、他のブラウザーやウェブエンジンのバグへのリンクを作成することもできます。</p> + +<dl> + <dt>WebKit (Safari, etc.)</dt> + <dd>{{TemplateLink("WebkitBug")}}: <code>\{{webkitbug(31277)}}</code> は {{webkitbug(31277)}} を生成します。</dd> +</dl> + +<h3 id="Linking_to_RFCs" name="Linking_to_RFCs">RFCにリンクする</h3> + +<p>インターネットがコアレベルで動作する方法の多くは、 RFC に文書化されています。 {{TemplateLink("RFC")}} マクロを使用して簡単に RFC を参照できます。たとえば、 <code>\{{RFC(2616)}}</code> は {{RFC(2616)}} になります。オプションで、記事の選択されたテキスト部分、および/またはリンク先の仕様内のセクション番号の代わりに、使用する代替リンクテキストを提供することもできます。</p> + +<h3 id="Linking_to_information_about_XPCOM_interfaces" name="Linking_to_information_about_XPCOM_interfaces">XPCOM インターフェイスに関する情報へリンクする</h3> + +<div class="note"> +<p>MDN スタッフはもはや XPCOM の文書を積極的に管理していませんが、ボランティアの貢献は歓迎します。</p> +</div> + +<p>Mozilla の内部を文書化している場合は、 XPCOM のインタフェース文書へのリンクを簡単に作成できることが役立ちます。これにはいくつかのマクロが使われています。</p> + +<p>XPCOM インターフェイスの文書全体にリンクするための構文は、 <code>\{{interface("interfacename")}}</code> です。たとえば、次のように書くことができます。</p> + +<blockquote> +<p>When you need to parse or create URIs, the \{{interface("nsIIOService")}} interface can help.</p> +</blockquote> + +<p>結果は次のようになります。</p> + +<blockquote> +<p>When you need to parse or create URIs, the {{interface("nsIIOService")}} interface can help.</p> +</blockquote> + +<p>XPCOM インターフェイス上の特定のメソッドまたは属性に関する情報にリンクする必要がある場合は、 {{TemplateLink("ifmethod")}} および {{TemplateLink("ifattribute")}} マクロが必要です。これらは、インターフェイスの名前と、参照したいメソッドまたは属性の名前を引数として受け入れます。 {{TemplateLink("ifmethod")}} マクロは、メソッドの名前の後にスタイルガイドに必須のカッコを追加することによって特別なフォーマットを行うので、特に興味深いです。たとえば、 <code>\{{ifmethod("nsIIOService", "newURI")}}</code> の結果は {{ifmethod("nsIIOService", "newURI")}} になります。それは、あなたが将来的にスタイルガイドの変更の可能性から保護されているケースです！</p> + +<h3 id="Linking_to_Mozilla_preference_documentation" name="Linking_to_Mozilla_preference_documentation">Mozilla 設定文書へのリンク</h3> + +<p>Mozilla プリファレンスの名前を挿入し、<a href="/ja/docs/Mozilla/Preferences/Preference_reference">プリファレンスリファレンス</a>の対応するページにリンクするには、 {{TemplateLink("pref")}} マクロを使用します。これには1つのパラメータ、つまりリンク先のプリファレンスのフルネームが指定されています。たとえば、 <code>\{{pref("javascript.options.showInConsole")}}</code> を使用すると、 {{pref("javascript.options.showInConsole")}} を作成できます。</p> + +<h3 id="Linking_to_a_Mozilla_source_file" name="Linking_to_a_Mozilla_source_file">Mozilla ソースファイルへリンクする</h3> + +<p>source マクロを使用して、 Mozilla のソースツリー内のファイルにリンクすることができます (おそらくこれは頻繁ではありません)。ファイルの完全な URL を指定する代わりに、単に <code>/source/</code> ディレクトリを基準にしたパスを指定することができます。例: <code>\{{source("browser/Makefile.in")}}</code> は {{source("browser/Makefile.in")}} というリンクを生成します。</p> + +<p>オプションで、リンクに使用する代替テキストを指定することもできます。たとえば、 <code>\{{source("browser/Makefile.in", "ブラウザーの makefile")}}</code> を使用すると、 {{source("browser/Makefile.in", "ブラウザーの makefile")}} のような結果になります。</p> + +<div class="note"> +<p>マクロの使用方法について詳しく知りたい場合は、 {{anch("Using macros")}} のドキュメントを参照してください。また、マクロシステムの詳細については、 <a href="/ja/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript</a> のドキュメントを参照してください。</p> +</div> + +<h2 id="Linking_to_recommended_content" name="Linking_to_recommended_content">推奨コンテンツのリンク</h2> + +<p>関連ページやその他のお勧め資料のリストを作成する場合は、サイドバーにクイックリンクボックスを作成してください。このメカニズムは、記事の末尾にある古い「関連情報」の見出しを置き換えるものです。クイックリンクボックスの作成方法の詳細については、<a href="/ja/docs/MDN/Contribute/Structures/Quicklinks">クイックリンク</a>を参照してください。</p> + +<h2 id="URL_schemes" name="URL_schemes">URL スキーム</h2> + +<p>セキュリティ上の理由から、作成するのは以下のスキームを使用するリンクのみにしてください。</p> + +<ul> + <li><code>http://</code></li> + <li><code>https://</code></li> + <li><code>ftp://</code></li> + <li><code>mailto:</code></li> +</ul> + +<p>他のものは動作するかもしれないし、動作しないかもしれませんが、対応しておらず、おそらく編集スタッフによって削除されます。</p> + +<div class="note"> +<p><code>about:</code> や <code>chrome:</code> のような特別な URL スキームは、 Firefox、 Google Chrome、その他のブラウザーで、設定、デバッグ情報などの特別なコンテンツへのアクセスを提供するために使用されます。これらのリンクは記事のコンテンツからは機能しませんので、 MDN の記事内でこれらのスキームを使用してリンクを作成しないでください。同様のことは <code>javascript:</code> と <code>jar:</code> スキームにも適用され、これらはセキュリティ上の予防策から、最新のブラウザーではブロックされています。</p> +</div> + +<p>{{EditorGuideQuicklinks}}</p> diff --git a/files/ja/mdn/editor/redirects/index.html b/files/ja/mdn/editor/redirects/index.html new file mode 100644 index 0000000000..80a1d7268b --- /dev/null +++ b/files/ja/mdn/editor/redirects/index.html @@ -0,0 +1,29 @@ +--- +title: リダイレクト +slug: MDN/Editor/Redirects +tags: + - Guide + - MDN Meta +translation_of: MDN/Editor/Redirects +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">時々、単純にほかのページやほかのセクションへリダイレクトするためのページが必要なことがあります。この記事ではリダイレクトについて説明します。</span></p> + +<h2 id="Creating_a_redirect" name="Creating_a_redirect">リダイレクトを作成する</h2> + +<p>たとえば、あるページを作成した後にほかのページにマージした場合など、リダイレクトは必要になってくるでしょう。リダイレクトを作成するには、単純にこのような <img alt="" src="https://mdn.mozillademos.org/files/5131/redirect.png" style="height: 17px; width: 17px;"> ツールバー上のリダイレクトボタンをクリックするだけです。</p> + +<p>そうすると、転送先の URL と名前を聞くダイアログボックスが表示されます。名前はそれほど重要ではありません。リダイレクトページ自体を見てどこのページへリダイレクトしているかを知りたいときにだけ利用します。URL は "/en-US/docs/foo" のように完全なパスである必要があります。相対 URL は動作しません。しかし、"/destination/url/here#section_name" のように、ハッシュマーク("#") 文字を含んだターゲットを使って、セクションを指定することが可能です。これでターゲットページのセクションへ直接ユーザーをリダイレクトさせることができます。</p> + +<p>リダイレクトページの内容は、リダイレクト指示のみとするべきです。それ以外の内容はリダイレクトを作成する前に、すべて新しいページへ移してください。また、オリジナルページのあらゆるレビューフラグをクリアしておき、要レビューの一覧に不思議なエントリーがあることを避けるようにします。</p> + +<div class="note"> +<p><strong>注:</strong> 最も重要なことは、リダイレクトページからすべてのタグを削除することです。そうしないと、リダイレクトページは (同じタグを持っていると仮定して) 目的のページと一緒に検索結果に表示され、読者を混乱させ、検索結果ページの貴重なスペースを使ってしまいます。また、 SEO にも悪影響を及ぼす可能性があります。</p> +</div> + +<h2 id="When_deleting_pages" name="When_deleting_pages">ページを削除するとき</h2> + +<p>ページの削除を依頼する前に、MDN 上のほかのページにリダイレクトをすべきではないか考えてください。もしユーザーが古いリンクからこのページに来た場合には、404("page not found") エラーを返すよりも正しいページへリダイレクトさせた方がよいです。ページの完全な削除は最終手段です。スパムやその他まったく適切でない内容に対処するための手段として予約されたものです。</p> + +<p>{{EditorGuideQuicklinks}}</p> diff --git a/files/ja/mdn/editor/source_mode/index.html b/files/ja/mdn/editor/source_mode/index.html new file mode 100644 index 0000000000..b78db66714 --- /dev/null +++ b/files/ja/mdn/editor/source_mode/index.html @@ -0,0 +1,137 @@ +--- +title: ソースモード +slug: MDN/Editor/Source_mode +tags: + - Guide + - Intermediate + - MDN Meta + - editor + - ガイド +translation_of: MDN/Editor/Source_mode +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">MDN のエディターには、ソース編集モードへ切り替えられる目立つボタンがあります。このモードでは、編集している本文の基礎となる HTML を見ることができます。<span class="seoSummary">このガイドでは MDN の wiki コンテンツのソース編集モードで<strong>何ができるか</strong>、これで何を<strong>すべき</strong>か、また最も重要なこととして何を<strong>すべきでない</strong>のかを理解するのに役立ちます。 </span></p> + +<div class="blockIndicator warning"> +<p>ソースモードを使用することを考える前に、使用しないことを私たちが<em>強く</em>主張していることにご注意ください。やっていることがスタイルガイドに合わせるための単純なことでない限り (残念ながらまだソースモードでないと作成できないものが必要とされています)、ソースモードを使用する必要はないはずです。下記の{{anch("Warnings and caveats", "警告")}}をご覧ください。</p> +</div> + +<h2 id="Accessing_source_mode" name="Accessing_source_mode">ソースモードにアクセスする</h2> + +<p>ソースモードに移るのは簡単です。エディターツールバーの左上隅にある<strong>ソース</strong>ボタンをクリックしてください。</p> + +<p><img alt="ソースモードボタンが強調表示されたエディタツールバーの部分的なスクリーンショット" src="https://mdn.mozillademos.org/files/15295/Source%20mode%20button.png" style="height: 98px; width: 267px;"></p> + +<p>整形や画像などによって、ソースは WYSIWYG コンテンツより (縦方向に) 短く、ソースを<a href="/ja/docs/MDN/Contribute/Editor/Edit_box">編集ボックス</a>内で見つけるのに上にスクロールしないといけないことがよくあります。</p> + +<h2 id="Warnings_and_caveats" name="Warnings_and_caveats">警告と抗議</h2> + +<p>上述の通り、ソースモードを使う必要があることは滅多にありません。ソースをいじらないとできないことは少ししかありません。最終的には編集インターフェイスがこれを扱えるように更新されるでしょう。</p> + +<p><a href="/ja/docs/MDN/Contribute">MDN 貢献者ガイド</a>のどこにも記述されていないことはソースに追加しては<strong>いけません</strong>。つまり、</p> + +<ul> + <li>カスタムフォントやスタイルは禁止です。標準のルックアンドフィールにない場合、使わないでください。</li> + <li>特別な色の禁止。MDN の標準のルックアンドフィールにある、スタイルで提供されたものだけを使ってください</li> +</ul> + +<h2 id="Working_in_source_mode" name="Working_in_source_mode">ソースモードで作業する</h2> + +<p>ソースモードでは、 Wiki ページを構成する生の HTML を編集できます。エディターでの制約を受けなくなりますが、行ったすべての作業が<a href="/ja/docs/MDN/Contribute/Content/CSS_style_guide">スタイルガイド</a>に適合していて、安全かつ確実であることを確認してください。</p> + +<div class="blockIndicator note"> +<p>ソースモードでの編集時間を長くするのではなく、微修正のみを行うべきです。</p> +</div> + +<p>残念ながら、<kbd>Tab</kbd> キーは、ソースモードでは動作しません。 <kbd>Tab</kbd> キーを使用する場所では、半角スペースを 2 つ挿入してください。</p> + +<p>MDN が許可しない HTML 要素や属性を使用すると、ドキュメントが保存されるときに HTML から削除されます。加えて、ドキュメントの HTML は、適度に読みやすく一貫性を保つために再整形されます。</p> + +<h2 id="Legitimate_uses_for_source_mode" name="Legitimate_uses_for_source_mode">ソースモードを正しく使用する</h2> + +<p>MDN のスタイルガイドに従う唯一の方法は、いくつかの具体的な例でソースモードの使用を頼ることです。 このセクションでは、これらのケースと、他のものを壊すことなくこれらの機能を適切に実装する方法について説明します。</p> + +<h3 id="Highlighting_lines_in_sample_code" name="Highlighting_lines_in_sample_code">サンプルコードの行を強調表示する</h3> + +<p><a href="/ja/docs/MDN/Contribute/Editor/Basics/Toolbar#Blocks">ツールバーのブロックグループ</a>の <strong>PRE</strong> または <strong>構文ハイライター</strong> ボタンを使用して設定されたサンプルコードスニペットのブロック内で、特定のコード行に特別な注意を向けることができます。これを行う唯一の方法は、ソースモードを開いてコードを含む {{HTMLElement("pre")}} ブロックを探し、<code><pre></code> タグの {{HTMLAttrxRef("class")}} 属性を編集して、次のような <code>highlight</code> コンポーネントを組み込むことです。</p> + +<ul> + <li><code>highlight[<em>lineNum1</em>, <em>lineNum2</em>, ..., <em>lineNumN</em>]</code></li> + <li><code>highlight[<em>lineNumStart</em>-<em>lineNumEnd</em>, ..., <em>lineNumN</em>]</code></li> +</ul> + +<pre class="syntaxbox notranslate">"hightlight[" <a href="#highlight-line-number-list"><line-number-list></a> "]" + +<strong>Where:</strong> +<a id="highlight-line-number-list" name="highlight-line-number-list"><line-number-list></a> = <a href="/ja/docs/Web/CSS/Value_definition_syntax#Brackets">[</a> <a href="#highlight-line-number"><line-number></a> <a href="/ja/docs/Web/CSS/Value_definition_syntax#Single_bar">|</a> <a href="#highlight-line-range"><line-range></a> <a href="/ja/docs/Web/CSS/Value_definition_syntax#Brackets">]</a><a href="/ja/docs/Web/CSS/Value_definition_syntax#Hash_mark">#</a> +<a id="highlight-line-range" name="highlight-line-range"><line-range></a> = <a href="#highlight-line-number"><line-number></a> - <a href="#highlight-line-number"><line-number></a> +<a id="highlight-line-number" name="highlight-line-number"><line-number></a> = <number-token></pre> + +<p>たとえば、既存のタグが <code><pre class="brush: js"></code> で、4行目と7行目にハイライトを追加する場合は、それを <code><pre class="brush:js; highlight:[4,7]"></code> に変更します。</p> + +<p>より完全な例を見てみましょう。</p> + +<div style="overflow: auto;"> +<table class="fullwidth-table"> + <thead> + <tr> + <th scope="col">ハイライト前</th> + <th scope="col">ハイライト後</th> + </tr> + </thead> + <tbody> + <tr> + <td> + <pre class="brush: js; notranslate"> +var canvas = document.getElementById("canvas"); +var ctx = canvas.getContext("2d"); + +var path1 = new Path2D(); +path1.rect(10, 10, 100, 100); + +var path2 = new Path2D(path1); +path2.moveTo(220, 60); +path2.arc(170, 60, 50, 0, 2 * Math.PI); + +ctx.stroke(path2); +</pre> + + <p>ここで、 {{HTMLElement("pre")}} タグは <code><pre class="brush: js;"></code></p> + </td> + <td> + <pre class="brush: js; highlight[4, 7] notranslate"> +var canvas = document.getElementById("canvas"); +var ctx = canvas.getContext("2d"); + +var path1 = new Path2D(); +path1.rect(10, 10, 100, 100); + +var path2 = new Path2D(path1); +path2.moveTo(220, 60); +path2.arc(170, 60, 50, 0, 2 * Math.PI); + +ctx.stroke(path2);</pre> + + <p>ここで <code><pre></code> タグは <code><pre class="brush: js; highlight:[4,7]"></code>に変更されました。</p> + </td> + </tr> + </tbody> +</table> +</div> + +<h3 id="Styles_that_dont_have_toolbar_buttons" name="Styles_that_dont_have_toolbar_buttons">ツールバーボタンにないスタイル</h3> + +<p>私たちは MDN で使用するいくつかのスタイルを持っていますが、通常のユーザーインターフェイスでは使用できません。 幸いにも、これらはあまり頻繁には使用されません。 いくつかの例があります。</p> + +<ul> + <li>キー名のテキストに "キーボード" スタイルを適用するには、それらを {{HTMLElement("kbd")}} 要素で囲む必要があります。これにはまだユーザーインターフェイスはありません。 ソースモードにして <code><kbd></code> でキー名を囲みます。たとえば、ソースが次の場合 + + <pre class="brush: html; no-line-numbers notranslate"><p>Press the <kbd>Enter</kbd> key to start the countdown.</p></pre> + + <p>結果は次のとおりです。</p> + + <p>Press the <kbd>Enter</kbd> key to start the countdown.</p> + </li> + <li>特殊なページで使用される非常に珍しいスタイルも手作業で追加する必要があります。 これは特にグループボックスで一般的です。 そのため、ランディングページコンポーネントの多くを自動的に構築するためのマクロが用意されています。</li> +</ul> diff --git a/files/ja/mdn/editor/syntax_highlighting/index.html b/files/ja/mdn/editor/syntax_highlighting/index.html new file mode 100644 index 0000000000..d369e0d239 --- /dev/null +++ b/files/ja/mdn/editor/syntax_highlighting/index.html @@ -0,0 +1,45 @@ +--- +title: シンタックスハイライト +slug: MDN/Editor/Syntax_highlighting +tags: + - Guide + - Howto + - MDN Meta +translation_of: MDN/Editor/Syntax_highlighting +--- +<div>{{MDNSidebar}}</div><p>この機能は、MDNの記事にコードの例を追加するとき、構文の強調表現を可能にし、適切な部分をコードから視覚的に見つけやすくするように手助けをします。コードにシンタックスハイライトを行うには、</p> + +<ol> + <li> + <p>記事にコードを記述します。</p> + + <p>void main(int argc, char **argv) {</p> + + <p style="margin-left: 40px;">printf("Hello world\n");</p> + + <p>}</p> + </li> + <li> + <p>コード部分を選択し、ツールバーの <strong>PRE</strong> アイコンをクリックします。</p> + + <pre class="notranslate">void main(int argc, char **argv) { + +printf("Hello world\n"); + +} +</pre> + </li> + <li> + <p><strong>Syntax Highlighter</strong> アイコンをクリックし、コードに適したプログラミング言語を選択します。以下の例ではC/C++を選択しています。</p> + + <pre class="brush: cpp notranslate">void main(int argc, char **argv) { + +printf("Hello world\n"); + +}</pre> + </li> +</ol> + +<div class="note"> +<p><strong>Note:</strong> エディタ上ではシンタックスハイライトが行われません。プレビューを表示するか、変更を保存して記事を表示することでシンタックスハイライトを確認できます。</p> +</div> diff --git a/files/ja/mdn/editor/tables/index.html b/files/ja/mdn/editor/tables/index.html new file mode 100644 index 0000000000..88278dbeb3 --- /dev/null +++ b/files/ja/mdn/editor/tables/index.html @@ -0,0 +1,160 @@ +--- +title: 表 +slug: MDN/Editor/Tables +tags: + - Guide + - MDN Meta + - editor +translation_of: MDN/Editor/Tables +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">表は情報を表現する便利な方法です。この記事では MDN の表を作成し、維持する方法と、いつ作るべきでいつ作るべきでないのかをカバーします。</span></p> + +<p>MDNでは、主にデータ点ごとに2つを超える情報のリストを表す時に表を使います。名前と値のあるリストを作成している場合は、ふつうは表の代わりにリストを使います。つまり2列の表の使用は避けた方が良いです。これは主にモバイル端末では表の表示が難しく読みにくいことがあるためで、このためなるべく使用を避けています。</p> + +<p>表の使い方や適切な書式の詳細は <a href="/ja/docs/MDN/Contribute/Guidelines/Writing_style_guide" title="/ja/docs/Project:MDN/Style_guide">MDN スタイルガイド</a>を読んでください。しかし、表の挿入や編集の実用テクニックを見ていきましょう。</p> + +<h2 id="Creating_a_table" name="Creating_a_table">表を作成する</h2> + +<p>新しい表を挿入するには、ツールバーの<strong>表</strong>ボタンを押してください。外見は <img alt="as of Aug-2017" src="https://mdn.mozillademos.org/files/15297/table%20icon.png" style="height: 14px; width: 15px;"> のようにになっています。</p> + +<p><strong>表のプロパティ</strong>ダイアログボックスが開きます。</p> + +<p><img alt="表のプロパティダイアログボックスの表のプロパティタブのスクリーンショットb" src="https://mdn.mozillademos.org/files/15299/Table%20properties%20dialog%20box.png" style="border-style: solid; border-width: 1px; height: 363px; width: 295px;"></p> + +<p>ここには<strong>表のプロパティ</strong>と<strong>高度な設定</strong>の2つのタブがあります。</p> + +<h3 id="Table_Properties_tab" name="Table_Properties_tab">表のプロパティタブ</h3> + +<p>This tab is where you'll do most of your work configuring the table, as there are very few items in the <strong>Advanced</strong> tab that we recommend using. The options here are:</p> + +<dl> + <dt>行数</dt> + <dd>The number of rows in your table. You may add more rows while in the editor, but this lets you quickly configure your table.</dd> + <dt>列数</dt> + <dd>The number of columns in your table.</dd> + <dt>ヘッダ</dt> + <dd>Lets you configure where your headers are, if any. By default, no header cells are added to your table; however, we generally prefer that tables have headers, so you should change this most of the time. The possible values are <strong>None</strong>, <strong>First row</strong>, <strong>First column</strong>, and <strong>Both</strong>.</dd> + <dt>行揃え</dt> + <dd>Lets you align the table along the left, right, or center of the article. <strong>Please do not use this option.</strong> Our style guide specifies that tables should always be left-aligned. There are very few exceptions to this rule.</dd> + <dt>キャプション</dt> + <dd>You may choose to add a caption to your table; however, we do not usually do so on MDN, so you will probably leave this blank.</dd> + <dt>表の概要</dt> + <dd>You should typically leave this blank, as you should be providing appropriate explanatory text adjacant to your table.</dd> +</dl> + +<h3 id="Advanced_tab" name="Advanced_tab">高度な設定タブ</h3> + +<p>The <strong>Advanced</strong> tab provides a few additional options, most of which we don't use on MDN and will likely remove in the future.</p> + +<p><img alt="Screenshot of the Table Properites dialog box's Advanced tab" src="https://mdn.mozillademos.org/files/15301/table%20properties%20advanced%20tab.png" style="border-style: solid; border-width: 1px; height: 360px; width: 296px;"></p> + +<p>As you see here, there are only four options; they are:</p> + +<dl> + <dt>Id</dt> + <dd>The {{HTMLElement("table")}} element's <code>id</code>. We generally do not use IDs on tables on MDN.</dd> + <dt>文字表記の方向</dt> + <dd>Lets you establish the writing direction used in the table. This should be used only when localizing content.</dd> + <dt>スタイル</dt> + <dd>This field lets you hand-enter custom CSS. <strong>Do not use this field! We will probably remove your table if you do.</strong> We are trying to eliminate all uses of custom styles outside what's provided by our stylesheets.</dd> + <dt>スタイルシートクラス</dt> + <dd>This lets you specify a stylesheet class to use for the table. This should nearly always be "standard-table", which is our standard table class.</dd> +</dl> + +<p>Once you've finished configuring your table, click the <strong>OK</strong> button to create it.</p> + +<h2 id="Maintaining_tables" name="Maintaining_tables">表を保守する</h2> + +<p>Once a table has been created, working with it is very much like in any table editor, entering data into its cells. Pressing the tab key will advance you to the next cell in the table, wrapping to the next row if you're in the last cell in the row you're currently working on. If you're in the last cell of the last row when you press tab, a new row will be added to the end of the table, and the cursor will be placed in the first cell of the new row.</p> + +<p>You may right-click on the table to get an assortment of options for adjusting the cells, rows, columns, and the table itself:</p> + +<p><img alt="Screenshot of the Table context menu" src="https://mdn.mozillademos.org/files/15303/table%20context%20menu.png" style="height: 196px; width: 166px;"></p> + +<dl> + <dt>Paste</dt> + <dd>On browsers that support pasting via script (some, including Firefox, do not, for security purposes), selecting this option pastes the contents of the clipboard at the current point in the table.</dd> + <dt>Cell</dt> + <dd>This submenu offers options related to the selected cell or cells. See {{anch("Cell options")}}.</dd> + <dt>Row</dt> + <dd>This submenu offers options related to the selected row or rows. See {{anch("Row options")}}.</dd> + <dt>Column</dt> + <dd>This submenu offers options related to the selected column or columns. See {{anch("Column options")}}.</dd> + <dt>Delete Table</dt> + <dd>Deletes the entire table.</dd> + <dt>Sort Table</dt> + <dd>Opens a dialog box providing options for sorting the contents of the table. See {{anch("Sorting tables")}} below.</dd> + <dt>Table Properties</dt> + <dd>Opens the same table properties dialog used to create a new table.</dd> +</dl> + +<h3 id="Cell_submenu" name="Cell_submenu">セルのサブメニュー</h3> + +<p>The Cell submenu offers options related to manipulating and editing cells in your table, and looks like this:</p> + +<p><img alt="Screenshot of the Table context menu's Cell submenu" src="https://mdn.mozillademos.org/files/15305/table%20context%20menu%20-%20cell%20submenu.png" style="height: 235px; width: 275px;"></p> + +<p>These options should be fairly self-explanatory, with the exception that <strong>Merge Cells</strong> is available only if you have selected multiple cells; you can then use this option to combine them into a single cell. The <strong>Merge Right</strong> and <strong>Merge Down</strong> options merge the current cell with the one to the right, or below, respectively.</p> + +<h3 id="Cell_Properties_dialog_box" name="Cell_Properties_dialog_box">セルプロパティのダイアログボックス</h3> + +<p>The <strong>Cell Properties</strong> option opens a dialog box that gives you control over the details of a cell:</p> + +<p><img alt="Screenshot of the Cell Properties dialog box" src="https://mdn.mozillademos.org/files/15307/Cell%20Properties%20dialog%20box.png" style="border-style: solid; border-width: 1px; height: 311px; width: 386px;"></p> + +<p>The options you can configure here are:</p> + +<dl> + <dt>Width</dt> + <dd>The width of the cell; you may change the units used for this value using the adjacent drop-down. <strong>Please don't use this.</strong> You shouldn't need to adjust widths of cells except in rare cases involving nesting images or example code within tables.</dd> + <dt>Height</dt> + <dd>The cell's height; this is always in pixels. <strong>Please don't use this.</strong> We prefer for cell sizes to be determined automatically, except in exceptionally rare cases.</dd> + <dt>Word Wrap</dt> + <dd>Specifies whether or not the cell's contents should be permitted to wrap. This should almost always be left at "Yes", the default.</dd> + <dt>Horizontal Alignment</dt> + <dd>Allows you to set the horizontal alignment for the cell's or cells' contents. This should almost always be left at the default.</dd> + <dt>Vertical Alignment</dt> + <dd>Lets you set the vertical alignment of the cell or cells. This should nearly always be left at the default, but may be adjusted if necessary.</dd> + <dt>Cell Type</dt> + <dd>Lets you specify whether the cell or cells contain data or header information. Making a row a header row gives it header styling that stands out from the data within the table.</dd> + <dt>Rows Span</dt> + <dd>Lets you specify how many rows the cell should take up within the table. Rarely needed, but useful for certain types of table.</dd> + <dt>Columns Span</dt> + <dd>Lets you indicate how many columns the cell should occupy within the table. You should rarely need to use this option.</dd> + <dt>Background Color</dt> + <dd>Lets you specify a background color for the cell. Please try to avoid using this; the rare cases in which changing the colors in a table are acceptable are covered by CSS classes.</dd> + <dt>Border Color</dt> + <dd>Lets you specify a border color for the cel. Please try to avoid using this; the rare cases in which changing the colors in a table are acceptable are covered by CSS classes.</dd> +</dl> + +<h3 id="Row_submenu" name="Row_submenu">行のサブメニュー</h3> + +<p>The <strong>Row</strong> submenu gives you options you may use to adjust and refine the rows in your table:</p> + +<p><img alt="Screenshot of the Table context menu's Row submenu" src="https://mdn.mozillademos.org/files/15309/Table%20context%20menu%20-%20Row%20submenu.png" style="height: 164px; width: 247px;"></p> + +<p>These options are all straightforward:</p> + +<ul> + <li><strong>Insert Row Before</strong> adds a new row before the current cursor position in the table</li> + <li><strong>Insert Row After</strong> adds a new row below the current row</li> + <li><strong>Delete Rows</strong> removes the row containing the insertion point, or all selected rows (or all rows on which you have selected cells)</li> +</ul> + +<h3 id="Column_submenu" name="Column_submenu">列のサブメニュー</h3> + +<p>The <strong>Column</strong> submenu lets you edit the columns in your table:</p> + +<p><img alt="Screenshot of the Table context menu's Column submenu" src="https://mdn.mozillademos.org/files/15313/Table%20context%20menu%20-%20column%20submenu.png" style="height: 174px; width: 268px;"></p> + +<p>These options mirror those in the row options menu:</p> + +<ul> + <li><strong>Insert Column Before</strong> adds a new column to the left of the current cursor position in the table (or to the right in right-to-left languages)</li> + <li><strong>Insert Column After</strong> adds a new row to the right of the current location (or to the left in right-to-left languages)</li> + <li><strong>Delete Columns</strong> removes the column containing the insertion point, or all selected columns (or all columns in which you have selected cells)</li> +</ul> + +<p>{{EditorGuideQuicklinks}}</p> diff --git a/files/ja/mdn/guidelines/code_guidelines/css/index.html b/files/ja/mdn/guidelines/code_guidelines/css/index.html new file mode 100644 index 0000000000..4f4449ba5c --- /dev/null +++ b/files/ja/mdn/guidelines/code_guidelines/css/index.html @@ -0,0 +1,255 @@ +--- +title: CSS のガイドライン +slug: MDN/Guidelines/Code_guidelines/CSS +tags: + - CSS + - Code + - Guide + - Guidelines + - MDN Meta +translation_of: MDN/Guidelines/Code_guidelines/CSS +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p class="summary">次のガイドラインでは、MDN コードの例として CSS を記述する方法について説明します。</p> + +<h2 id="In_this_article" name="In_this_article">目次</h2> + +<ul> + <li><a href="#High-level_guidelines">高水準のガイドライン</a> + + <ul> + <li><a href="#Dont_use_preprocessors">プリプロセッサーを使用しない</a></li> + <li><a href="#Dont_use_specific_CSS_methodologies">特定の CSS の方法論を使わない</a></li> + <li><a href="#Use_flexiblerelative_units">柔軟性のある/相対的な単位を使用する</a></li> + <li><a href="#Dont_use_resets">リセットを使わない</a></li> + <li><a href="#Plan_your_CSS_%E2%80%94_avoid_overriding">CSS を計画する - オーバーライドを避ける</a></li> + </ul> + </li> + <li><a href="#General_CSS_coding_style">一般的な CSS コーディングスタイル</a> + <ul> + <li><a href="#Use_expanded_syntax">展開した構文を使用する</a></li> + <li><a href="#Favor_longhand_rules_over_terse_shorthand">一括指定よりも個別指定を推奨</a></li> + <li><a href="#Use_double_quotes_around_values">値の周りには二重引用符を使用する</a></li> + <li><a href="#Spacing_around_function_parameters">関数の引数の空白</a></li> + <li><a href="#CSS_comments">CSS のコメント</a></li> + <li><a href="#Dont_use_!important">!important は使わない</a></li> + </ul> + </li> + <li><a href="#Specific_CSS_syntax_points">具体的な CSS 構文のポイント</a> + <ul> + <li><a href="#Turning_off_borders_and_other_properties">ボーダーなどのプロパティをオフにする</a></li> + <li><a href="#Use_mobile_first_media_queries">「モバイルファースト」のメディアクエリを使用する</a></li> + </ul> + </li> + <li><a href="#Selectors">セレクター</a> + <ul> + <li><a href="#Dont_use_ID_selectors">ID セレクターを使わない</a></li> + <li><a href="#Put_multiple_selectors_on_separate_lines">複数のセレクターは個別の行に配置する</a></li> + </ul> + </li> +</ul> + +<h2 id="High-level_guidelines" name="High-level_guidelines">高水準のガイドライン</h2> + +<h3 id="Dont_use_preprocessors" name="Dont_use_preprocessors">プリプロセッサーを使用しない</h3> + +<p>MDN のサンプル コードでは、<a href="https://sass-lang.com/">Sass</a>,<a href="http://lesscss.org/">Less</a>,<a href="http://stylus-lang.com/">Stylus,</a>などのプリプロセッサー構文を使用しないでください。MDN はバニラ CSS 言語を文書化しており、プリプロセッサーを使用することは、例を理解するためのハードルを上げるだけであり、読者を混乱させる可能性があります。</p> + +<h3 id="Dont_use_specific_CSS_methodologies" name="Dont_use_specific_CSS_methodologies">特定の CSS の方法論を使わない</h3> + +<p>前のガイドラインと同じ精神で、 <a href="http://getbem.com/naming/">BEM</a> や <a href="https://smacss.com/">SMACSS</a> のような特定の CSS の方法論を使って MDN のサンプルコードを書かないようにしてください。これらが有効な CSS 構文であっても、それらの方法論に精通していない人にとっては、命名規則が混乱を招く可能性があります。</p> + +<h3 id="Use_flexiblerelative_units" name="Use_flexiblerelative_units">柔軟性のある/相対的な単位を使用する</h3> + +<p>可能な限り幅広い端末で最大限の柔軟性を実現するために、コンテナーやパディングなどの寸法は、em や rem のような相対的な単位を使用し、ビューポートの幅に応じて変化させたい場合はパーセント値やビューポートの単位を使用することをお勧めします。これについては、<a href="/ja/docs/Web/Apps/app_layout/responsive_design_building_blocks#Fluid_grids">レスポンシブデザインのビルディングブロック</a>の記事をご覧ください。</p> + +<h3 id="Dont_use_resets" name="Dont_use_resets">リセットを使わない</h3> + +<p>For maximum control over CSS across platforms, a lot of people used to use CSS resets to remove every style, before then building things back up themselves. This certainly has its merits, but especially in the modern world CSS resets can be overkill, resulting in lots of extra time spent reimplementing things that weren't completely broken in the first place, like default margins, list styles, etc.</p> + +<p>If you really feel like you need to use a reset, consider using <a href="http://necolas.github.io/normalize.css/">normalize.css by Nicolas Gallagher</a>, which aims to just make things more consistent across browsers, get rid of some default annoyances that we always remove (the margins on <code><body></code>, for example) and fix a few bugs.</p> + +<h3 id="Plan_your_CSS_—_avoid_overriding" name="Plan_your_CSS_—_avoid_overriding">CSS を計画する — オーバーライドを避ける</h3> + +<p>Before diving in and writing huge chunks of CSS, plan your styles carefully. What general styles are going to be needed, what different layouts do you need to create, what specific overrides need to be created, and are they reusable? Above all, you need to try to avoid too much overriding. If you keep finding yourself writing styles and then cancelling them again a few rulesets down, you probably need to rethink your strategy.</p> + +<h2 id="General_CSS_coding_style" name="General_CSS_coding_style">一般的な CSS のコーディングスタイル</h2> + +<h3 id="Use_expanded_syntax" name="Use_expanded_syntax">展開した構文を使用する</h3> + +<p>There are a variety of CSS writing styles you can use, but we prefer the expanded style, with the selector/opening brace, close brace, and each declaration on a separate line. This maximizes readability, and again, promotes consistency on MDN.</p> + +<p>Use this:</p> + +<pre class="brush: css example-good notranslate">p { + color: white; + background-color: black; + padding: 1rem; +}</pre> + +<p>Not this:</p> + +<pre class="brush: css example-bad notranslate">p { color: white; background-color: black; padding: 1rem; }</pre> + +<p>In addition, keep these specifics in mind:</p> + +<ul> + <li>Include a space between the selector(s) and the opening curly brace.</li> + <li>Always include a semi-colon at the end of the last declaration, even though it isn't strictly necessary.</li> + <li>Put the closing curly brace on a new line.</li> + <li>In each declaration, put a space after the separating colon, but not before.</li> + <li>Use 2 spaces for code indentation.</li> +</ul> + +<h3 id="Favor_longhand_rules_over_terse_shorthand" name="Favor_longhand_rules_over_terse_shorthand">一括指定よりも個別指定を推奨</h3> + +<p>Usually when teaching the specifics of CSS syntax, it is clearer and more obvious to use longhand properties, rather than terse shorthand (unless of course teaching the shorthand is the point of the example). Remember that the point of MDN examples is to teach people, not to be clever or efficient.</p> + +<p>To start with, it is often harder to understand what the shorthand is doing. It takes a while to pick apart exactly what {{cssxref("font")}} syntax is doing, for example:</p> + +<pre class="brush: css notranslate">font: small-caps bold 2rem/1.5 sans-serif;</pre> + +<p>Whereas this is more immediate in terms of understanding:</p> + +<pre class="brush: css notranslate">font-variant: small-caps; +font-weight: bold; +font-size: 2rem; +line-height: 1.5; +font-family: sans-serif;</pre> + +<p>Second, CSS shorthand comes with potential added pitfalls — default values are set for parts of the syntax that you don't explicitly set, which can produce unexpected resets of values you've set earlier in the cascade, or other expected effects. The {{cssxref("grid")}} property for example sets all of the following default values for items that are not specified:</p> + +<ul> + <li>{{cssxref("grid-template-rows")}}: <code>none</code></li> + <li>{{cssxref("grid-template-columns")}}: <code>none</code></li> + <li>{{cssxref("grid-template-areas")}}: <code>none</code></li> + <li>{{cssxref("grid-auto-rows")}}: <code>auto</code></li> + <li>{{cssxref("grid-auto-columns")}}: <code>auto</code></li> + <li>{{cssxref("grid-auto-flow")}}: <code>row</code></li> + <li>{{cssxref("grid-column-gap")}}: <code>0</code></li> + <li>{{cssxref("grid-row-gap")}}: <code>0</code></li> + <li>{{cssxref("column-gap")}}: <code>normal</code></li> + <li>{{cssxref("row-gap")}}: <code>normal</code></li> +</ul> + +<p>In addition, some shorthands only work as expected if you include the different value components in a certain order. In CSS animations for example:</p> + +<pre class="brush: css notranslate">/* duration | timing-function | delay | iteration-count + direction | fill-mode | play-state | name */ +animation: 3s ease-in 1s 2 reverse both paused slidein;</pre> + +<p>As an example, the first value that can be parsed as a {{cssxref("time", "<time>")}} is assigned to the {{cssxref("animation-duration")}}, and the second one is assigned to {{cssxref("animation-delay")}}. For more details, read the full <a href="/en-US/docs/Web/CSS/animation#Syntax">animation syntax</a> details.</p> + +<h3 id="Use_double_quotes_around_values" name="Use_double_quotes_around_values">値の周りには二重引用符を使用する</h3> + +<p>Where quotes can or should be included, use them, and use double quotes. For example:</p> + +<pre class="brush: css example-good notranslate">[data-vegetable="liquid"] { + background-color: goldenrod; + background-image: url("../../media/examples/lizard.png"); +}</pre> + +<h3 id="Spacing_around_function_parameters" name="Spacing_around_function_parameters">関数の引数の空白</h3> + +<p>Function parameters should have spaces after their separating commas, but not before:</p> + +<pre class="brush: css example-good notranslate">color: rgb(255, 0, 0); +background-image: linear-gradient(to bottom, red, black);</pre> + +<h3 id="CSS_のコメント">CSS のコメント</h3> + +<p>Use CSS-style comments to comment code that isn't self-documenting:</p> + +<pre class="brush: css example-good notranslate">/* This is a CSS-style comment */</pre> + +<p>Put your comments on separate lines preceeding the code they are referring to:</p> + +<pre class="brush: css example-good notranslate">h3 { + /* Creates a red drop shadow, offset 1px right and down, w/2px blur radius */ + text-shadow: 1px 1px 2px red; + /* Sets the font-size to double the default document font size */ + font-size: 2rem; +}</pre> + +<p>Also note that you should leave a space between the asterisks and the comment, in each case.</p> + +<h3 id="Dont_use_!important" name="Dont_use_!important">!important は使わない</h3> + +<p>!important is a last resort generally only used when you need to override something and there is no other way. It is a bad practice and you should avoid it wherever possible.</p> + +<p>Bad:</p> + +<pre class="brush: css example-bad notranslate">.bad-code { + font-size: 4rem !important; +}</pre> + +<h2 id="Specific_CSS_syntax_points" name="Specific_CSS_syntax_points">具体的な CSS 構文のポイント</h2> + +<h3 id="border_などのプロパティをオフにする">border などのプロパティをオフにする</h3> + +<p>When turning off borders (and any other properties that can take <code>0</code> or <code>none</code> as values), use <code>0</code> rather than <code>none</code>:</p> + +<pre class="brush: css example-good notranslate">border: 0;</pre> + +<h3 id="Use_mobile_first_media_queries" name="Use_mobile_first_media_queries">「モバイルファースト」のメディアクエリを使用する</h3> + +<p>When including different sets of styles for different target viewport sizes using media queries inside the same stylesheet, it is a good idea to make the default styling before any media queries have been applied to the document the narrow screen/mobile styling, and then override this for wider viewports inside successive media queries.</p> + +<pre class="brush: css example-good notranslate">/*Default CSS layout for narrow screens*/ + +@media (min-width: 480px) { + /*CSS for medium width screens*/ +} + +@media (min-width: 800px) { + /*CSS for wide screens*/ +} + +@media (min-width: 1100px) { + /*CSS for really wide screens*/ +}</pre> + +<p>This has many advantages, outlined in our <a href="/en-US/docs/Web/Apps/Progressive/Responsive/Mobile_first">Mobile First</a> article.</p> + +<h2 id="Selectors" name="Selectors">セレクター</h2> + +<h3 id="Dont_use_ID_selectors" name="Dont_use_ID_selectors">ID セレクターを使わない</h3> + +<p>There is really no need to use ID selectors — they are less flexible (you can't add more if you discover you need more than one), and are harder to override if needed, being of a higher specificity than classes.</p> + +<p>Good:</p> + +<pre class="brush: css example-good notranslate">.editorial-summary { + ... +}</pre> + +<p>Bad:</p> + +<pre class="brush: css example-bad notranslate">#editorial-summary { + ... +}</pre> + +<h3 id="Put_multiple_selectors_on_separate_lines" name="Put_multiple_selectors_on_separate_lines">複数のセレクターは個別の行に配置する</h3> + +<p>When a rule has multiple selectors, put each selector on a new line. This makes the selector list easier to read, and can help to make code lines shorter.</p> + +<p>Do this:</p> + +<pre class="brush: css example-good notranslate">h1, +h2, +h3 { + font-family: sans-serif; + text-align: center; +}</pre> + +<p>Not this:</p> + +<pre class="brush: css example-bad notranslate">h1, h2, h3 { + font-family: sans-serif; + text-align: center; +}</pre> + +<h2 id="Good_CSS_examples_on_MDN" name="Good_CSS_examples_on_MDN">MDN の良い CSS の例</h2> + +<p>CSS プロパティのリファレンスページの冒頭には、簡潔で意味のある良い CSS スニペットが掲載されています。 <a href="/ja/docs/Web/CSS/Reference#Keyword_index">CSS のキーワード索引</a>から探して参照してみてください。そこにあるインタラクティブな例は、一般的に上記のガイドラインに沿って書かれていますが、ガイドラインが新しく書かれる前に書かれたものがほとんどなので、場所によってはそうではない場合があることに注意してください。</p> diff --git a/files/ja/mdn/guidelines/code_guidelines/general/index.html b/files/ja/mdn/guidelines/code_guidelines/general/index.html new file mode 100644 index 0000000000..207830b455 --- /dev/null +++ b/files/ja/mdn/guidelines/code_guidelines/general/index.html @@ -0,0 +1,160 @@ +--- +title: すべてのコードの全般的なガイドライン +slug: MDN/Guidelines/Code_guidelines/General +tags: + - Code + - General + - Guide + - Guidelines + - MDN Meta + - MDN メタ + - ガイド + - ガイドライン + - コード + - 全般 +translation_of: MDN/Guidelines/Code_guidelines/General +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p class="summary">以下のコード例のガイドラインは、 HTML, CSS, JavaScript, その他のどれであっても適用されます。</p> + +<h2 id="In_this_article" name="In_this_article">目次</h2> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Indentation_spacing_size">インデントづけ、領域、大きさ</a> + + <ul> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Indentation">インデント付け</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Code_line_length">コードの行の長さ</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Code_block_height">コードブロックの高さ</a></li> + </ul> + </li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Guidelines_for_displaying_examples">例を示す場合のガイドライン</a> + <ul> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Size_of_rendered_example">例を表示する大きさ</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Use_of_images_and_other_media">画像およびその他のメディアの使用</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Use_of_color">色の使用</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Highlight_good_and_bad_practice_examples">良い例と悪い例の強調表示</a></li> + </ul> + </li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/General#Writing_syntax_sections_on_reference_pages">リファレンスページの構文の節を書く</a></li> +</ul> + +<h2 id="Indentation_spacing_size" name="Indentation_spacing_size">インデント付け、領域、大きさ</h2> + +<h3 id="Indentation" name="Indentation">インデント付け</h3> + +<p>すべてのコードは、次のように2文字のインデントを使用します。</p> + +<pre class="brush: html example-good notranslate"><div> + <p>This is my paragraph.</p> +</div></pre> + +<pre class="brush: js example-good notranslate">function myFunc() { + if(thingy) { + console.log('Yup, that worked.'); + } +}</pre> + +<h3 id="Code_line_length" name="Code_line_length">コードの行の長さ</h3> + +<p>コードの行の長さは最大80文字 (<a href="https://github.com/mdn/interactive-examples">対話型デモ</a>の場合は64文字) にしてください。読みやすくするために、適切な方法で改行する必要がありますが、ベストプラクティスを犠牲にする必要はありません。</p> + +<p>例えば、次のものは良くありません。</p> + +<pre class="brush: js example-bad notranslate">let tommyCat = 'Said Tommy the Cat as he reeled back to clear whatever foreign matter may have nestled its way into his mighty throat. Many a fat alley rat had met its demise while staring point blank down the cavernous barrel of this awesome prowling machine.';</pre> + +<p>次のものはましですが、まだ幾らかぎこちないです。</p> + +<pre class="brush: js notranslate">let tommyCat = 'Said Tommy the Cat as he reeled back to clear whatever foreign ' ++ 'matter may have nestled its way into his mighty throat. Many a fat alley rat ' ++ 'had met its demise while staring point blank down the cavernous barrel of ' ++ 'this awesome prowling machine.';</pre> + +<p>テンプレートリテラルを使うのもよいでしょう。</p> + +<pre class="brush: js example-good notranslate">let tommyCat = `Said Tommy the Cat as he reeled back to clear whatever foreign + matter may have nestled its way into his mighty throat. Many a fat alley rat + had met its demise while staring point blank down the cavernous barrel of + this awesome prowling machine.`;</pre> + +<h3 id="Code_block_height" name="Code_block_height">コードブロックの高さ</h3> + +<p>コードブロックは必要なだけの長さであるべきですが、それより長くなってもいけません。できれば、15-25行が目安です。コードブロックがはるかに長くなりそうであれば、最も有用なスニペットのみを示し、 GitHup リポジトリや codepen に入れた完全な例にリンクさせてください。</p> + +<h2 id="Guidelines_for_displaying_examples" name="Guidelines_for_displaying_examples">例を表示する際のガイドライン</h2> + +<h3 id="Size_of_rendered_example" name="Size_of_rendered_example">例を表示する大きさ</h3> + +<p>MDN のメインコンテンツペインは、デスクトップでおよそ 700px の幅ですので、 MDN に埋め込む例はその幅であれば大丈夫です (埋め込む例の幅を 100% に設定してください)。</p> + +<p>高さについては、可能な限り画面で読みやすくするために、例を表示する高さを 700px 未満に保つことをお勧めします。</p> + +<p>また、サンプルをある程度レスポンシブにすることを検討する必要があり、そうすればモバイル端末でも役立ちます。</p> + +<h3 id="Use_of_images_and_other_media" name="Use_of_images_and_other_media">画像およびその他のメディアの使用</h3> + +<p>画像やその他のメディアを例に含めたい場合があるでしょう。その場合は次のようにしてください。</p> + +<ul> + <li>あなたが利用できるライセンスであることを確認してください。許容度がとても広いライセンス、例えば <a href="https://creativecommons.org/share-your-work/public-domain/cc0/" rel="nofollow">CC0</a> や、一般的なコンテンツライセンス — <a class="external text external-icon" href="http://creativecommons.org/licenses/by-sa/2.5/" rel="nofollow noopener" title="http://creativecommons.org/licenses/by-sa/2.5/">クリエイティブ・コモンズの表示-継承ライセンス</a> (CC-BY-SA) — と互換性のある1つ以上のライセンスを持つメディアを使用してみてください。</li> + <li>画像については、 <a href="https://tinypng.com" rel="nofollow">https://tinypng.com</a> や <a href="https://imageoptim.com" rel="nofollow">https://imageoptim.com</a> を通すと例のページの重さを軽減することができます。</li> + <li><code>SVG</code> については、コードを <a href="https://jakearchibald.github.io/svgomg/">SVGOMG</a> に通すと <code>SVG</code> ファイルの最後に空行があることを保証することができます。</li> + <li> + <p>ページ上にアイコンを表示するときは (例えば {{cssxref("background-image")}} などで)、適切な箇所に <a href="https://mdn.github.io/mdn-fiori/patterns/css/iconography/">MDN 組み込みアイコン</a>を使用し、他のものとスタイルを合わせるようにしてください。</p> + </li> +</ul> + +<h3 id="Use_of_color" name="Use_of_color">色の使用</h3> + +<p>16進数であれば小文字で、影や主な色 (black, white, red など) ならばキーワードを使用することもできます。より複雑な方式 (透過を含めるなど) は必要な場合だけ使用してください。</p> + +<p>下記のように、主要な色やその他の「基本的な」色はキーワードを使用することを推奨します。</p> + +<pre class="brush: css example-good notranslate">color: black; +color: white; +color: red;</pre> + +<p>もっと複雑な色には rgb() を使用してください (半透過のものも含む)。</p> + +<pre class="brush: css example-good notranslate">color: rgb(0, 0, 0, 0.5); +color: rgb(248, 242, 230);</pre> + +<p>16進の色を使用する必要がある場合は、小文字を使用してください。</p> + +<pre class="brush: css example-good notranslate">color: #058ed9; +color: #a39a92;</pre> + +<p>冗長であれば短縮形を使用してください。</p> + +<pre class="brush: css example-good notranslate">color: #ff0; +color: #fff;</pre> + +<p><a href="https://mdn.github.io/mdn-fiori/">MDN's Fiori guidelines</a> (フロンドエンドコードベース向け) には、 MDN のデザイン全般を貫く<a href="https://mdn.github.io/mdn-fiori/patterns/scss/variables/">有用な色のセット</a>があります。</p> + +<h3 id="Highlight_good_and_bad_practice_examples" name="Highlight_good_and_bad_practice_examples">良い例と悪い例の強調表示</h3> + +<p>このガイドラインを見ていてお気づきと思いますが、良い方法と思われるコードブロックは緑地に笑顔で強調表示され、悪い方法と思われるコードブロックには赤地に悲しい顔で強調表示されています。</p> + +<p>これを行うには、まず MDN エディターコントロールを使用してコードブロックを <code><pre></code> ブロックの中に入れ、適切な構文強調表示を指定してください。コードのソースは次のようになります。</p> + +<pre class="notranslate"><pre class="brush: js"> +function myFunc() { + console.log('Hello!'); +};</pre></pre> + +<p>これを良い例とするには、 <code>example-good</code> を <code>class</code> 属性の引用符の直前に入れてください。</p> + +<pre class="notranslate"><pre class="brush: js example-good"> + ...</pre> + +<p>悪い例とするには、 <code>example-bad</code> を <code>class</code> 属性の引用符の直前に入れてください。</p> + +<pre class="notranslate"><pre class="brush: js example-bad"> + ...</pre> + +<p>これらの使用をお勧めします。これらをすべての場所で使用する必要はありません。特に、コードの良い点と悪い点を明確に示している場合に限って使用してください。</p> + +<h2 id="Writing_syntax_sections_on_reference_pages" name="Writing_syntax_sections_on_reference_pages">リファレンスページの構文の節を書く</h2> + +<p>MDN リファレンスページには、ある機能、例えば JavaScript メソッド、 CSS プロパティ、 HTML 要素、などがどのような構文を取りうる・取るべきかを曖昧にせずに示します。これらを記述するガイドラインは<a href="/ja/docs/MDN/Contribute/Structures/Syntax_sections">構文の節</a>の文書にあります。</p> diff --git a/files/ja/mdn/guidelines/code_guidelines/html/index.html b/files/ja/mdn/guidelines/code_guidelines/html/index.html new file mode 100644 index 0000000000..167160be4b --- /dev/null +++ b/files/ja/mdn/guidelines/code_guidelines/html/index.html @@ -0,0 +1,165 @@ +--- +title: HTML ガイドライン +slug: MDN/Guidelines/Code_guidelines/HTML +tags: + - Code + - Guide + - Guidelines + - HTML + - MDN Meta +translation_of: MDN/Guidelines/Code_guidelines/HTML +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p class="summary">以下のガイドラインでは、MDN のコードの例で HTML をどのように記述するのかを学習します。</p> + +<h2 id="In_this_article" name="In_this_article">この記事について</h2> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Doctype_and_metadata">文書型宣言とメタデータ</a> + + <ul> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Doctype">Doctype</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Document_language">文書の言語</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Document_characterset">文書の文字セット</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Viewport_meta_tag">ビューポートメタタグ</a></li> + </ul> + </li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#General_markup_coding_style">一般的なマークアップコーディングスタイル</a> + <ul> + <li><a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Use_lowercase">小文字を使う</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Trailing_slashes">末尾のスラッシュ</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Quoting_attributes">属性の引用</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Use_double_quotes">ダブルクォートを使う</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Boolean_attributes">真偽属性</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Class_and_ID_names">クラス と ID の名前</a></li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML#Entity_references">実体参照</a></li> + </ul> + </li> +</ul> + +<h2 id="Doctype_and_metadata" name="Doctype_and_metadata">Doctype とメタデータ</h2> + +<div class="note"> +<p><strong>注記</strong>: このセクションにあるガイドラインは完全な HTML 文書として見せなければならない時だけ適用してください。多くの場合、このようにする必要がありません; スニペット(HTML の断片)で通常は機能を説明するのに十分間に合います。<a href="/ja/docs/MDN/Contribute/Structures/Code_examples#Traditional_live_samples">EmbedLiveSample macro</a> を使うと、スニペットを取り込みます; 表示される際に自動で完全な HTML 文書に挿入されます。</p> +</div> + +<h3 id="Doctype" name="Doctype">Doctype</h3> + +<p>HTML5 の Doctype を使わなくてはなりません。短く、覚えやすく、後方互換性があります:</p> + +<pre class="brush: html example-good notranslate"><!DOCTYPE html></pre> + +<h3 id="Document_language" name="Document_language">文書の言語</h3> + +<p>{{htmlelement("html")}} 要素に {{htmlattrxref('lang')}} 属性を使って文書の言語を設定します:</p> + +<pre class="brush: html example-good notranslate"><html lang="ja"></pre> + +<p>これはアクセシビリティと検索エンジンにとって良いことで、コンテンツのローカライズに役立ち、最良の慣習を使うべきと気づかせます。</p> + +<h3 id="Document_characterset" name="Document_characterset">文書の文字セット</h3> + +<p>また文書の文字セットを以下のように定義しなければなりません:</p> + +<pre class="brush: html example-good notranslate"><meta charset="utf-8"></pre> + +<p>UTF-8 を使用しないというとても明白な理由がない限りは使用するべきです; 文書でどんな言語が使われていても必要とする文字を余裕を持って扱えます。加えて、常にできるだけ早く、HTML の {{HTMLElement("head")}} ブロック (先頭の 1 キロバイト内) に文字セットを特定するべきです、かなり <a href="http://support.microsoft.com/kb/928847">不快な Internet Explorer のセキュリティ脆弱性</a> から守ってくれるからです。</p> + +<h3 id="Viewport_meta_tag" name="Viewport_meta_tag">ビューポートメタタグ</h3> + +<p>最後に、HTML {{HTMLElement("head")}} にはビューポートメタタグを追加しなければなりません、例を示してモバイル端末でより良く動作するきっかけとなります。文書に少なくとも以下の内容を含めておき、必要になったら後ほど変更できます:</p> + +<pre class="brush: html example-good notranslate"><meta name="viewport" content="width=device-width"></pre> + +<p>より詳しくは <a href="/ja/docs/Mobile/Viewport_meta_tag">モバイルブラウザーでのレイアウトを制御するために meta タグの viewport を使う</a> をご覧ください。</p> + +<h2 id="General_markup_coding_style" name="General_markup_coding_style">一般的なマークアップコーディングスタイル</h2> + +<h3 id="Use_lowercase" name="Use_lowercase">小文字を使う</h3> + +<p>すべての要素の名前と属性の名前/値に小文字を使ってください、綺麗に見えますし、マークアップをより早く書くことができます。</p> + +<p>良い例:</p> + +<pre class="brush: html example-good notranslate"><p class="nice">This looks nice and neat</p></pre> + +<p>良くない例:</p> + +<pre class="brush: html example-bad notranslate"><P CLASS="WHOA-THERE">Why is my markup shouting?</P></pre> + +<h3 id="Trailing_slashes" name="Trailing_slashes">末尾のスラッシュ</h3> + +<p>空要素に XHTML スタイルの末尾のスラッシュを含めないでください、不要ですし実行速度を遅くします。注意しないと古いブラウザーを中断させます (思い返してみると、Netscape 4 から問題とはなっていませんが)。</p> + +<p>こちらは良い例:</p> + +<pre class="brush: html example-good notranslate"><input type="text"> +<hr></pre> + +<p>スラッシュは必要ありません:</p> + +<pre class="brush: html example-bad notranslate"><input type="text" /> +<hr /></pre> + +<h3 id="Quoting_attributes" name="Quoting_attributes">属性を引用符で囲む</h3> + +<p>すべての属性の値はダブルクォートで囲わなければなりません。HTML5 でクオートの省略が許されるようになり、広まっていますが、取り入れるとマークアップが綺麗になり読みやすくなります。例えば、こちらは良い例です:</p> + +<pre class="brush: html example-good notranslate"><img src="images/logo.jpg" alt="A circular globe icon" class="no-border"></pre> + +<p>次の例と比べてください。</p> + +<pre class="brush: html example-bad notranslate"><img src=images/logo.jpg alt=A circular globe icon class=no-border></pre> + +<p>こちらは問題も引き起こします — 上記の例では <code>alt</code> 属性の部分が複数の属性と解釈されて実行が中断するでしょう、"A circular globe icon" が 1 つの属性の値であると特定するクォートがないためです。</p> + +<h3 id="Use_double_quotes" name="Use_double_quotes">ダブルクォートを使う</h3> + +<p>HTML にはシングルクォートでなく、ダブルクォートを使います:</p> + +<pre class="brush: html example-good notranslate"><p class="important">Yes</p></pre> + +<pre class="brush: html example-bad notranslate"><p class='important'>Nope</p></pre> + +<h3 id="Boolean_attributes" name="Boolean_attributes">真偽属性</h3> + +<p>真偽属性は完全な形で書かないでください; 設定するには属性の名前だけ書きます。例えば、このように書きます:</p> + +<pre class="brush: html example-good notranslate">required</pre> + +<p>これだけで完全に理解され、うまく動作します。値を含めて書く長い形式、</p> + +<pre class="brush: html example-bad notranslate">required="required" </pre> + +<p>もサポートされるものの必須ではありません。</p> + +<h3 id="Class_and_ID_names" name="Class_and_ID_names">クラス名と ID 名</h3> + +<p>意味のあるクラス/ID 名を使い、複数の単語はハイフンで分割します。キャメルケース (camelCase) は使いません。</p> + +<p>良い:</p> + +<pre class="brush: html example-good notranslate"><p class="editorial-summary">Blah blah blah</p></pre> + +<p>悪い:</p> + +<pre class="brush: html example-bad notranslate"><p class="bigRedBox">Blah blah blah</p></pre> + +<h3 id="Entity_references" name="Entity_references">実体参照</h3> + +<p>実体参照を必要以上に使わない — リテラル文字を可能であれば使いましょう (角括弧や引用符のような記号は、まだエスケープが必要です) 。</p> + +<p>単純に書ける例</p> + +<pre class="brush: html example-good notranslate"><p>© 2018 Me</p></pre> + +<p>以下のようにも書けますが、</p> + +<pre class="brush: html example-bad notranslate"><p>&copy; 2018 Me</p></pre> + +<p>UTF-8 文字セットで記述する限りは問題ありません。</p> + +<h2 id="Good_HTML_examples_on_MDN" name="Good_HTML_examples_on_MDN">MDN での良い HTML の例</h2> + +<p>優良で、簡潔で、有意義な HTML のスニペットを <a href="/ja/docs/Web/HTML/Reference">HTML リファレンス</a> の先頭で見つけることができます — 対話形式の例は一般的にこれらのガイドラインに従って書かれていますが、ガイドラインが新規に書かれる前に大部分が書かれているので、いくつかの箇所は異なっているのに気をつけてください。</p> diff --git a/files/ja/mdn/guidelines/code_guidelines/index.html b/files/ja/mdn/guidelines/code_guidelines/index.html new file mode 100644 index 0000000000..3ce931004f --- /dev/null +++ b/files/ja/mdn/guidelines/code_guidelines/index.html @@ -0,0 +1,80 @@ +--- +title: Code example guidelines +slug: MDN/Guidelines/Code_guidelines +tags: + - CSS + - Code + - Guide + - Guidelines + - HTML + - JavaScript + - MDN Meta + - NeedsTranslation + - Shell + - TopicStub +translation_of: MDN/Guidelines/Code_guidelines +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<div> +<p class="summary"><span class="seoSummary">This document series outlines the coding guidelines and best practices we use for writing demos, code snippets, interactive examples, etc, for use on MDN.</span></p> + +<p>If you are looking for guidelines to follow when writing your code examples, you have come to the right place. The biggest advantage to adhering to these guidelines is that it will foster consistency across our samples and demos on MDN, which increases readability and comprehension overall.</p> +</div> + +<div class="note"> +<p><strong>Note</strong>: If you want advice on the styling of code as it appears on an MDN article, rather than the code content, see our <a href="/en-US/docs/MDN/Contribute/Guidelines/Writing_style_guide#Code_sample_style_and_formatting">Writing style guide</a>.</p> +</div> + +<h2 id="Article_structure">Article structure</h2> + +<p>This article contains general high-level best practices for writing MDN code examples. Its subarticles are as follows:</p> + +<ul> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/General">General guidelines for all code</a> — both syntactical and for styling/displaying examples</li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML">HTML guidelines</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS">CSS guidelines</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/JavaScript">JavaScript guidelines</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/Shell">Shell prompt guidelines</a></li> +</ul> + +<h2 id="General_best_practices">General best practices</h2> + +<p>This section provides quick general best practices for creating an understandable minimal code sample to demonstrate usage of a specific feature or function.</p> + +<p>Code samples need to be:</p> + +<ul> + <li>simple enough to be understandable, but</li> + <li>complex enough to do something interesting, and preferably useful.</li> +</ul> + +<p>There is one overarching consideration that you need to keep in mind: <strong>Readers will copy and paste the code sample into their own code, and may put it into production.</strong></p> + +<p>Therefore, you need to make sure that the code example is usable and follows generally accepted best practices, and <strong>does not</strong> do anything that will cause an application to be insecure, grossly inefficient, bloated, or inaccessible. If the code example is not runnable or production-worthy, be sure to include a warning in a code comment and in the explanatory text — if it is a snippet and not a full example, make this clear. This also means that you should provide <strong>all</strong> of the information necessary to run the example including any dependencies and setup.</p> + +<p><span class="author-g-frc9o9ihh5c9qyd0">Code samples should be as self-contained and easy to understand as possible. The aim is not necessarily to produce efficient, clever code that impresses experts and has great functionality, but rather to produce reduced working examples that can be understood as quickly as possible.</span></p> + +<ul> +</ul> + +<div id="magicdomid13"><span class="author-g-frc9o9ihh5c9qyd0">Guidelines:</span></div> + +<div id="magicdomid14"> </div> + +<div id="magicdomid15"> +<ul> + <li><span class="author-g-frc9o9ihh5c9qyd0">The sample should be short and ideally only show the feature you are immediately interested in.</span></li> + <li><span class="author-g-frc9o9ihh5c9qyd0"><strong>Only</strong> include code that is essential for the example. A large amount of non-relevant code can easily distract or confuse the audience. If you want to provide a full, more lengthy, example put it in one of our <a href="https://github.com/mdn/">Github repos</a> (or a JSBin, Codepen, or similar) and then provide the link to the full version above or below the sample.</span></li> + <li><span class="author-g-frc9o9ihh5c9qyd0">Don't include unnecessary server-side code, libraries, frameworks, preprocessors, and other such dependencies — they make the code less portable, and harder to run and understand. Use vanilla code where possible.</span></li> + <li><span class="author-g-frc9o9ihh5c9qyd0">Don't assume knowledge of any libraries, frameworks, preprocessors, or other non-native features. For example, use class names that make sense within the example rather than classnames that make sense to BEM or Bootstrap users.</span></li> + <li><span class="author-g-frc9o9ihh5c9qyd0">Write your code as cleanly and understandably as possible, even if it is not the most efficient way to do it.</span></li> + <li><span class="author-g-frc9o9ihh5c9qyd0">Don't use bad practices for brevity (such as presentational elements like {{HTMLElement("big")}} or {{domxref("Document.write", "document.write()")}}); do it correctly.</span></li> + <li><span class="author-g-frc9o9ihh5c9qyd0">In the case of API demos, if you are using multiple APIs together point out what APIs are included, and what features come from where.</span></li> +</ul> +</div> + +<ul> +</ul> diff --git a/files/ja/mdn/guidelines/conventions_definitions/index.html b/files/ja/mdn/guidelines/conventions_definitions/index.html new file mode 100644 index 0000000000..74b90bcc78 --- /dev/null +++ b/files/ja/mdn/guidelines/conventions_definitions/index.html @@ -0,0 +1,201 @@ +--- +title: MDN の慣習と定義 +slug: MDN/Guidelines/Conventions_definitions +tags: + - MDN + - MDN Meta + - ガイド + - ガイドライン + - ドキュメント +translation_of: MDN/Guidelines/Conventions_definitions +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p class="summary">この記事では MDN で使用されている慣習や定義、特に文書化する際に人によっては忘れがちなものを紹介します。</p> + +<h2 id="Definitions" name="Definitions">定義</h2> + +<h3 id="Deprecated_and_obsolete" name="Deprecated_and_obsolete">非推奨と廃止</h3> + +<p><strong>非推奨</strong>や<strong>廃止</strong>は技術や仕様書によく使われている言葉ですが、どのような意味でしょうか？</p> + +<dl> + <dt><ruby>非推奨<rp> (</rp><rt>Deprecated</rt><rp>)</rp></ruby></dt> + <dd>MDN において<strong>非推奨</strong> の用語は、もう推奨されないものの、まだ実装されており動作する可能性がある API や技術を示すために使用されます。最近では、 <a href="https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md#status-information">browser-compat-data プロジェクト</a>の中で使用される定義を、「その機能はもう推奨されません。将来は削除されるか、互換性のためだけに温存される可能性があります。この機能を使用することは避けてください。」と更新しました。</dd> + <dt><ruby>廃止<rp> (</rp><rt>Obsolete</rt><rp>)</rp></ruby></dt> + <dd>MDN において<strong>廃止</strong> の用語は、もう推奨されないだけでなく、ブラウザーでももう実装されていない API や技術を示すために使用されます。しかし、これは混乱しやすもののです。 — 非推奨に似ており、区別することがさほど役立たない (こちらも本番サイトでは使用するべきではない) ものです。従って、私たちはこれを使用するのをやめ、使用されている記述を削除するか、非推奨に置き換えるかしてください。</dd> +</dl> + +<h3 id="Experimental" name="Experimental">実験的</h3> + +<p><ruby><strong>実験的</strong><rp> (</rp><rt>Experimental</rt><rp>) </rp></ruby>は、聞いた場所や読んだ場所の文脈によって意味が異なる可能性があります。 MDN においてある技術が実験的と記述されている場合、その技術は生まれたばかりで未熟であり、現在ウェブプラットフォームへの追加手続の途中の (または追加が検討されている) 段階であることを意味します。</p> + +<p>次の一方または両方が成り立つ場合です。</p> + +<ul> + <li>実装し、既定で有効になっている主要なブラウザーが二つ未満であること。</li> + <li>仕様の記述が安定しておらず、大きく変わる可能性があること。従って、仕様書の変更によって、将来の版のブラウザーで構文や動作が変更する可能性があること。</li> +</ul> + +<p>これらの定義のうちの一方または両方が成り立つ場合、その技術を様々な種類の製品プロジェクト (つまり、単なるデモまたは実験ではない場合) に使用する前に慎重に考えなければなりません。実験的の定義については、 <a href="https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md#status-information">browser-compat-data プロジェクト</a>も参照してください。</p> + +<p>逆に、以下のような場合は実験的とは言いません。</p> + +<ul> + <li>二つ以上の主要なブラウザーで実装されている。または、</li> + <li>仕様の定義が安定していて、変化しそうにない。</li> +</ul> + +<p>ここでは<em>または</em>が重要です。 — 通常、ある技術に複数の主要なブラウザーが対応した場合、仕様は安定するでしょうが、これは常に言えるわけではありません。また、技術によっては安定した仕様書がありよく使用されてはいるものの、ブラウザーでのネイティブな対応がない場合もあります (<a href="/en-US/docs/Related/IMSC">IMSC</a> などがその例)。</p> + +<h3 id="Archived_pages" name="Archived_pages">アーカイブページ</h3> + +<p>アーカイブページは、 MDN の<a href="/ja/docs/Archive">古いコンテンツのアーカイブ</a>に保存されているページです。これらのページには古くなった情報が含まれているため、他の人にとっては直接役に立ちません。</p> + +<p>最も一般的なのは、これらは廃止されてもはや信頼されるべきではない Mozilla プロジェクトに関係します。しかし、それらは有用な歴史的記録を形成するのでそれらを単純に削除するのではなく、その中に含まれるパターンやアイデアのいくつかは将来の作業に役立つかもしれません。 良い例は <a href="/ja/docs/Archive/B2G_OS">B2G (Firefox OS) プロジェクト</a>です。</p> + +<h4 id="When_should_a_page_be_archived" name="When_should_a_page_be_archived">どのような時にページをアーカイブするか？</h4> + +<p>ページをアーカイブするべきである場合は、ページが上記の説明に合う場合です。ページをアーカイブするには、[ページ移動]機能 ([詳細] - [この記事を移動]) を使用して、ページを[アーカイブ]ページツリー (/ja/docs/Archive) に移動します。この機能を使用する権限がない可能性があります。ページのアーカイブを開始する前に、まず MDN コミュニティと話し合う必要があります - <a href="https://discourse.mozilla.org/c/mdn">ディスカッションフォーラム</a>で私たちに相談してください。</p> + +<h3 id="Deleted_pages" name="Deleted_pages">削除されたページ</h3> + +<p>削除されたページは、 MDN から明示的に削除されたページです - 例えば <code><a href="/ja/docs/Web/API/SharedKeyframeList">SharedKeyframeList</a></code> インターフェイスと <code><a href="/ja/docs/Web/API/SharedKeyframeList/SharedKeyframeList">SharedKeyframeList()</a></code> コンストラクターを見てください。 これらのページには、もはや有用ではない情報が含まれています。また、利用可能にしておくと混乱したり、知っていたりすることが不適切な場合もあります。</p> + +<p>次のようなものが該当する可能性があります。</p> + +<ul> + <li>ブラウザーに実装される前に仕様から削除された API 機能のリファレンスページ</li> + <li>後で悪い手法であることが示され、より良い技術によって置き換えられた手法をカバーする記事</li> + <li>後で他のより質の高い記事に置き換えられた情報を含む記事</li> + <li>MDN に不適切なコンテンツを含む記事</li> + <li>古く、時代遅れで、修正が難しい翻訳記事で、すなわち英語版が推奨されて翻訳し直した方が簡単である場合</li> +</ul> + +<h4 id="When_should_a_page_be_deleted" name="When_should_a_page_be_deleted">どのような時にページを削除するか</h4> + +<p>上記の説明に合う場合はページを削除する必要があります。ページを削除するには、[このページを削除] 機能 ([詳細設定] > [このページを削除]) を使用してページを削除します。あなたはおそらくこの機能を使う権限を持っていないでしょう、そしてページを削除することを考えるときあなたは最初にそれを MDN コミュニティと議論するべきです - <a href="https://discourse.mozilla.org/c/mdn">ディスカッションフォーラム</a>で私たちに相談してください。</p> + +<h3 id="When_to_document_new_technologies" name="When_to_document_new_technologies">新しい技術を記述するとき</h3> + +<p>MDN では、新しいウェブ標準技術を適切に文書化することを常に検討しています。私達は、開発者が必要なときにすぐに新機能について学ぶことができるように文書を十分に早く公開することと、定期的に更新したり迅速に削除したりする必要がないように技術が成熟し安定したものになるように十分に遅く公開することのバランスをとるようにしています。</p> + +<p>一般的に、新しい技術を文書化することを検討する最も早い定義は、次のとおりです。</p> + +<p><em>「この機能が標準化過程にあり、どこかで実装されている場合」</em></p> + +<p>新しい技術を文書化することを絶対的に考えるべきであるのは以下のような場合です。</p> + +<ul> + <li>信頼できる標準化団体 (W3C、WHATWG、Khronos、IETFなど) の下で公開された仕様書で指定されており、妥当なレベルの安定性に達している (例えば、 W3C のワーキングドラフトや候補者の勧告、あるいはそれに対して提起された問題の流れから判断すると、仕様はかなり安定しているように見えます)</li> + <li>他のブラウザー開発者が興味を引く兆しを見せており、少なくとも1つのブラウザーで一貫して実装されている場合 (有効なチケットや「実装」プロセスなど)</li> +</ul> + +<p>次のような場合は、新しいテクノロジを文書化することにもっと慎重になるべきです (ただし、意味がある場合はそれを考慮する必要があります)。</p> + +<ul> + <li>仕様書がない、あるいは、変更するべきであるような大まかなメモでしかない場合</li> + <li>現在それを実装しているブラウザーがゼロまたは1種類であり、対応していないブラウザーが実装する様子を見せていない場合 (それらのブラウザーの開発をしているエンジニアに尋ねたり、ブラウザーのバグトラッカーやメーリングリストなどを調べたりすることで評価することができます)。</li> +</ul> + +<p>次のような場合は、その新しい技術を文書化しようと考えないでください。</p> + +<ul> + <li>ウェブに公開された技術ではない場合や、完全に私有の技術である場合</li> + <li>すでに非推奨になっている、または同様の機能によって置き換えられる見込みがある</li> +</ul> + +<h2 id="Conventions" name="Conventions">慣習</h2> + +<h3 id="When_something_is_removed_from_the_specification" name="When_something_is_removed_from_the_specification">何かが仕様書から削除されたとき</h3> + +<p>新しい仕様の開発中や、 HTML のようなリビングスタンダードの進化の過程で、新しい要素、メソッド、プロパティなどが仕様書に追加され、しばらく存在してから削除されることが時々あります。これはとても速い周期で行われることもあれば、新しい項目が仕様書に数か月から数年の間、削除されずに残っていることもあります。これによって、仕様書から項目が削除されたと判断することが難しくなっています。どうするべきかを決める参考となるガイドラインをいくつか紹介します。</p> + +<div class="note"> +<p>ここでは「項目」という単語を、仕様書の一部になりうるものすべてを示す意味で使用しています。要素や要素の属性、インターフェイスや個々のメソッド、プロパティ、またはインターフェイスの他のメンバーなどがこれに該当します。</p> +</div> + +<ul> + <li>その項目が<em>どの</em>ブラウザーのリリース版でも<em>決して</em>実装されていない場合 — 設定やフラグで隠されている場合を含めて — 単純にその項目のリファレンスを文書から削除してください。 + + <ul> + <li>If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), delete that page. If the removed item is an interface, this means removing any subpages describing the properties and methods on that interface as well.</li> + <li>Remove the item from any lists of properties, attributes, methods, and so forth. For methods of an interface, that means to remove it from the "Methods" section on the interface's overview page, for example.</li> + <li>Search the text of the overview page for that interface, element, etc. for any references to the removed item. Remove those references, being sure not to leave weird grammar issues or other problems with the text. This may mean not just deleting words but rewriting a sentence or paragraph to make more sense. It may also mean removing entire sections of content if the description of the item's use is lengthy.</li> + <li>Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Remove those references, being sure not to leave weird grammar issues or other problems with the text. This may mean not just deleting words but rewriting a sentence or paragraph to make more sense. It may also mean removing entire sections of content if the description of the item's use is lengthy.</li> + <li>Search MDN for references to the removed item, in case there are discussions elsewhere. It's unlikely that there are, since if it was never implemented, it's unlikely to be widely discussed. Remove those mentions as well.</li> + <li>If the <a href="https://github.com/mdn/browser-compat-data">Browser Compatibility Data repository's</a> JSON files contain data for the removed items, delete those objects from the JSON code and submit a PR with that change, explaining why in the commit message and the PR description. Be careful to check that you don't break the JSON syntax while doing this.</li> + </ul> + </li> + <li>アイテムが1つ以上のブラウザーのリリースバージョンに実装している場合 — ただし、設定またはフラグの背後に<em>のみ </em>— ドキュメントからすぐに削除しないでください。代わりに、次のように非推奨としてアイテムをマークします: + <ul> + <li>If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), add the {{TemplateLink("deprecated_header")}} macro to the top of the page and add the {{tag("Deprecated")}} tag to the page's list of tags.</li> + <li>On the overview page for the element, interface, or API, find the list of items which includes the item that's been removed from the specification and add the {{TemplateLink("deprecated_inline")}} macro after the item's name in that list.</li> + <li>Search the informative text of the overview page for that interface, element, etc. for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "[whatever] has been removed from the specification and will be removed from browsers soon. See [link to page] for a new way to do this."</li> + <li>Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings.</li> + <li>Search MDN for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well.</li> + <li>At some point in the future, a decision may be made to actually remove the item from the documentation; we don't normally do this but if the item was especially unutilized or uninteresting, we may decide to do so.</li> + <li>Update any relevant entries in the <a href="https://github.com/mdn/browser-compat-data">Browser Compatibility Data repo</a> to reflect the obsolescence of the item(s) affected.</li> + </ul> + </li> + <li>アイテムがブラウザーの1つ以上のリリースビルドで実装された場合 — 設定やフラグを変更する必要な し— 次のように、アイテムを非推奨としてマークします: + <ul> + <li>If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), add the {{TemplateLink("deprecated_header")}} macro to the top of the page and add the {{tag("Deprecated")}} tag to the page's list of tags.</li> + <li>On the overview page for the element, interface, or API, find the list of items which includes the item that's been removed from the specification and add the {{TemplateLink("deprecated_inline")}} macro after the item's name in that list.</li> + <li>Search the informative text of the overview page for that interface, element, etc. for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "[whatever] has been removed from the specification and is deprecated. It may be removed from browsers in the future, so you should not use it. See [link to page] for a new way to do this."</li> + <li>Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings.</li> + <li>Search MDN for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well.</li> + <li>It's unlikely that these items will be removed from the documentation anytime soon, if ever. It's possible, however, that some or all of the material may be moved to the <a href="/ja/docs/Archive">Archive</a> section of the site.</li> + <li>Update any relevant entries in the <a href="https://github.com/mdn/browser-compat-data">Browser Compatibility Data repo</a> to reflect the deprecation of the item(s) affected.</li> + </ul> + </li> +</ul> + +<p>Please use common sense with wording of warning messages and other changes to text suggested by the guidelines above. Different items will require different wording and handling of the situation. When in doubt, feel free to ask for advice on the <a href="https://chat.mozilla.org/#/room/#mdn:mozilla.org">MDN Web Docs chat room</a> on <a href="https://wiki.mozilla.org/Matrix">Matrix</a>, or on the <a href="https://discourse.mozilla.org/c/mdn">MDN Web Docs discussion forum</a>.</p> + +<h3 id="Copying_content_within_MDN" name="Copying_content_within_MDN">MDN 内でのコンテンツのコピー</h3> + +<p>ときどき、複数のページで同じテキストを再利用する必要が生じる場合 (または、あるページを別のページのテンプレートとして利用したい場合) があります。その場合、3つの選択肢があります。</p> + +<ul> + <li>ページ全体をコピーしたい場合。 + <ol> + <li>コピーしたいページを閲覧中に、<strong>詳細</strong>（歯車）メニュー内にある、 <strong><a href="/ja/docs/MDN/Contribute/Creating_and_editing_pages#Clone_of_an_existing_page">この記事を複製</a></strong>を選んで下さい。新しいページのエディターのユーザーインターフェイスが、複製されたページの内容がすでに入った状態で開かれます。</li> + <li>新しい<strong>タイトル</strong>と<strong>スラグ</strong>を、複製したページに入力します。</li> + <li>必要に従ってページを編集し、通常と同じように保存します。</li> + </ol> + </li> + <li>ページの一部分だけをコピーしたい場合は、<strong>ページの単純なコピーアンドペーストはやめて下さい。</strong>余計な HTML の断片を作成中のページに埋め込むことになり、誰かが片付けをすることになります。あなたかもしれないし、他の編集者かもしれませんが、誰もそんなことやりたくありません。 MDN のページの一部をコピーする場合、 + <ol> + <li>ソースページで、<strong>編集</strong>ボタンをクリックします。</li> + <li><strong>エディターの UI の中で再利用したい部分をコピーします。</strong></li> + <li><strong>変更を破棄</strong>をクリックして、エディターの UI を終了します。</li> + <li>貼り付けしたいページのエディターの UI を開きます。</li> + <li>内容をクリップボードから貼り付けします。</li> + </ol> + + <div class="note"><strong>Chrome を使用している方へ:</strong> Chrome では一般的に、エディターで文書をコピーして貼り付けた際に、コンテンツに適用されるクラスが含まれません。これを行った後にコンテンツを確認し、失われたスタイルを再適用する必要があります。特にテーブル、構文ボックス、構文の強調表示、コンテンツの非表示部分をチェックしてください。</div> + </li> + <li>文字通り、同じコンテンツを多くのページに利用したい場合もあるかもしれません。そんな時は、そのコンテンツを一つのページにまとめてしまうのがいいかもしれません。そして {{TemplateLink("Page")}} マクロを利用して、一つのページから他のページへ素材を転写しましょう。こうすると、参照元のページが更新されると、参照先のページの内容も同様に更新されます（これは強制的に更新したり、参照先のページが定期的に再構築されたりした際に起こります）。</li> +</ul> + +<h4 id="Copying_content_from_elsewhere" name="Copying_content_from_elsewhere">他の場所からの内容のコピー</h4> + +<p>多くの場合、MDN 以外にも Web 上のどこかにトピックに関する有用なコンテンツがあります。しかし、そのようなコンテンツをコピーすることは、法的にも技術的にも困難を伴うことがあります。</p> + +<p>技術的なレベルでは、検索エンジンは通常他の場所で利用可能なコンテンツを再生するために彼らのランキングでサイトにペナルティを課します。したがって、MDN のコンテンツの検索エンジンのランキングを向上させるために、MDN にオリジナルのコンテンツを含めることが好ましいです。MDN から既存のコンテンツにリンクできます。</p> + +<p>法的なレベルでは、あなたはコンテンツを寄付する権限を与えられなければならず、そしてそれは <a href="/ja/docs/MDN/About#Copyrights_and_licenses">MDN のライセンス</a>と互換性のある方法でライセンスされそして帰属しなければなりません。</p> + +<ul> + <li><strong>既存のコンテンツを作成し</strong> (あなた自身の目的のためであり、仕事用としてではなく)、それを MDN のライセンスの下で MDN に寄付する意思がある場合、これが最も簡単なケースであり、自由にコンテンツを寄付できます</li> + <li><strong>コンテンツの著作権が他の人に帰属する場合</strong>、それは MDN のライセンスと互換性があるようにライセンスされている必要があります。弁護士ではない人にとって、互換性のあるライセンスを判断するのは容易ではありません。安全のため、必要に応じて <a href="https://wiki.mozilla.org/MDN#Staff_Team">MDN スタッフチーム</a>のメンバーに連絡してください</li> +</ul> + +<h4 id="How_to_communicate_a_spec_conflict" name="How_to_communicate_a_spec_conflict">仕様書が競合したときの調整方法</h4> + +<p>なお、時々 (まれに) 仕様書の異なるバージョン (特に W3C と WHATWG) が競合することがあり、例えば一方のバージョンがある機能を非推奨とする一方で、もう一方が非推奨にしない場合などがあります。このような場合、何が真実なのか — 例えば、ブラウザーは実際にどうしているか — を考慮し、「重要」なメモを書いて最新の状態を要約してください。例えば、2019年1月時点の <code><a href="/ja/docs/Web/HTML/Global_attributes/inputmode">inputmode</a></code> グローバル属性には競合があり、次のように要約されています。</p> + +<div class="blockIndicator warning"> +<p><strong>仕様の競合</strong>: <a href="https://html.spec.whatwg.org/multipage/interaction.html#attr-inputmode">WHATWG の仕様書では <code>inputmode</code> を記述しており</a>、最近のブラウザーでは対応の方向に向かっています。しかし、 <a href="https://www.w3.org/TR/html52/index.html#contents">W3C HTML 5.2 spec</a> は仕様に含めるのをやめています (すなわち廃止扱いにしています)。合意に至るまでは、 WHATWG の定義が正しいとみなすべきでしょう。</p> +</div> diff --git a/files/ja/mdn/guidelines/css_style_guide/index.html b/files/ja/mdn/guidelines/css_style_guide/index.html new file mode 100644 index 0000000000..9fbeb620ef --- /dev/null +++ b/files/ja/mdn/guidelines/css_style_guide/index.html @@ -0,0 +1,861 @@ +--- +title: MDN のコンテンツで使われるクラスとスタイルのガイド +slug: MDN/Guidelines/CSS_style_guide +tags: + - Guide + - MDN + - MDN Meta + - ガイド + - ガイドライン + - クラス + - スタイル +translation_of: MDN/Guidelines/CSS_style_guide +--- +<p>{{MDNSidebar}}</p> + +<p class="summary"><span class="seoSummary">MDN には数多くの組み込みのグローバルスタイルがあって、記事のスタイル付けやレイアウトの際に使用することができ、この記事では利用可能なクラスとその使用方法を説明します。</span></p> + +<p>これらのスタイルの一部は、 MDN エディタのツールバーからアクセスできます。このような場合、スタイルの見出しの下に「ツールバーで編集」という表示と、関連するツールバーのボタンの画像を含めます。</p> + +<p>これらのスタイルは、記事内容のスタイリング中に発生する最も一般的な状況をカバーするように開発されているので、可能な限り使用可能なクラスを使用するようにしてください。標準的なコンテンツのルックアンドフィールからの分岐が多すぎると、一貫性や可読性を損ないます。あなたのページが絶対に特別なカスタムスタイリングを必要としていると感じたら、まず <a href="https://discourse.mozilla.org/c/mdn">MDN Discourse フォーラム</a>でその話題を切り出す必要があります。</p> + +<div class="blockIndicator note"> +<p><strong>注</strong>: 特定のクラスが MDN で使用されている場所を検索する場合は、<code>https://developer.mozilla.org/ja/search?locale=en-US&css_classnames=<var>desired-css-class</var></code> という形式の URL を使用して検索できます。たとえば、 Google のカードグリッドレイアウトを使用するページを見つけるには、URL <a href="https://wiki.developer.mozilla.org/ja/search?locale=*&css_classnames=card-grid">https://wiki.developer.mozilla.org/ja/search?locale=*&css_classnames=card-grid</a> を試してください。</p> +</div> + +<div class="blockIndicator warning"> +<p><strong>重要</strong>: このガイドは不完全です。完成させるための手助けをする方法については、{{anch("Updating this guide", "このガイドの更新")}}を参照してください。</p> +</div> + +<h2 id="Inline_styles" name="Inline_styles">インラインスタイル</h2> + +<p>この節では、 MDN のスタイルコンテンツブロックで使用できるインラインスタイルを示します。</p> + +<h3 id=".button"><code>.button</code></h3> + +<p>任意の要素に MDN のボタンとしてスタイル付けします。通常はリンクをスタイル付けするために使用されます (セキュリティ上の理由で、 {{HTMLElement("button")}} 要素は記事のソースコードから削除されます)。</p> + +<p><a class="button" href="https://github.com/mdn/simple-web-worker/archive/gh-pages.zip">Download source code</a></p> + +<details> +<h4 id="構文例">構文例</h4> + +<pre class="brush: html notranslate"><a href="https://github.com/mdn/simple-web-worker/archive/gh-pages.zip" class="button">Download source code</a></pre> +</details> + +<h3 id=".external-icon_and_.ignore-external" name=".external-icon_and_.ignore-external"><code style="white-space: nowrap;">.external-icon</code> および <code style="white-space: nowrap;">.ignore-external</code></h3> + +<p>MDN の外部にあるコンテンツへのリンクは、 <code style="white-space: nowrap;">external-icon</code> クラスが追加されるように自動的に構成され、サイトから離れることを示すアイコンが作成されます。しかし、このアイコンが望ましくなく、他のスタイルと干渉することがあります。これはリンクに <code style="white-space: nowrap;">ignore-external</code> クラスを追加することで削除できます。</p> + +<div class="blockIndicator note"> +<p><strong>注:</strong> ほとんどの場合、これらを使用することは望ましくありません。 <code style="white-space: nowrap;">.external-icon</code> が自動的に追加されるのは、ユーザーが知らずに MDN から離れるのを防ぐためです。一般的に受け入れられる利用例は唯一、サンプルコードやその他のサービスに使用するもののような、 MDN に固有のドメインやサブドメインへリンクする場合のみです。</p> +</div> + +<p><a href="/">MDN 内部へのリンク</a><br> + <a href="http://wikipedia.org">MDN から離れるリンク</a><br> + <a class="ignore-external" href="http://wikipedia.org">MDN から離れるリンクに <code style="white-space: nowrap;">ignore-external</code></a> を付けたもの</p> + +<details> +<h4 id="Example_syntax_2" name="Example_syntax_2">構文例</h4> + +<pre class="brush: html notranslate"><a href="/">Link to MDN</a> +<a href="http://wikipedia.org">Link away from MDN</a> +<a href="http://wikipedia.org" class="ignore-external">Link away from MDN with <code>ignore-external</code></a></pre> +</details> + +<h3 id=".glossaryLink"><code>.glossaryLink</code></h3> + +<p>これは用語集へのリンクをスタイル付けするためのもので、ページ上であまり目立たなくするためのものです。このクラスは、<a href="/ja/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros#Creating_a_single_hyperlink">よく使われるマクロ</a>で説明したように、 KumaScript マクロを使用して追加されるため、手動では挿入されません。</p> + +<p>{{Glossary("HTML")}}</p> + +<details> +<h4 id="Example_macro_syntax" name="Example_macro_syntax">マクロの構文例</h4> + +<p>\{{Glossary("HTML")}}</p> +</details> + +<h3 id=".hidden"><code>.hidden</code></h3> + +<p>コンテンツを Wiki の記事内では非表示にし、エディター内では表示するようにすることができます。これは HTML, CSS, JavaScript を使用してライブコードサンプルを提供しつつ、読者には関連する言語のみを表示するようにするようにすることができます。</p> + +<details> +<h4 id="Example_syntax_3" name="Example_syntax_3">構文例</h4> + +<pre class="brush: html notranslate"><h4 id="Hidden_Code_Sample" name="Hidden_Code_Sample">Hidden code Sample</h4> + +<div class="hidden"> +<h5 id="HTML">HTML</h5> + +<pre class="brush: html;"> +&lt;button id="test"&gt; Click me &lt;/button&gt; + +<h5 id="CSS">CSS</h5> + +<pre class="brush: css;"> +button { + background-color: #a00; + color:#fff; + font-size: 20px; +} +</pre> +</div> + +<h5 id="JavaScript_Content">JavaScript Content</h5> + +<pre class="brush: js;"> +document.getElementById("test").addEventListener("click", works); +function works() { + window.alert("you clicked it!"); +} +</pre> + +<p>\{{EmbedLiveSample("Hidden_Code_Sample")}}</p> +</pre> + +<h4 id="Hidden_Code_Sample" name="Hidden_Code_Sample">非表示コードサンプル</h4> + +<div class="hidden"> +<h5 id="HTML">HTML</h5> + +<pre class="brush: html notranslate"><button id="test">Click Me</button> +</pre> + +<h5 id="CSS">CSS</h5> + +<pre class="brush: css notranslate">button{ + background-color: #a00; + color:#fff; + font-size: 20px; +} +</pre> +</div> + +<h5 id="JavaScript">JavaScript</h5> + +<pre class="brush: js notranslate">document.getElementById("test").addEventListener("click", works); +function works(){ + window.alert("you clicked it!"); +} +</pre> + +<p>{{EmbedLiveSample("Hidden_Code_Sample", "100%", 150)}}</p> +</details> + +<h3 id=".seoSummary"><code>.seoSummary</code></h3> + +<p>これはページ上のコンテンツに目に見える効果を与えないクラスですが、しかし、クラスが要素 (通常は {{HTMLElement("span")}}) に適用されている場合、 KumaScript は要素のコンテンツを使用して <code>description</code> の {{HTMLElement("meta")}} タグを生成します。これらは短い説明を提供し、これは検索エンジン、 Facebook や Twitter のような共有サイトなどで使用されます。このクラスは、 MDN エディターの WYSIWYG スタイルドロップダウンメニューの [SEO Summary] オプションで利用できます。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11859/seosummary-menu-option.png" style="border: 1px solid black; display: block; height: 58px; margin: 0px auto; width: 235px;"></p> + +<details> +<div class="blockIndicator note"> +<p><strong>注</strong>: <code>.seoSummary</code> がページに明示的に指定されていない場合、最初の段落が自動的に SEO の要約として設定されます。ほとんどのページでは、これを使用する必要はありません。</p> +</div> + +<p>最後のページの画面にはスタイルの変更は表示されませんが、 SEO サマリーとして設定されたテキストには次のように点線のアウトラインと "SEO Summary" ラベルが表示されます。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11861/seosummary-editor-representation.png" style="display: block; margin: 0 auto;"></p> + +<p>以下の例は、 <a href="/ja/docs/Mozilla/Add-ons">Mozilla のアドオン</a>ページから抜粋したものです。</p> + +<h3 id="Example_syntax_4" name="Example_syntax_4">構文例</h3> + +<pre class="brush: html notranslate"><p> + <span class="seoSummary">Add-ons add new functionality to <a href="/en-US/docs/Mozilla/Gecko">Gecko</a>-based applications such as Firefox, SeaMonkey, and Thunderbird.</span> + There are two main types of add-on: <a href="#Extensions">Extensions</a> add new features to the application, while <a href="#Themes">Themes</a> modify the application's user interface. +</p></pre> + +<h4 id="Example_of_the_generated_HTMLElementmeta_elements" name="Example_of_the_generated_HTMLElementmeta_elements">生成された {{HTMLElement("meta")}} 要素の例</h4> + +<pre class="brush: html; notranslate"><meta property="og:description" content="Add-ons add new functionality to Gecko -based applications such as Firefox, SeaMonkey, and Thunderbird."> +<meta name="description" content="Add-ons add new functionality to Gecko -based applications such as Firefox, SeaMonkey, and Thunderbird."> +<meta name="twitter:description" content="Add-ons add new functionality to Gecko -based applications such as Firefox, SeaMonkey, and Thunderbird."></pre> + +<h4 id="Example_of_how_Facebook_uses_it" name="Example_of_how_Facebook_uses_it">Facebook の使い方の例</h4> + +<p><img alt="SEOSummary as it is used by Facebook" src="https://mdn.mozillademos.org/files/11857/seosummary.jpg" style="display: block; height: 338px; margin: 0px auto; width: 500px;"></p> +</details> + +<div class="blockIndicator note"> +<p><strong>注:</strong> これは特別な "About this page" スタイルの blurb ボックスを作成する <code>{{anch(".summary")}}</code> クラスと同じではありません。そのクラスは、検索エンジンで使用される SEO サマリーや、MDN がツールチップを生成するために使用するマクロ、およびサブページをリストするメニューを自動的に生成するマクロを設定しません。</p> +</div> + +<h2 id="Block_level_styles" name="Block_level_styles">ブロックレベルスタイル</h2> + +<p>このセクションでは、MDN のスタイルコンテンツブロックで使用可能なブロックレベルのスタイルを示します。</p> + +<h3 id=".callout-box"><code style="white-space: nowrap;">.callout-box</code></h3> + +<p>コールアウト、またはハイライトしたい関連情報を格納するための右浮動ボックスを作成できます。</p> + +<div class="callout-box"> +<p>これはエキサイティングな吹き出しです</p> +</div> + +<p>浮遊するコンテンツの例</p> + +<p>Mixtape distillery biodiesel pop-up Austin chambray. Fingerstache YOLO tousled, meditation four loko squid brunch single-origin coffee stumptown ethical asymmetrical polaroid Neutra hashtag beard. Mustache Godard Bushwick, Tumblr salvia +1 fixie cornhole beard wayfarers stumptown aesthetic keffiyeh lomo. Meggings lumbersexual keytar Shoreditch.</p> + +<details> +<h4 id="Example_syntax_5" name="Example_syntax_5">構文例</h4> + +<pre class="brush: html notranslate"><div class="callout-box"> + <p>This is an exciting callout</p> +</div> +<p>Example content to float around</p> +<p>Mixtape distillery biodiesel pop-up Austin chambray. Fingerstache YOLO tousled, meditation four loko squid brunch single-origin coffee stumptown ethical asymmetrical polaroid Neutra hashtag beard. Mustache Godard Bushwick, Tumblr salvia +1 fixie cornhole beard wayfarers stumptown aesthetic keffiyeh lomo. Meggings lumbersexual keytar Shoreditch.</p> +</pre> +</details> + +<h3 id=".card-grid"><code style="white-space: nowrap;">.card-grid</code></h3> + +<p>複数のカードを並べて配置すると、特定のコンテンツを呼び出すことや、複数ステップの行動を促すことができます。カードは、利用可能な水平スペース内で均等に配置されています。2〜3個くらいが最適です。</p> + +<ul class="card-grid"> + <li><span>CSS リファレンス</span> + + <p>An <a href="/en-US/docs/Web/CSS/Reference" title="en-US/docs/CSS/CSS_Reference">exhaustive reference</a> for <u>seasoned Web developers</u> describing every property and concept of CSS.</p> + </li> + <li><span>CSS チュートリアル</span> + <p>A <a href="/en-US/docs/CSS/Getting_Started" title="en-US/docs/CSS/Getting_Started">step-by-step introduction</a> to help <u>complete beginners</u> get started. It presents all the needed fundamentals.</p> + </li> + <li><span>CSS3 デモ</span> + <p>A <a href="/en-US/demos/tag/tech:css3" title="https://developer.mozilla.org/en-US/demos/tag/tech:css3">collection of demos</a> showing the <u>latest CSS technologies</u> in action: a boost for the creativity.</p> + </li> +</ul> + +<details> +<h4 id="Example_syntax_6" name="Example_syntax_6">構文例</h4> + +<pre class="brush: html; notranslate"><ul class="card-grid"> + <li>My card content</li> + <li>My second card content</li> + <li>My third card content</li> +</ul></pre> +</details> + +<h3 id=".column-container"><code style="white-space: nowrap;">.column-container</code></h3> + +<p>特定の幅の列のコンテナを示します。通常、以下に示すように他のクラスと組み合わせて使用されます。</p> + +<div class="column-container"> +<div class="column-4"> +<p>１つ目の列</p> +</div> + +<div class="column-4"> +<p>２つ目の列</p> +</div> + +<div class="column-4"> +<p>３つ目の列</p> +</div> +</div> + +<details> +<h4 id="Example_syntax_7" name="Example_syntax_7">構文例</h4> + +<pre class="brush: html notranslate"><div class="column-container"> + <div class="column-4"> + <p>My first equal width column.</p> + </div> + <div class="column-4"> + <p>My second equal width column.</p> + </div> + <div class="column-4"> + <p>My third equal width column.</p> + </div> +</div></pre> +</details> + +<h3 id=".column-1_.column-2_.column-3_..._all_the_way_up_to_.column-11" name=".column-1_.column-2_.column-3_..._all_the_way_up_to_.column-11"><code style="white-space: nowrap;">.column-1</code>, <code style="white-space: nowrap;">.column-2</code>, <code style="white-space: nowrap;">.column-3</code> ... のように上がって <code style="white-space: nowrap;">.column-11</code> まで</h3> + +<p><code style="white-space: nowrap;">.column-container</code> に格納される特定の幅の列を指定します。これは、列コンテナの幅の12分の1 (12列のグリッドレイアウトに基づいています) です。各列のペアの間に溝が残されます。</p> + +<div class="column-container"> +<div class="column-1" style="background-color: yellow;">1/12</div> + +<div class="column-11" style="background-color: lime;">11/12</div> +</div> + +<div class="column-container"> +<div class="column-5" style="background-color: yellow;">5/12</div> + +<div class="column-7" style="background-color: lime;">7/12</div> +</div> + +<div class="column-container"> +<div class="column-6" style="background-color: yellow;">6/12</div> + +<div class="column-4" style="background-color: lime;">4/12</div> + +<div class="column-2" style="background-color: pink;">2/12</div> +</div> + +<details> +<h4 id="Example_syntax_8" name="Example_syntax_8">構文例</h4> + +<pre class="brush: html notranslate"><div class="column-container"> + <div class="column-1" style="background-color: yellow;">1/12</div> + <div class="column-11" style="background-color: lime;">11/12</div> +</div> + +<div class="column-container"> + <div class="column-5" style="background-color: yellow;">5/12</div> + <div class="column-7" style="background-color: lime;">7/12</div> +</div> + +<div class="column-container"> + <div class="column-6" style="background-color: yellow;">6/12</div> + <div class="column-4" style="background-color: lime;">4/12</div> + <div class="column-2" style="background-color: pink;">2/12</div> +</div> +</pre> +</details> + +<h3 id=".column-quarter_.column-third_.column-half"><code style="white-space: nowrap;">.column-quarter</code>, <code style="white-space: nowrap;">.column-third</code>, <code style="white-space: nowrap;">.column-half</code></h3> + +<p><code style="white-space: nowrap;">.column-container</code> によって保持される特定の幅の列を指定します。これは、列コンテナの幅広い部分です。それぞれの列のペアの間にガターが残されます。</p> + +<div class="column-container"> +<div class="column-half" style="background-color: yellow;">Half</div> + +<div class="column-half" style="background-color: lime;">Half</div> +</div> + +<div class="column-container"> +<div class="column-third" style="background-color: yellow;">Third</div> + +<div class="column-third" style="background-color: lime;">Third</div> + +<div class="column-third" style="background-color: pink;">Third</div> +</div> + +<div class="column-container"> +<div class="column-quarter" style="background-color: yellow;">Quarter</div> + +<div class="column-quarter" style="background-color: lime;">Quarter</div> + +<div class="column-quarter" style="background-color: pink;">Quarter</div> + +<div class="column-quarter" style="background-color: cyan;">Quarter</div> +</div> + +<details> +<p>これらのクラスは、次のようなよく使われる数値の幅のクラスと等価なものです。</p> + +<ul> + <li><code style="white-space: nowrap;">.column-quarter</code> — <code style="white-space: nowrap;">.column-3</code> と等価</li> + <li><code style="white-space: nowrap;">.column-third</code> — <code style="white-space: nowrap;">.column-4</code> と等価</li> + <li><code style="white-space: nowrap;">.column-half</code> — <code style="white-space: nowrap;">.column-6</code> と等価</li> +</ul> + +<h4 id="Example_syntax_9" name="Example_syntax_9">構文例</h4> + +<pre class="brush: html notranslate"><div class="column-container"> + <div class="column-half" style="background-color: yellow;">Half</div> + <div class="column-half" style="background-color: lime;">Half</div> +</div> + +<div class="column-container"> + <div class="column-third" style="background-color: yellow;">Third</div> + <div class="column-third" style="background-color: lime;">Third</div> + <div class="column-third" style="background-color: pink;">Third</div> +</div> +<div class="column-container"> + <div class="column-quarter" style="background-color: yellow;">Quarter</div> + <div class="column-quarter" style="background-color: lime;">Quarter</div> + <div class="column-quarter" style="background-color: pink;">Quarter</div> + <div class="column-quarter" style="background-color: cyan;">Quarter</div> +</div> +</pre> +</details> + +<h3 id="<details>"><code><details></code></h3> + +<p>そのコンテンツを隠すためにコンテンツのブロックを囲むことができ、その中に含まれるコンテンツを展開/折りたたむためにクリックすることができる「+詳細」リンクを表示することができます。 あなたはこの記事全体を通して使用されているのを見ることができます。</p> + +<details open> +<h4 id="Example_syntax_10" name="Example_syntax_10">構文例</h4> + +<p>これは、 {{HTMLElement("details")}} で隠された {{HTMLElement("details")}} の構文セクションの例です。おぉ、なんとメタなんでしょう。</p> + +<pre class="brush: html; notranslate"><details> +<h4>Example syntax</h4> +<p>This is an example syntax section for <code>.detail</code> that was hidden with <code>.detail</code>. Ooooooh, how meta.</p> +</details></pre> +</details> + +<h3 id=".example-bad_and_.example-good"><code style="white-space: nowrap;">.example-bad</code> and <code style="white-space: nowrap;">.example-good</code></h3> + +<p>Good と bad の例は、<code>.example-good</code> クラスと <code>.example-bad</code> クラスを使ってハイライトすることができます。これらは通常、サンプルコードスニペットを示す <code><pre></code> ブロックで使用されますが、他のブロックでも使用できます。</p> + +<h5 id="Good_code_example" name="Good_code_example">良いコード例</h5> + +<pre class="brush: html example-good notranslate"><label for="test">Form label:</label> +<input type="text" id="test"> +</pre> + +<h5 id="Bad_code_example" name="Bad_code_example">悪いコード例</h5> + +<pre class="brush: html example-bad notranslate"><input type="text"> +</pre> + +<details> +<p><strong>以下に示すように、これらのクラスでは見出しを常に使用する必要があります。</strong> — CSS はページのローカライズされた言語をページに追加することができないため、スクリーンリーダーを使用するユーザーや文化的背景の異なるユーザーにとって重要です(緑と赤は普遍的に良いと悪いを意味するわけではありません。)</p> + +<h4 id="Example_syntax_11" name="Example_syntax_11">構文例</h4> + +<pre class="brush: html notranslate"><h5 id="Good_code_example">Good code example</h5> + +<pre class="brush: html example-good"> + &lt;label for="test"&gt;Form label:&lt;/label&gt; + &lt;input type="text" id="test"&gt; +</pre> + +<h5 id="Bad_code_example">Bad code example</h5> + +<pre class="brush: html example-bad"> + &lt;input type="text"&gt; +</pre></pre> +</details> + +<h3 id=".moreinfo"><code>.moreinfo</code></h3> + +<p>このクラスはもともと、さらなる読み上げのためのリンクのリストを表示するように設計されていましたが、現在のページから離れていくあらゆる情報に使用できます。</p> + +<div class="moreinfo"> +<h4 id="Tools_to_build_on_your_JavaScript_knowledge" name="Tools_to_build_on_your_JavaScript_knowledge">JavaScript の知識を基に構築するツール</h4> + +<dl> + <dt>JavaScript フレームワーク</dt> + <dd>Developed by Google <a href="https://angularjs.org/">Angular.js</a> is one of the best known frameworks.</dd> + <dd><a href="http://emberjs.com/">Ember.js</a> is open source and community driven.</dd> + <dt>JavaScript コンパイラ</dt> + <dd><a href="https://babeljs.io/">Babel</a> lets you write ES2015 and compiles to more backwards compatible code.</dd> +</dl> +</div> + +<details> +<h4 id="Example_syntax_12" name="Example_syntax_12">構文例</h4> + +<pre class="brush: html notranslate"><div class="moreinfo"> + <!-- content goes here --> +</div></pre> +</details> + +<h3 id=".blockIndicator.note"><code>.blockIndicator.note</code></h3> + +<p>コンテンツのセクションをノートボックスに変換します。これは通常、現在の主題に直接関連する有用なメモであるものの、情報の流れに直接会わないものです。</p> + +<div class="blockIndicator note"> +<p><strong>注</strong>: これは通常、 MDN の記事にメモを表示する方法です。</p> +</div> + +<details> +<p>これは MDN エディタの WYSIWYG スタイルドロップダウンメニューの "Note box" オプションで利用できます。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11677/Screen%20Shot%202015-10-05%20at%2006.56.01.png" style="border: 1px solid black; display: block; margin: 0px auto;"></p> + +<h4 id="Example_syntax_13" name="Example_syntax_13">構文例</h4> + +<pre class="brush: html; notranslate"><div class="blockIndicator note" role="complementary"> + <p><strong>Note</strong>: This is how we usually present a note in an MDN article.</p> +</div></pre> +</details> + +<h3 id=".pull-aside"><code>.pull-aside</code></h3> + +<p>コンテンツを側面に引き出します。</p> + +<div class="pull-aside">側面に移動するいくつかのコンテンツ。</div> + +<p>側面に出てこないコンテンツもあります。</p> + +<details> +<h4 id="Example_Syntax" name="Example_Syntax">構文例</h4> + +<pre class="brush: html notranslate"><div class="pull-right">Some content that goes off to the side.</div> +<p>Some content that does not go off to the side.</p></pre> + +<h4 id="Other_uses" name="Other_uses">その他の利用</h4> + +<div class="pull-aside"> +<div class="moreinfo">側面に移動するいくつかのコンテンツ。</div> +</div> + +<p>側面に出てこないコンテンツもあります。</p> + +<pre class="brush: html notranslate"><div class="pull-aside"><div class="moreinfo">Some content that goes off to the side.</div></div> +<p>Some content that does not go off to the side.</p> +<p>Some content that does not go off to the side.</p> +</pre> +</details> + +<h3 id=".summary" name=".summary"><code>.summary</code> {{Obsolete_Inline}}</h3> + +<p>追加のパディング付きの灰色のボックスとして視覚的に明示的に表示されるページの要約ボックスを作成します。ページの重要性を高めるため、記事の開始段落 (参照記事は除く) に使用する必要があります。</p> + +<div class="blockIndicator warning"> +<p><strong>重要:</strong> これは検索エンジンによる検索結果リストのページの要約や MDN によって、ページタイトルとその要約のツールチップとメニューを作成するのに使用されるテキストのセクションを設定する {{anch(".seoSummary")}} クラスと同じではありません。このクラスは、厳密には視覚効果です。ページの可視性および有効な要約の両方を確立するために、両方のクラスを一緒に使用することができます。</p> +</div> + +<p class="summary">これはこの記事の始まりです。以下では、子犬、キリン、ジュゴンについて説明します。</p> + +<details> +<p>これは MDN エディタの WYSIWYG スタイルドロップダウンメニューの "Article Summary" オプションで利用できます。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11863/article-summary-menu-option.png" style="display: block; height: 238px; margin: 0px auto; width: 254px;"></p> + +<h4 id="Example_syntax_14" name="Example_syntax_14">構文例</h4> + +<pre class="brush: html notranslate"><p class="summary">This is the start of this article. Below we will talk about puppies, giraffes, and dugongs.</p></pre> +</details> + +<h3 id=".topicpage-table"><code>.topicpage-table</code></h3> + +<p>太い灰色の境界線で区切られた2つの列を作成します。ランディングページでよく使用されます。これは通常、ネストされた {{HTMLElement("div")}} で最も効果的です。2つの子要素に <code>.section</code> クラスを与えなければならないことに注意してください。</p> + +<div class="topicpage-table"> +<div class="section">Column 1</div> + +<div class="section">Column 2</div> +</div> + +<details> +<h4 id="Example_syntax_15" name="Example_syntax_15">構文例</h4> + +<pre class="brush: html notranslate"><div class="topicpage-table"> + <div class="section">Column 1</div> + <div class="section">Column 2</div> +</div></pre> +</details> + +<h3 id=".threecolumns"><code>.threecolumns</code></h3> + +<p>コンテンツのブロックが3つの等幅の列に表示されます。</p> + +<div class="threecolumns"> +<p>Mixtape distillery biodiesel pop-up Austin chambray. Fingerstache YOLO tousled, meditation four loko squid brunch single-origin coffee stumptown ethical asymmetrical polaroid Neutra hashtag beard. Mustache Godard Bushwick, Tumblr salvia +1 fixie cornhole beard wayfarers stumptown aesthetic keffiyeh lomo. Meggings lumbersexual keytar Shoreditch.</p> + +<p>Street art PBR YOLO pug, before they sold out fixie artisan blog bicycle rights beard direct trade chillwave. Fanny pack cornhole whatever, Austin single-origin coffee ethical church-key distillery fashion axe tofu farm-to-table irony tattooed Tumblr. Craft beer Thundercats Austin gentrify, wolf Echo Park asymmetrical hella sartorial.</p> +</div> + +<details> +<p>これは MDN エディターの WYSIWYG スタイルドロップダウンメニューの [3列] オプションで利用できます。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11779/twocolumn-threecolumn.png" style="border: 1px solid black; display: block; height: 167px; margin: 0px auto; width: 253px;"></p> + +<div class="blockIndicator note"> +<p><strong>注</strong>: これをリストに適用する場合は、外側のラッパー {{HTMLElement("div")}} に適用する必要があります。そうでなければ、 {{HTMLElement("ul")}} 要素に適用されます。 リストの箇条書きが Chrome に表示されなくなります。</p> +</div> + +<h4 id="Example_syntax_16" name="Example_syntax_16">構文例</h4> + +<pre class="notranslate"><div class="threecolumns"> + <p>Mixtape distillery biodiesel pop-up Austin chambray. Fingerstache YOLO tousled, meditation four loko squid brunch single-origin coffee stumptown ethical asymmetrical polaroid Neutra hashtag beard. Mustache Godard Bushwick, Tumblr salvia +1 fixie cornhole beard wayfarers stumptown aesthetic keffiyeh lomo. Meggings lumbersexual keytar Shoreditch.</p> + + <p>Street art PBR YOLO pug, before they sold out fixie artisan blog bicycle rights beard direct trade chillwave. Fanny pack cornhole whatever, Austin single-origin coffee ethical church-key distillery fashion axe tofu farm-to-table irony tattooed Tumblr. Craft beer Thundercats Austin gentrify, wolf Echo Park asymmetrical hella sartorial.</p> +</div></pre> +</details> + +<h3 id=".twocolumns"><code>.twocolumns</code></h3> + +<p>コンテンツのブロックが2つの等幅の列に表示されます。</p> + +<div class="twocolumns"> +<p>Mixtape distillery biodiesel pop-up Austin chambray. Fingerstache YOLO tousled, meditation four loko squid brunch single-origin coffee stumptown ethical asymmetrical polaroid Neutra hashtag beard. Mustache Godard Bushwick, Tumblr salvia +1 fixie cornhole beard wayfarers stumptown aesthetic keffiyeh lomo. Meggings lumbersexual keytar Shoreditch.</p> + +<p>Street art PBR YOLO pug, before they sold out fixie artisan blog bicycle rights beard direct trade chillwave. Fanny pack cornhole whatever, Austin single-origin coffee ethical church-key distillery fashion axe tofu farm-to-table irony tattooed Tumblr. Craft beer Thundercats Austin gentrify, wolf Echo Park asymmetrical hella sartorial.</p> +</div> + +<details> +<p>これは MDN エディターの WYSIWYG スタイルドロップダウンメニューの [2列] オプションで利用できます。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11779/twocolumn-threecolumn.png" style="border: 1px solid black; display: block; height: 167px; margin: 0px auto; width: 253px;"></p> + +<div class="blockIndicator note"> +<p><strong>注</strong>: これをリストに適用する場合は、外側のラッパー {{HTMLElement("div")}} に適用する必要があります。そうでなければ、{{HTMLElement("ul")}} 要素に適用されます。 リストの箇条書きが Chrome に表示されなくなります。</p> +</div> + +<h4 id="Example_syntax_17" name="Example_syntax_17">構文例</h4> + +<pre class="notranslate"><div class="twocolumns"> + <p>Mixtape distillery biodiesel pop-up Austin chambray. Fingerstache YOLO tousled, meditation four loko squid brunch single-origin coffee stumptown ethical asymmetrical polaroid Neutra hashtag beard. Mustache Godard Bushwick, Tumblr salvia +1 fixie cornhole beard wayfarers stumptown aesthetic keffiyeh lomo. Meggings lumbersexual keytar Shoreditch.</p> + + <p>Street art PBR YOLO pug, before they sold out fixie artisan blog bicycle rights beard direct trade chillwave. Fanny pack cornhole whatever, Austin single-origin coffee ethical church-key distillery fashion axe tofu farm-to-table irony tattooed Tumblr. Craft beer Thundercats Austin gentrify, wolf Echo Park asymmetrical hella sartorial.</p> +</div></pre> +</details> + +<h3 id=".blockIndicator.warning"><code>.blockIndicator.warning</code></h3> + +<p>コンテンツの一部を警告ボックスに変換します。警告ボックスは通常、読者が本当に注意する必要があるという重要な事実を伝えます (例えば、何かをする必要がある、あるいは重大な問題を避けるために何かを避けるなど)。</p> + +<div class="blockIndicator warning"> +<p><strong>警告</strong>: ここにはドラゴンがいます！</p> +</div> + +<details> +<p>これは MDN エディタの WYSIWYG スタイルドロップダウンメニューの [警告ボックス] オプションで利用できます。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11779/twocolumn-threecolumn.png" style="border: 1px solid black; display: block; height: 167px; margin: 0px auto; width: 253px;"></p> + +<h4 id="Example_syntax_18" name="Example_syntax_18">構文例</h4> + +<pre class="brush: html notranslate"><div class="blockIndicator warning"> + <p><strong>警告</strong>:ここにはドラゴンがいます！</p> +</div></pre> +</details> + +<h2 id="Table_styles" name="Table_styles">表のスタイル</h2> + +<p>MDN は、 HTML {{HTMLElement("table")}} 要素を表示するための特定のスタイルを提供します。このセクションでは、これらについて説明します。</p> + +<p>追加クラスなし:</p> + +<table> + <caption>Favorite teas, December 2015</caption> + <thead> + <tr> + <th scope="row">種類</th> + <th scope="col">カフェイン</th> + <th scope="col">抽出時間</th> + <th scope="col">湯温</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">紅茶</th> + <td>高</td> + <td>2-3 分</td> + <td>99 °C</td> + </tr> + <tr> + <th scope="row">緑茶</th> + <td>低-中</td> + <td>1-2 分</td> + <td>75-80 °C</td> + </tr> + <tr> + <th colspan="4">カフェインフリー</th> + </tr> + <tr> + <th scope="row">ハーブティー</th> + <td>なし</td> + <td>3-6 分</td> + <td>99 °C</td> + </tr> + </tbody> +</table> + +<h3 id=".standard-table"><code style="white-space: nowrap;">.standard-table</code></h3> + +<table class="standard-table"> + <caption>Favorite teas, December 2015</caption> + <thead> + <tr> + <th scope="row">種類</th> + <th scope="col">カフェイン</th> + <th scope="col">抽出時間</th> + <th scope="col">湯温</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">紅茶</th> + <td>高</td> + <td>2-3 分</td> + <td>99 °C</td> + </tr> + <tr> + <th scope="row">緑茶</th> + <td>低-中</td> + <td>1-2 分</td> + <td>75-80 °C</td> + </tr> + <tr> + <th colspan="4">カフェインフリー</th> + </tr> + <tr> + <th scope="row">ハーブティー</th> + <td>なし</td> + <td>3-6 分</td> + <td>99 °C</td> + </tr> + </tbody> +</table> + +<details> +<p>MDN エディターの WYSIWYG ツールバーにある <em>Table</em> ボタンを使用して、標準の表を作成することができます。これを押すといくつもの機能を含む表のプロパティダイアログボックスが表示されます。一般には行と列の数、どのセルが表の見出し ({{HTMLElement("th")}}) なのか、表示される {{HTMLElement("caption")}}、必要に応じて読み上げソフトにもっと詳細な情報を提供する {{HTMLAttrxRef("summary", "table")}} 属性などを設定するために使用します。</p> + +<p><img alt="A diagram showing the Table button in the MDN edit interface, which has a picture of a table on it, and the dialog box that it brings up, which has options on it to set row number, column number, which cells are headings, and more." src="https://mdn.mozillademos.org/files/11997/table-styles-interface-flat.png" style="display: block; margin: 0 auto;"></p> + +<h4 id="Style_notes" name="Style_notes">スタイルのメモ</h4> + +<ul> + <li>Note the different styling applied to the headers ({{HTMLElement("th")}}), and the fact that they have {{HTMLAttrxRef("scope", "th")}} attributes applied for accessibility purposes.</li> + <li>By default, alternating rows have zebra stripes applied, but these can be removed by adding the <code>.no-stripe</code> class to them.</li> + <li>You can force a table to span the full width of the content area (or other immediate containing box, if it is not the content area) by adding the <code>.fullwidth</code> class to the {{HTMLElement("table")}} element.</li> +</ul> + +<h4 id="Example_syntax_19" name="Example_syntax_19">構文例</h4> + +<pre class="brush: html notranslate"><table class="standard-table" summary="This table details what tea we liked to drink back in the heady month of December 2015"> + <caption>Favorite teas, December 2015</caption> + <thead> + <tr> + <th scope="row">種類</th> + <th scope="col">カフェイン</th> + <th scope="col">抽出時間</th> + <th scope="col">湯温</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">紅茶</th> + <td>High</td> + <td>2-3 minutes</td> + <td>99&nbsp;°C</td> + </tr> + <tr> + <th scope="row">緑茶</th> + <td>低 - 中</td> + <td>1-2 minutes</td> + <td>75 - 80&nbsp;°C</td> + </tr> + <tr> + <th scope="row">ハーブティー</th> + <td>None</td> + <td>3-6 minutes</td> + <td>99&nbsp;°C</td> + </tr> + </tbody> +</table></pre> +</details> + +<h3 id=".standard-table.nostripe"><code><span style="white-space: nowrap;">.standard-table</span>.nostripe</code></h3> + +<table class="nostripe standard-table"> + <caption>Favorite teas, December 2015</caption> + <thead> + <tr> + <th scope="row">種類</th> + <th scope="col">カフェイン</th> + <th scope="col">抽出時間</th> + <th scope="col">湯温</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">紅茶</th> + <td>高</td> + <td>2-3 分</td> + <td>99 °C</td> + </tr> + <tr> + <th scope="row">緑茶</th> + <td>低-中</td> + <td>1-2 分</td> + <td>75-80 °C</td> + </tr> + <tr> + <th colspan="4">カフェインフリー</th> + </tr> + <tr> + <th scope="row">ハーブティー</th> + <td>なし</td> + <td>3-6 分</td> + <td>99 °C</td> + </tr> + </tbody> +</table> + +<h3 id=".standard-table.fullwidth"><code>.<span style="white-space: nowrap;">standard-table</span>.fullwidth</code></h3> + +<table class="fullwidth standard-table"> + <caption>Favorite teas, December 2015</caption> + <thead> + <tr> + <th scope="row">種類</th> + <th scope="col">カフェイン</th> + <th scope="col">抽出時間</th> + <th scope="col">湯温</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">紅茶</th> + <td>高</td> + <td>2-3 分</td> + <td>99 °C</td> + </tr> + <tr> + <th scope="row">緑茶</th> + <td>低-中</td> + <td>1-2 分</td> + <td>75-80 °C</td> + </tr> + <tr> + <th colspan="4">カフェインフリー</th> + </tr> + <tr> + <th scope="row">ハーブティー</th> + <td>なし</td> + <td>3-6 分</td> + <td>99 °C</td> + </tr> + </tbody> +</table> + +<h3 id=".fullwidth-table"><code style="white-space: nowrap;">.fullwidth-table</code></h3> + +<table class="fullwidth-table"> + <caption>Favorite teas, December 2015</caption> + <thead> + <tr> + <th scope="row">種類</th> + <th scope="col">カフェイン</th> + <th scope="col">抽出時間</th> + <th scope="col">湯温</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">紅茶</th> + <td>高</td> + <td>2-3 分</td> + <td>99 °C</td> + </tr> + <tr> + <th scope="row">緑茶</th> + <td>低-中</td> + <td>1-2 分</td> + <td>75-80 °C</td> + </tr> + <tr> + <th colspan="4">カフェインフリー</th> + </tr> + <tr> + <th scope="row">ハーブティー</th> + <td>なし</td> + <td>3-6 分</td> + <td>99 °C</td> + </tr> + </tbody> +</table> + +<h2 id="Updating_this_guide" name="Updating_this_guide">このガイドの更新</h2> + +<p>このガイドは未完成のものであり、時間をかけて徐々に更新されています。このガイドの更新や追加を手伝ってくださる方は、気軽に行ってください。質問がある場合や、この記事を改善するための議論やアイデアをご希望の場合、または MDN Web Docs のスタイルやレイアウトを改善する方法についての提案がある場合は、いくつかの選択肢があります。</p> + +<p>完成させることを手伝いたい場合や、抜けているものや正しくない記述のスタイルがある場合は、 (Discourse では chrisdavidmills、 <a href="https://wiki.mozilla.org/IRC">Mozilla IRC</a> では chrismills) に連絡してください。</p> + +<dl> + <dt><a href="https://discourse.mozilla.org/c/mdn">MDN Web Docs Discourse フォーラムの議論を開始する</a></dt> + <dd>MDN Web Docs コミュニティやスタッフと議論したいという考えがある場合は、Mozilla Discourse のディスカッションサイトにある MDN Web Docs フォーラムでトピックを開始してください。</dd> + <dt><a href="https://github.com/mdn/sprints/issues/new?template=issue-template.md">提案を GitHub で提出</a></dt> + <dd>あなたが私たちの公式問題追跡システムにあなたの提案を記録したいのであれば、そうすることをお勧めします。最初に上記のチャンネルの1つを使って議論することをお勧めしますが、必須ではありません。</dd> + <dt><a href="irc://irc.mozilla.org/mdn">IRC チャンネルで質問する</a></dt> + <dd>私たちの執筆スタッフと寄稿者のコミュニティは、<a href="https://wiki.mozilla.org/IRC">Mozilla の IRC サーバ</a>の #mdn チャンネルを使って議論し、アイデアを共有しています。私たちのチャンネルに参加して質問をしたり、提案をすることは大歓迎です！ (なお、 IRC は参加者が少なく、2020年内に終了する可能性があります。 Discourse のほうが回答が得られやすいです。)</dd> +</dl> diff --git a/files/ja/mdn/guidelines/does_this_belong_on_mdn/index.html b/files/ja/mdn/guidelines/does_this_belong_on_mdn/index.html new file mode 100644 index 0000000000..64d4de378a --- /dev/null +++ b/files/ja/mdn/guidelines/does_this_belong_on_mdn/index.html @@ -0,0 +1,202 @@ +--- +title: これは MDN Web Docs に掲載するものですか？ +slug: MDN/Guidelines/Does_this_belong_on_MDN +tags: + - Guide + - Guidelines + - MDN Meta +translation_of: MDN/Guidelines/Does_this_belong_on_MDN +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p><span class="seoSummary">この記事では、ある主題やコンテンツの種類を MDN Web Docs に載せるべきかどうかを決定する方法について説明します。</span>また、詳細ではありませんが、コンテンツを配置する可能性のある他の場所についても検討します。</p> + +<h2 id="The_question" name="The_question">問い</h2> + +<p>何らかの文書をまとめる準備をしている場合、その情報を MDN Web Docs に載せるどうか考えるかもしれません。加えて、ソースコード内の文書を維持したり、その文書を <a href="https://wiki.mozilla.org/">Mozilla wiki</a> や、git リポジトリー内の readme ファイルに置いたりすることを検討しているかもしれません。この記事の目的は、あなたのコンテンツが、これらのオプションのどれにふさわしいのかを決めるのに役立つことです。</p> + +<p>文書を MDN に載せるかどうかについて、主に 2 つ考慮する点があります。</p> + +<ul> + <li>文書の主題 (何についてのものか)</li> + <li>文書の性質 (これはどんな種類の文書か)</li> +</ul> + +<p>MDN への寄稿は、すべて特定のオープンソースライセンスに該当することに注意してください。これは <a href="/en-US/docs/MDN/About">MDN について</a>ページに<a href="/ja/docs/MDN/About#Copyrights_and_licenses">詳細に記されています</a>。</p> + +<div class="note"> +<p><strong>注</strong>: MDN Web Docs を利用したり、投稿したりする際には、Mozilla の<a href="https://www.mozilla.org/en-US/about/legal/terms/mozilla/">ウェブサイトおよびコミュニケーション利用規約</a>が適用されることに注意してください。この文書を確認して、Mozilla のサイトで投稿できること、できないことを確認してください。</p> +</div> + +<h2 id="What_topics_belong_on_MDN_Web_Docs" name="What_topics_belong_on_MDN_Web_Docs">どのようなトピックが MDN Web Docs に載るのか</h2> + +<p>一般的には、オープンなウェブ向きの技術であれば、MDN 上で文書化します。これは、現在および近い将来にサイトやアプリケーションを作成するウェブ開発者が使用できる機能を意味します。複数のブラウザーで実装されていて、標準として受け入れられているか、標準化に向けて進んでいるものであれば、そうですね。もしそれがまだ非常に実験的で、複数のブラウザーで実装されておらず、変更される可能性がある場合、それでも載せるのに適してはいますが、ライターのチームが取り組むべき優先事項とは見なされないかもしれません。</p> + +<p>主にフロントエンドのウェブ技術に重点を置いています。</p> + +<ul> + <li><a href="/ja/docs/Web/HTML" title="HTML">HTML</a></li> + <li><a href="/ja/docs/Web/CSS" title="CSS">CSS</a></li> + <li><a href="/ja/docs/Web/JavaScript" title="JavaScript">JavaScript</a></li> + <li><a href="/ja/docs/Web/SVG" title="SVG">SVG</a></li> + <li><a href="/ja/docs/Web/API">Web APIs</a></li> + <li><a href="/ja/docs/Web/API/WebGL_API" title="WebGL">WebGL</a></li> + <li>など</li> +</ul> + +<div class="note"> +<p><strong>Note</strong>: バックエンドテクノロジーには、別の文書化の場所があり、MDN はこれにとって変わるつもりはありませんが、<a href="/ja/docs/Learn/Server-side">いくつかの例外はあります</a>。</p> +</div> + +<p>また、複数の技術にまたがるが、以下のようなウェブ開発に関連したトピックも歓迎します。</p> + +<ul> + <li><a href="/ja/docs/Web/Accessibility" title="Accessibility">Accessibility</a></li> + <li><a href="/ja/docs/Web/Guide/AJAX">AJAX</a></li> + <li><a href="/ja/docs/Web/Guide/Graphics">ウェブグラフィック</a></li> + <li><a href="/ja/docs/Web/Progressive_web_apps">プログレッシブウェブアプリ</a></li> + <li><a href="/ja/docs/Games/">ウェブベースのゲーム</a></li> +</ul> + +<div class="note"> +<p><strong>注:</strong> MDN は、ウェブに公開されていて、特に一般的に使われている場合には、一部の標準外の機能をカバーしています。例えば、WebKit 固有の CSS プロパティのドキュメントがあります。MDN は、ウェブ開発者にとって十分に有用であると考えられる場合には、ウェブ標準以外の技術もカバーしています。<a href="/ja/docs/Related">ウェブ関連技術</a>のセクションを参照してください。</p> +</div> + +<h2 id="What_topics_dont_belong_on_MDN_Web_Docs" name="What_topics_dont_belong_on_MDN_Web_Docs">MDN Web Docs に掲載しない主題</h2> + +<p>一般医、オープンなウェブ標準ではないものはすべて、MDN に掲載するものではありません。以下にもっと具体的に示します。</p> + +<h3 id="Mozilla_products" name="Mozilla_products">Mozilla 製品</h3> + +<p>このカテゴリーの文書には、 Mozilla 製品に対して開発者として作業する方法と、これらのオープンソースプロジェクトに貢献する方法との、両方があります。</p> + +<p>MDN には Mozilla 製品の文書が大量にありますが、新規コンテンツ開発の重点はオープンウェブに置いています。MDN に Mozilla 製品の文書を新規作成することは推奨されません。Mozilla 製品 (やそうなるかもしれない製品) の作業を進めている場合は、<a href="https://wiki.mozilla.org/Engagement/MDN_Durable_Team">MDN スタッフチーム</a>のメンバーに話して、その製品の文書化の道を議論してください。また、下記の<a href="#Cases_for_documenting_elsewhere">他の場所に文書化する場合</a>も見てください。</p> + +<ul> + <li><a href="/ja/docs/Mozilla/Firefox">Firefox ブラウザー</a> + + <ul> + <li><a href="/ja/docs/Tools">Firefox 開発ツール</a></li> + <li><a href="/ja/docs/Mozilla/Add-ons">アドオン</a></li> + <li><a href="/ja/docs/Mozilla/Developer_guide/Build_Instructions">Firefox の構築と構成</a></li> + <li>など</li> + </ul> + </li> + <li><a href="/ja/docs/Mozilla">Mozilla プラットフォーム</a> + <ul> + <li><a href="/ja/docs/Mozilla/Gecko">Gecko</a></li> + <li><a href="/ja/docs/Mozilla/Projects/SpiderMonkey">SpiderMonkey</a></li> + <li>など</li> + </ul> + </li> +</ul> + +<h3 id="What_else" name="What_else">それ以外</h3> + +<p>その他の MDN Web Docs のトピックとして適切ではないものの例です。</p> + +<ul> + <li>ウェブに公開されていない技術で、Mozilla 以外のブラウザーに固有のもの</li> + <li>ウェブにも Mozilla 製品にも関係しない技術</li> + <li>エンドユーザー向け文書。Mozilla 製品では、こうした文書は <a href="https://support.mozilla.org">Mozilla サポートサイト</a>に載っています。</li> +</ul> + +<h2 id="What_types_of_documents_belong_on_MDN" name="What_types_of_documents_belong_on_MDN">MDN に掲載する文書の種類</h2> + +<p>一般に、MDN は<em>プロダクト</em>のドキュメントであり、<em>プロジェクト</em>や<em>プロセス</em>のドキュメントではありません (<a href="/ja/docs/MDN">MDN 自体について</a>を除く)。そのため、もしドキュメントが「どのように使うか」や「どのように動作するか」 (「どの」とは下記で記述されている特定のカテゴリのことです) なら MDN に掲載しましょう。しかし、「誰が開発したか」や「開発プランについて」などは MDN にふさわしくありません。Mozilla 傘下で開発されているものの場合は <a href="https://wiki.mozilla.org/Main_Page">Mozilla project wiki</a> に掲載するといいでしょう。</p> + +<p>MDN に掲載するのにふさわしく<em>ない</em>種類の文書の例をいくつか挙げます。</p> + +<ul> + <li>計画書</li> + <li>設計書</li> + <li>プロジェクト提案書</li> + <li>仕様書や標準</li> + <li>プロモーション素材、広告、<a href="#About_your_profile">個人情報</a></li> +</ul> + +<h2 id="Advantages_to_documenting_on_MDN" name="Advantages_to_documenting_on_MDN">MDN で文書化する利点</h2> + +<p>もし書きたいドキュメントの内容や種類が MDN に適していると判断したとしても、MDN が最適な場所かどうか迷っているのであれば、読んでみてください。MDN でドキュメントを作成する利点はたくさんあります。</p> + +<h3 id="Lots_of_writers_and_translators" name="Lots_of_writers_and_translators">たくさんの執筆者と翻訳者</h3> + +<p>MDN コミュニティは巨大です。MDN のコンテンツの作成や保守に参加している人がたくさんいます。すべての大陸に (南極ではないかもしれませんが、それ以外には) 執筆者や編集者がいて、執筆者の数の多さには価値があります。</p> + +<ul> + <li>雇用している本職の執筆者がいて、できるだけコンテンツをより良いものにする<strong>ミッション</strong>が与えられています。</li> + <li>ボランティアの中心となるコミュニティがあり、あなたを手助けするかなりの量のコンテンツに協力しています。</li> + <li>MDN チームは、あなたの文書化プロジェクトに十分人を配置することを保証すべく、一緒に作業してくれます。</li> + <li>広大な MDN コミュニティは大量に貢献します。誤字の修正からコンテンツの編集レビューまで、助けてくれます。</li> + <li><a href="https://chat.mozilla.org/#/room/#mdn:mozilla.org">MDN Web Docs チャットルーム</a>が <a href="https://wiki.mozilla.org/Matrix">Matrix</a> にあり、ライターコミュニティに話してアドバイスを得る場や、コンテンツ作成や維持を助ける人を採用する場を提供します。</li> + <li>全世界に協力者がいるため、問題を見ていたり直したりする人がいつも周りにいます。</li> + <li>ボランティアコミュニティには、多くの言語へ翻訳する人がいて、ドキュメントのローカライズを手伝っています。</li> +</ul> + +<p>あなたの開発チームが、文書作成に全責任を負うことを望みますか？その場合はおそらく他の場所で文書を維持するべきでしょう。</p> + +<h3 id="Maintenance" name="Maintenance">保守</h3> + +<p>投稿者の数が非常に多いため、通常、コンテンツに問題がないかどうかを監視するために、誰かが常駐していま。スパム対策からコピー編集まで、24時間体制で対応しています。ここでは、私たちのチームができることのほんの一例をご紹介します。</p> + +<dl> + <dt>スパム削除</dt> + <dd>スパムは発生します。それに対処します。</dd> + <dt>文章の推敲</dt> + <dd>文章が思うようにはっきりしていなくても、正確でなくても心配する必要はありません。散文を、他の人が読めるような文章に仕上げます。</dd> + <dt>スタイルの一貫性</dt> + <dd>コンテンツが、それ自体だけでなく、その周りにある他のドキュメントとスタイル的に一貫していることを確認します。</dd> + <dt>コンテンツ管理</dt> + <dd>私たちのチームは、ドキュメントが他の関連資料とクロスリンクされ、記事が適切な場所に配置され、メニューやその他のインフラストラクチャが構築されているかどうかを確認し、フォローしやすく、理解しやすいように支援します。</dd> + <dt>サイトとプラットホームの維持</dt> + <dd>MDN には、サイトの稼働、運営、安全性を維持するITチームと、コンテンツが表示されるプラットフォームを維持、強化するプラットフォーム開発チームの両方があります。ドキュメントのインフラに自分のリソースや追加のリソースを割く必要はありません。</dd> +</dl> + +<h2 id="Cases_for_documenting_elsewhere" name="Cases_for_documenting_elsewhere">他の場所で文書化した場合</h2> + +<p>MDN 以外のどこかで成果を文書化するのを考える理由も少しあります。その理由のいくつかと、利点や欠点をそれぞれ示します。</p> + +<h3 id="Plans_and_processes" name="Plans_and_processes">計画書や手順書</h3> + +<p>計画書や手順書や提案書は、決して MDN に載せてはいけません。これはとても単純なことです。製品が Mozilla のものなら、<a href="https://wiki.mozilla.org/Main_Page">Mozilla project wiki</a> に置くことができます。</p> + +<h3 id="The_project_is_on_GitHub" name="The_project_is_on_GitHub">Github 上のプロジェクト</h3> + +<p>Mozilla の製品のいくつかは Github にホストされていて、Github では wiki 的な文書化システムが提供されています。文書をそこに作成するチームもあります。文書を作成するには確実にフェアで便利ですが、次に注意してください。</p> + +<ul> + <li>MDN はたぶんあなたを手助けできません。一般的に我々は MDN 以外の文書作業には加わりしません。例外はあるものの、まれです。</li> + <li>あなたの文書と、関連する他の素材をクロスリンクするのは、困難だったり、不可能になるかもしれません。</li> + <li>コンテンツが他の文書と一貫したスタイルが持てなくなります。</li> + <li>他の (ウェブや Mozilla の) 文書の外にあるため、文書の発見しやすさが失われます。</li> +</ul> + +<p>もちろん、これらのことが困ることではなかったり、問題にならなかったりする可能性もあります。チームによっては、自分たちでドキュメントを書いたりメンテナンスしたりすることを気にしない、あるいは最低限のドキュメントの必要性があるコードに取り組んでいるチームもあります。</p> + +<h3 id="You_want_to_keep_docs_in-source" name="You_want_to_keep_docs_in-source">ソース内に文書を置きたい場合</h3> + +<p>一部のチームでは、ドキュメントをソースツリーに配置したがることがあります。これは特にプロジェクトの内部やライブラリプロジェクトでよく見られます。</p> + +<p>このアプローチにはいくつかの利点があります。</p> + +<ul> + <li>これにより、開発者が技術をコーディングしながらドキュメントを作成することができ、ドキュメントがコードを常に最新の状態に保つことができるようになります。</li> + <li>ドキュメントは、バージョン管理を含め、コードと同じ開発とリリースのプロセスに従うことができます。</li> +</ul> + +<p>欠点もあります。</p> + +<ul> + <li>MDN Web Docs チームはあなたを助けることができません。コードが Mozilla のソースリポジトリー内にあっても、レビューとチェックインのシステムにより、docs チームが参加することは現実的ではありません。</li> + <li>他の関連文書とのクロスリンクを行うための簡単なツールがありません。クロスリンクは、読者にコンテキストと追加の重要な情報の両方を提供します。</li> + <li>ドキュメントが、他のドキュメントの中に存在しないことで発見可能性を失います。</li> + <li>変換ツール (JavaDoc など) を使ってウェブで読めるドキュメントを作っても、MDN Web Docs でできるものほど魅力的なものにはならないでしょう。</li> +</ul> + +<p>それでも、これはいくつかの種類のプロジェクト、特に小さなものや、あまり興味を持たれることが期待されていないものに対しては、実行可能な選択肢 (良い選択肢である可能性もあります) になるでしょう。</p> + +<h2 id="About_your_profile" name="About_your_profile">自分のプロフィールについて</h2> + +<p>MDN のプロフィールページには、限られた個人情報を掲載しても構いません。ユーザーのプロフィールは、企業や組織ではなく、人間を反映したものであるべきです。適度な自己 PR は OK ですが、リンクスパムは不可です。個人的な写真やその他の無関係なファイルをアップロードするためにプロフィールを使用<em>しない</em>でください。</p> diff --git a/files/ja/mdn/guidelines/editorial/index.html b/files/ja/mdn/guidelines/editorial/index.html new file mode 100644 index 0000000000..3d0d00ae1c --- /dev/null +++ b/files/ja/mdn/guidelines/editorial/index.html @@ -0,0 +1,45 @@ +--- +title: 編集方針 +slug: MDN/Guidelines/Editorial +tags: + - MDN + - MDN Meta + - ドキュメンテーション + - 書き方 +translation_of: MDN/Guidelines/Editorial +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p><span class="seoSummary">この記事では、Mozilla MDN のスタッフが MDN Web ドキュメントのコンテンツを管理するために設定したポリシーについて説明します。</span>MDN Web ドキュメントへの貢献者はすべて、これらのポリシーを遵守することが期待されます。</p> + +<h2 id="関連性">関連性</h2> + +<p>MDN のすべてのコンテンツは、それが現れるテクノロジーセクションに関連していなければなりません。迷惑メール (商業広告) およびその他の無関係なコンテンツは、検出時に元に戻すか削除されます。Mozilla スタッフの裁量により、スパムを投稿するユーザは MDN から禁じられることがあります。</p> + +<p>翻訳されたコンテンツは MDN の適切なロケールセクションに表示する必要があります。これを行う方法については <a href="/ja/docs/MDN/Contribute/Localize/Translating_pages">MDN ページの翻訳</a>を参照してください。</p> + +<p>リンクされているトピックに関連する商用サイトへの外部リンクは、ケースバイケースで判断されます。Web 開発者を支援するうえでのその価値は、リンク先サイトの商業的利益を上回るものでなければなりません。</p> + +<h2 id="中立性">中立性</h2> + +<p>MDN の記事コンテンツは<a href="https://ja.wikipedia.org/wiki/Wikipedia:%E4%B8%AD%E7%AB%8B%E7%9A%84%E3%81%AA%E8%A6%B3%E7%82%B9">中立的な視点</a>を持ち、編集上の偏見のないブラウザのバリエーションについて報告しなければなりません。任意のブラウザまたはユーザエージェントについての論評は容認できません。</p> + +<h3 id="オープンな_web_のトピック">オープンな web のトピック</h3> + +<p>MDN web docs には、Web 開発者がブラウザに依存しないコードを書くことを可能にする、ブラウザに依存しないドキュメントが含まれています。</p> + +<p>MDN で文書化される Web 技術は、標準化されており、少なくとも2つのブラウザによって実装されるべきです。ブラウザサポートのバリエーションは、記事の<a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables">ブラウザ互換性</a>セクションに記載されています。</p> + +<h3 id="Mozilla_固有のセクション">Mozilla 固有のセクション</h3> + +<p>MDN の Mozilla 特有のセクションは、Mozilla 特有のコンテンツに関心があるため、ブラウザに中立である必要はないことに注意してください。しかし、彼らは依然として中立的な視点を維持し、他の製品に関する軽蔑的な発言を避けなければなりません。</p> + +<h2 id="構造">構造</h2> + +<p>リファレンスページは同じタイプの他のページと同じ構造にする必要があります。共通ページ構造のリストと例については<a href="/ja/docs/MDN/Contribute/Structures/Page_types">ページの種類</a>を参照してください。</p> + +<h2 id="その他のガイドライン">その他のガイドライン</h2> + +<p>貢献者は文章、コードサンプル、CSS、その他のトピックについて、MDN に関する<a href="/ja/docs/MDN/Contribute/Guidelines">他のガイドライン</a>に従うことが求められます。 これらのガイドラインのバリエーションは <a href="https://discourse.mozilla.org/c/mdn">MDN ディスカッションフォーラム</a>で議論されなければならず、その必要性を提示したり、必要に応じてガイドラインを変更したりする必要があります。</p> diff --git a/files/ja/mdn/guidelines/index.html b/files/ja/mdn/guidelines/index.html new file mode 100644 index 0000000000..346a54a01a --- /dev/null +++ b/files/ja/mdn/guidelines/index.html @@ -0,0 +1,16 @@ +--- +title: ガイドライン +slug: MDN/Guidelines +tags: + - Documentation + - Landing + - MDN +translation_of: MDN/Guidelines +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p><span class="seoSummary">これらのガイドは MDN の文書がどのように書かれ、整形されるべきかの詳細を説明します。同様に、コードのサンプル、その他の素材をどのように示したら良いかについても説明します。</span> これらのガイドに従うならば、あなたの成果物はきれいなものであり、すぐに使えるものとなります。</p> + +<p>{{LandingPageListSubpages}}</p> diff --git a/files/ja/mdn/guidelines/video/index.html b/files/ja/mdn/guidelines/video/index.html new file mode 100644 index 0000000000..4ce9b87b9f --- /dev/null +++ b/files/ja/mdn/guidelines/video/index.html @@ -0,0 +1,230 @@ +--- +title: MDNのビデオコンテンツ +slug: MDN/Guidelines/Video +translation_of: MDN/Guidelines/Video +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p class="summary">MDNのWeb Docsは動画が多いサイトではありませんが、ビデオコンテンツを記事の一部として使用することに意味がある場所がいくつかあります。この記事では、MDNの記事に動画を含めることが適切な場合について説明し、シンプルだが効果的なビデオを予算内で作成するためのヒントを提供します。</p> + +<h2 id="MDNで動画を使用する場合">MDNで動画を使用する場合</h2> + +<p>技術文書、特に参考資料や上級レベルガイドにビデオコンテンツを使用することには、いくつかの反対意見があります。：</p> + +<ul> + <li> + <p>Video is linear. People don’t tend to read online documentation in a linear fashion, starting at the start and reading through to the end. <a href="http://www.sensible.com/chapter.html">They scan</a>. Video is really hard to scan — it forces the user to consume the content start-to-finish.</p> + </li> + <li> + <p>Video is less information-dense than text. It takes longer to consume a video explaining something than it does to read the equivalent instructions.</p> + </li> + <li> + <p>Video is big in terms of file size, and therefore more expensive and less performant than text.</p> + </li> + <li> + <p>Video has accessibility problems: it’s more expensive to produce generally than text, but especially to localize, or make usable by screen reader users.</p> + </li> + <li> + <p>Following on from the last point, video is much harder to edit/update/maintain than text content.</p> + </li> +</ul> + +<div class="note"> +<p><strong>Note</strong>: It’s worth keeping these problems in mind, even when you are making videos, so you can try to alleviate some of them.</p> +</div> + +<p>There are many popular video sites that provide a lot of video tutorials. MDN just isn't a video-driven site. But video does have a place on MDN, in certain contexts.</p> + +<p>We tend to most commonly use video when describing some kind of instruction sequence or multi-step workflow that would be hard to describe concisely in words: <em>"do this, then do that, then this will happen"</em>. It is especially useful when trying to describe processes that cross over multiple applications or windows, and include GUI interactions that might not be simple to describe: <em>"now click on the button near the top-left that looks a bit like a duck"</em>.</p> + +<p>In such cases it is often more effective to just <strong>show</strong> what you mean. We most commonly use videos when explaining features of the <a href="/en-US/docs/Tools">Firefox DevTools</a>.</p> + +<h2 id="What_should_MDN_videos_look_like">What should MDN videos look like?</h2> + +<p>Videos for MDN should be:</p> + +<ul> + <li> + <p><strong>Short</strong>: Try to keep videos under 30 seconds, ideally under 20 seconds. This is short enough not to make big demands on peoples’ attention spans.</p> + </li> + <li> + <p><strong>Simple</strong>: Try to make the workflow simple, 2-4 distinct pieces. This makes them easier to follow.</p> + </li> + <li> + <p><strong>Silent</strong>: Audio makes videos much more engaging, but they are much more time-consuming to make. Also, having to explain what you’re doing makes the videos much longer, and adds to the costs (both financial and in terms of time) of localization.</p> + </li> +</ul> + +<p>To explain something more complex, you can use a blend of short videos and screenshots, interspersed with text. The text can help reinforce the points made in the video, and the user can rely on the text or the video as they choose. See <a href="https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Work_with_animations#Animation_inspector">Working with the Animation Inspector</a> for a good example.</p> + +<p>In addition, you should consider the following tips:</p> + +<ul> + <li>The video will end up being uploaded to YouTube before embedding. We'd recommend a 16:9 aspect ratio for this use, so that it fills up the entire viewing frame and you don't end up with ugly black bars on the top and bottom (or left and right) of your video. So for example, you might choose a resolution of 1024×576, 1152×648, or 1280×720.</li> + <li>Record the video in HD, so that it looks better when uploaded.</li> + <li>For DevTools videos, it is often a good idea to choose a contrasting theme to the page content, for example choose the dark theme if the example webpage is light-themed. It is easier to see what is going on, and where the DevTools start and the page ends.</li> + <li>For DevTools videos, zoom in the DevTools as much as you can while still showing everything you want to show and making it look OK.</li> + <li>Make sure the thing you are trying to demonstrate isn't covered up by the mouse cursor.</li> + <li>Consider whether or not it would be useful to configure the screen recording tool to add a visual indicator of mouse clicks.</li> +</ul> + +<h2 id="Video_tools">Video tools</h2> + +<p>You'll need some kind of a tool for recording the video. These range from free to expensive, and simple to complex. If you are already experienced in creating video content, then great. If not, then we'd recommend that you start with a simple tool and then work up to something more complex if you start to enjoy creating video and want to create more interesting productions.</p> + +<p>The following table provides some recommendations for good starter tools.</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Tool</th> + <th scope="col">OS</th> + <th scope="col">Cost</th> + <th scope="col">Post-production features available?</th> + </tr> + </thead> + <tbody> + <tr> + <td>Open Broadcaster Software</td> + <td>macOS, Windows, Linux</td> + <td>Free</td> + <td>Yes</td> + </tr> + <tr> + <td>CamStudio</td> + <td>Windows</td> + <td>Free</td> + <td>Limited</td> + </tr> + <tr> + <td>Camtasia</td> + <td>Windows, macOS</td> + <td>High</td> + <td>Yes</td> + </tr> + <tr> + <td>QuickTime Player</td> + <td>macOS</td> + <td>Free</td> + <td>No, just allows simple recording</td> + </tr> + <tr> + <td>ScreenFlow</td> + <td>macOS</td> + <td>Medium</td> + <td>Yes</td> + </tr> + <tr> + <td>Kazam</td> + <td>Linux</td> + <td>Free</td> + <td>Minimal</td> + </tr> + </tbody> +</table> + +<h3 id="QuickTime_tips">QuickTime tips</h3> + +<p>If you are using macOS, you should have QuickTime Player available. This actually provides pretty easy simple recording facilities too:</p> + +<ol> + <li>Choose <em>File</em> > <em>New Screen Recording</em> from the main menu.</li> + <li>In the <em>Screen Recording</em> box, hit the record button (the red round button).</li> + <li>Drag a rectangle round the area of the screen you want to record.</li> + <li>Press the <em>Start Recording</em> button.</li> + <li>Perform whatever actions you want to record.</li> + <li>Press the <em>Stop</em> button.</li> + <li>Choose <em>File</em> > <em>Export As...</em> > <em>1080p</em> from the main menu to save as hi definition.</li> +</ol> + +<h3 id="Other_resources">Other resources</h3> + +<ul> + <li><a href="https://photography.tutsplus.com/tutorials/how-to-add-custom-callouts-to-screencast-videos-in-screenflow--cms-27122">How to Add Custom Callouts to Screencast Videos in Screenflow</a></li> +</ul> + +<h2 id="A_workflow_for_creating_videos">A workflow for creating videos</h2> + +<p>the following subsections describe the general steps you'd want to follow to create a video and get it shown on an MDN page.</p> + +<h3 id="Preparation">Preparation</h3> + +<p>First, plan the flow you want to capture: consider the best points to start and end.</p> + +<p>Make sure the desktop background and your browser profile are clean. Plan the size and positioning of browser windows, especially if you will be using multiple windows.</p> + +<p>Plan carefully what you are actually going to record, and practice the steps a few times before recording them:</p> + +<ul> + <li> + <p>Don't start a video in the middle of a process — consider whether the viewer has enough context for your actions to make sense to them. In a short DevTools video for example, it is a good idea to start by opening the DevTools to allow the viewer to get oriented.</p> + </li> + <li> + <p>Consider what your actions are, slow down, and make them obvious. Whenever you have to perform an action (say, click an icon), take it slow and make it obvious, so for example:</p> + + <ul> + <li> + <p>Move the mouse over the icon</p> + </li> + <li> + <p>Highlight or zoom (not always, depending on whether it feels needed)</p> + </li> + <li> + <p>Pause for a beat</p> + </li> + <li> + <p>Click the icon</p> + </li> + </ul> + </li> + <li>Plan zoom levels for the parts of the UI that you’re going to show. Not everyone will be able to view your video in high definition. You will be able to zoom particular parts in post-production, but it’s a good idea to zoom the app beforehand as well.</li> +</ul> + +<div class="note"> +<p><strong>Note</strong>: Don’t zoom so far that the UIs you are showing start to look unfamiliar or ugly.</p> +</div> + +<h3 id="Recording">Recording</h3> + +<p>When recording the workflow you want to show, go through the flow smoothly and steadily. Pause for a second or two when you are at key moments — for example, about to click on a button. Make sure the mouse pointer doesn’t obscure any icons or text that are important to what you are trying to demonstrate.</p> + +<p>Remember to pause for a second or two at the end, to show the result of the flow.</p> + +<div class="note"> +<p><strong>Note</strong>: If you are using a really simple tool like QuickTime Player and post production is not an option for some reason, you should get your windows set up in the right size to show the area you want to show. In the Firefox DevTools, you can use the <a href="/en-US/docs/Tools/Rulers">Rulers Tool</a> to make sure the viewport is at the right aspect ratio for the recording.</p> +</div> + +<h3 id="Post-production">Post-production</h3> + +<p>You’ll be able to highlight key moments in post-production. A highlight can consist of a couple of things, which you’ll often combine:</p> + +<ul> + <li>Zoom in on parts of the screen.</li> + <li>Fade the background.</li> +</ul> + +<p>Highlight key moments of the workflow, especially where the detail is hard to see: clicking on a particular icon or entering a particular URL, for example. Aim for the highlight to last for 1-2 seconds. It’s a good idea to add a short transition (200-300 milliseconds) at the starts and ends of the highlights.</p> + +<p>Use some restraint here: don’t make the video a constant procession of zooming in and out, or viewers will get seasick.</p> + +<p>Crop the video to the desired aspect ratio, if required.</p> + +<h3 id="Uploading">Uploading</h3> + +<p>Videos currently have to be uploaded to YouTube to be displayed on MDN, for example the <a href="https://www.youtube.com/user/mozhacks/videos">mozhacks</a> channel. Ask a member of MDN staff to upload the video if you don't have somewhere appropriate to put it.</p> + +<div class="note"> +<p><strong>Note</strong>: Mark the video as "unlisted" if it doesn’t make sense out of the context of the page (if it’s a short video, then it probably doesn't).</p> +</div> + +<h3 id="Embedding">Embedding</h3> + +<p>Once uploaded, you can embed the video in the page using the {{TemplateLink("EmbedYouTube")}} macro. This is used by inserting the following in your page at the position you want the video to appear:</p> + +<p>\{{EmbedYouTube("you-tube-url-slug")}}</p> + +<p>The single property taken by the macro call is the string of characters at the end of the video URL, not the whole URL. For example, the video embedded in our <a href="/en-US/docs/Tools/Page_Inspector/3-pane_mode">Page inspector 3-pane mode</a> article is available at https://www.youtube.com/watch?v=ELS2OOUvxIw, so the required macro call looks like this:</p> + +<p>\{{EmbedYouTube("ELS2OOUvxIw")}}</p> diff --git a/files/ja/mdn/guidelines/writing_style_guide/index.html b/files/ja/mdn/guidelines/writing_style_guide/index.html new file mode 100644 index 0000000000..a95525e369 --- /dev/null +++ b/files/ja/mdn/guidelines/writing_style_guide/index.html @@ -0,0 +1,814 @@ +--- +title: 執筆スタイルガイド +slug: MDN/Guidelines/Writing_style_guide +tags: + - MDN + - MDN Meta + - MDN Web Docs + - MDN スタイルガイド + - ガイド + - ガイドライン + - スタイルガイド + - ドキュメンテーション + - 執筆スタイルガイド +translation_of: MDN/Guidelines/Writing_style_guide +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p><span class="seoSummary">整理され、標準化され、読みやすい書き方でドキュメンテーションを示すために、 MDN Web Docs スタイルガイドはテキストがどのような体系、表記、書式などに従うべきかを説明します。これらは厳密な規則というのではなくガイドラインです。</span>形式よりも内容が重要であり、このため貢献する前にガイドラインを学ばなければならないと重荷に感じたりしないでください。とはいえ、真面目な他のボランティアが、あとであなたの成果をガイドラインに添うように書き換えても、びくびくしたり、ぎょっとしたりもしないでください。</p> + +<p>このガイドにおける言語的な観点は主に英語のドキュメンテーションに向けられたものです。その他の言語については独自のスタイルガイドを持っているかもしれません (是非つくってください)。これは多国語化チームのページのサブページとして公開してください。</p> + +<div class="note"> +<p>2017年12月現在、日本語独自コンテンツとしてのスタイルガイドは未作成だが、下記の資料が参考になります。</p> + +<ul> + <li><a href="https://github.com/mozilla-japan/translation/wiki/L10N-Guideline">Mozilla 関連独自の L10N ガイドライン</a></li> + <li><a href="https://github.com/mozilla-japan/translation/wiki/Editorial-Guideline">Mozilla 関連のドキュメントの表記ガイドライン</a></li> +</ul> +</div> + +<p>MDN 以外のサイトの記事での標準的なスタイルを知りたければ、<a href="http://www.mozilla.org/en-US/styleguide/" title="http://www.mozilla.org/en-US/styleguide/">One Mozilla style guide</a>を参照してください。</p> + +<h2 id="Basics" name="Basics">基本事項</h2> + +<p>よく普及しているスタイルガイドでは、始めるのに最適な場所は、文書の一貫性を維持するのに役立つような、とても基本的なテキストの取り決めです。以下のセクションでは、その基本のアウトラインを示します。</p> + +<h3 id="Page_titles" name="Page_titles">ページタイトル</h3> + +<p>ページタイトルは検索結果や、ページの先頭にあるパンくずリストのページ階層を構造化するために使用されます。 (ページの先頭や検索結果に表示される) ページタイトルは、ページの「スラッグ」とは異なっていても構いません。「スラッグ」とは、ページの URL の "<em><locale>/docs/</em>" に続く部分のことです。</p> + +<h4 id="Title_and_heading_capitalization" name="Title_and_heading_capitalization">タイトルと見出しの大文字・小文字の使用</h4> + +<p>ページタイトルセクションの見出しは文スタイルの大文字化 (文頭と固有名詞の始めの1字だけを大文字にします) を用いるべきです。一般的な見出しスタイルの大文字化は用いません。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: "A new method for creating JavaScript rollovers"</li> + <li><span class="incorrect"><strong>間違い</strong></span>: "A New Method for Creating JavaScript Rollovers"</li> +</ul> + +<p>この表記法が確立するより前の古い記事が多くあります。必要により気軽に書き換えてください。だんだん新しいやり方に慣れていくでしょう。</p> + +<h4 id="Choosing_titles_and_slugs" name="Choosing_titles_and_slugs">タイトルとスラッグの決め方</h4> + +<p>ページのスラッグは短くするべきです。つまり新しい階層を作るとき、スラッグは1つか2つの単語で構成されるようにしましょう。</p> + +<p>一方で、タイトルは常識的な範囲で好きなだけ長くして構いません。また記事の内容がよくわかるものであるべきです。</p> + +<h4 id="Creating_new_subtrees" name="Creating_new_subtrees">サブツリーの新規作成</h4> + +<p>ある主題とその周辺についていくつかの記事を追加する必要があるとき、ふつうはランディングページを作ってから各記事をサブページとして追加します。ランディングページは1つか2つの段落で、トピックやテクノロジーについての説明をします。つぎにそれぞれのページについて説明するサブページ一覧を付け加えます。我々が用意したマクロを利用すれば、一覧にページを追加する作業を自動化できます。</p> + +<p>例えば、<a href="/ja/docs/Web/JavaScript">JavaScript</a> ガイド を見てみましょう。以下のような構造になっています。</p> + +<ul> + <li><a href="/ja/docs/Web/JavaScript/Guide" title="JavaScript/Guide">JavaScript/Guide</a> – メインの目次となるページ</li> + <li><a href="/ja/docs/Web/JavaScript/Guide/JavaScript_Overview" title="JavaScript/Guide/JavaScript_Overview">JavaScript/Guide/JavaScript Overview</a></li> + <li><a href="/ja/docs/JavaScript/Guide/Functions" title="JavaScript/Guide/Functions">JavaScript/Guide/Functions</a></li> + <li><a href="/ja/docs/JavaScript/Guide/Details_of_the_Object_Model" title="JavaScript/Guide/Details_of_the_Object_Model">JavaScript/Guide/Details of the Object Model</a></li> +</ul> + +<p>階層の最上位部に自分の記事を配置しないようにしましょう。サイトのパフォーマンスを下げ、検索とサイト探索を非効率にします。</p> + +<div class="blockIndicator note"> +<p>メモ: 記事を追加するには、<a href="https://wiki.developer.mozilla.org/ja/docs/MDN/Contribute/Howto/Create_and_edit_pages#Getting_page-creation_permissions">ページ作成特権</a>が必要です。</p> +</div> + +<h3 id="General_article_content_guidelines" name="General_article_content_guidelines">全般的な記事内容のガイドライン</h3> + +<p>どんな文書を書くときも、どれくらいの量を言えばいいのかを知ることが重要です。あまりにも長い文章になってしまったり、過剰な詳細を提供してしまったりすると、読むのが面倒になってしまい、誰も使ってくれなくなってしまいます。網羅する量を正しく把握することは、いくつかの理由から重要です。特に、読者が本当に必要な情報を見つけられるようにすること、そして検索エンジンが記事を適切に分析してランク付けできるように十分な質の高い素材を提供することです。</p> + +<p>ここでは前者 (読者が必要としている可能性がある情報を提供すること) について説明します。ページが適切に分類され、検索エンジンにランク付けされるようにすることについて少し学びたい方は、 <a href="/ja/docs/MDN/Contribute/Howto/Write_for_SEO">MDN で SEO を行うための書き方</a>の記事をご覧ください。</p> + +<p>ここでの目標は、読者が必要としている情報を全て含めたページを、あまり長くせずに書くことです。この分野では、いくつかの推奨事項があります。</p> + +<h4 id="Consider_your_audience" name="Consider_your_audience">読み手を意識する</h4> + +<p>これらはガイドラインであることを覚えておいてください。これらのヒントの中には、すべての場合で適用されない場合があります。記事の読者層を意識してください。高度なネットワーク技術に関する記事では、基本的なネットワーキングの概念について、例えばネットワークを使用したコーディングに関する典型的な記事のように詳細に説明する必要はありません。</p> + +<h4 id="有益な概要を提供する">有益な概要を提供する</h4> + +<p>記事の概要、すなわち、最初の見出しの前の段落は、自分が読みたいと思っていることを記事がカバーしているかどうか、読者が理解するのに十分な情報を提供していることを確認してください。</p> + +<p>ガイドやチュートリアルのコンテンツでは、概要は、どのような主題が取り上げられるのか、必要であれば、読者が事前に何を知っておくべきかを読者に知らせなければなりません。文書化または議論されている技術や API について言及し、それらへのリンクを記載し、どのような状況で記事の内容が役に立つかのヒントを提供しなければなりません。</p> + +<h5 id="Example_Too_short!" name="Example_Too_short!">あまりにも短い例</h5> + +<p>この要約の例は、あまりにも短すぎます。 "stroke" Textについてや、テキストが描画される場所や、正確に何を意味するのかなど、あまりにも多くの情報を除外しています。</p> + +<div class="example-bad"> +<p><strong><code>CanvasRenderingContext2D.strokeText()は、文字列を描画します。</code></strong></p> +</div> + +<h5 id="Example_Too_long!" name="Example_Too_long!">長すぎる例</h5> + +<p>ここで、概要を更新しましたが、今度は長すぎます。あまりにも詳細な内容が含まれていて、他のメソッドやプロパティにテキストが入り込みすぎています。</p> + +<p>代わりに、要約は <code>strokeText()</code> メソッドに焦点を当て、他の詳細が提供されている適切なガイドを参照してください。</p> + +<div class="example-bad"> +<p>Canvas 2D API の <strong><code>CanvasRenderingContext2D.strokeText()</code></strong> メソッドは呼び出されると、指定された座標から始まる指定された文字列内の文字を、現在のペンの色を使ってストロークさせます。コンピュータグラフィックスの用語では、テキストを「ストロークする」とは、文字の内容を色で塗りつぶさずに、文字列内のグリフのアウトラインを描くことを意味します。</p> + +<p>テキストは、コンテキストの {{domxref("CanvasRenderingContext2D.font", "font")}} プロパティで指定されたコンテキストの現在のフォントを使用して描画されます。</p> + +<p>指定された座標に対するテキストの相対的な配置は、コンテキストの <code>textAlign</code>, <code>textBaseline</code>, <code>direction</code> プロパティによって決定されます。 <code>textAlign</code> は、指定された X 座標に対する文字列の配置を制御します。値が <code>"center"</code> の場合、文字列は <code>x - (stringWidth / 2)</code> から始まり、文字列の中央に配置するように描画されます。値が <code>"left"</code> の場合は、文字列は指定された X 座標から描画されます。また、 <code>textAlign</code> が <code>"right"</code> の場合は、指定されたX座標で終わるように描画されます。</p> + +<p>(等 等 等...)</p> + +<p>オプションで、4 番目の引数を指定して文字列の最大幅をピクセル単位で指定することもできます。この引数を指定すると、テキストは水平方向に圧縮されるか、描画時にその幅の空間に収まるように拡大縮小 (あるいは調整) されます。</p> + +<p><strong><code>fillText()</code></strong> メソッドを呼び出すことで、文字列の輪郭のみを描画するのではなく、文字列の文字を色で塗りつぶすことができます。</p> +</div> + +<h5 id="Example_Much_better!" name="Example_Much_better!">はるかに良い例</h5> + +<p>ここで、 <code>strokeText()</code> メソッドのより良い概要を見てみましょう。</p> + +<div class="example-good"> +<p>{{domxref("CanvasRenderingContext2D")}} の <code><strong>strokeText()</strong></code> メソッドは、 <a href="/en-US/docs/Web/API/Canvas_API">Canvas 2D API</a> の一部で、指定された文字列の文字の輪郭を、指定された X 座標と Y 座標で示された位置に描画します。テキストは、コンテキストの現在の {{domxref("CanvasRenderingContext2D.font", "font")}} を使用して描画され、 {{domxref("CanvasRenderingContext2D.textAlign", "textAlign")}}, {{domxref("CanvasRenderingContext2D.textBaseline", "textBaseline")}}, {{domxref("CanvasRenderingContext2D.direction", "direction")}} の各プロパティに従って揃えられます。</p> + +<p>詳細とさらなる例については、学習エリアの<a href="/ja/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics">図形の描画</a>の<a href="/ja/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics#Text">テキスト</a>や、このテーマに関するメインの記事「<a href="/ja/docs/Web/API/Canvas_API/Tutorial/Drawing_text">テキストの描画</a>」を参照してください。</p> +</div> + +<h4 id="Include_all_relevant_examples" name="Include_all_relevant_examples">関連するすべての例を含める</h4> + +<p>例があるページは、ないページよりも多くなるべきです。実際、多くのページには複数の例があるはずです。</p> + +<p>重要なことは、例を使用して、すべての引数が何のために使用されるのかを明確にし、存在する可能性のある希少な例を明確にすることです。また、一般的なタスクの解決策を示すために例を使用し、発生する可能性のある問題の解決策を示すために例を使用する必要があります。</p> + +<p>それぞれの例は、例を読んだり試してみたりする前に、その例が何をするのか、読み始める前に読者が知っておくべきことは何かを説明する文章が必要です。</p> + +<h5 id="Code_Examples" name="Code_Examples">コードの例</h5> + +<p>コードの各部分では、それがどのように動作するかを説明する必要があります。大きなコードを小さな部分に分割して、個別に説明できるようにしたほうが理解しやすいかもしれないということに留意してください。</p> + +<p>コードの各部分に続く文章は、適切なレベルの詳細を使用して、関連性のあるものを説明する必要があります。</p> + +<ul> + <li>If the code is very simple and doesn't really feature anything directly related to the API being documented, you may only give a quick summary of what it is and why it's there.</li> + <li>If the code is intricate, uses the API being documented, or is technically creative, you should provide a more detailed explanation.</li> +</ul> + +<p>When using the live sample system, it's helpful to be aware that all of the {{HTMLElement("pre")}} blocks in the area that contains the sample are concatenated together before running the example, which lets you break any or all of the HTML, CSS, and JavaScript into multiple segments, each optionally with its own descriptions, headings, and so forth. This makes documenting code incredibly powerful and flexible.</p> + +<h4 id="Overly-short_articles_are_hard_to_find">Overly-short articles are hard to find</h4> + +<p>If an article is "thin"—that is, too short—it may not be indexed properly (or at all) by search engines. As a rule of thumb, the article's body text should be at least 250–300 words. Don't artificially inflate a page, but treat this guideline as a minimum target length when possible.</p> + +<h3 id="Sections.2C_Paragraphs.2C_Newlines" name="Sections.2C_Paragraphs.2C_Newlines">セクション、段落、改行</h3> + +<p>降順に見出しレベルを使い分けてください。 {{HTMLElement("h2")}}, {{HTMLElement("h3")}}, {{HTMLElement("h4")}} という順に、途中を飛ばさず使って下さい。</p> + +<p>H2 が最高の見出しレベルなのは H1 がページタイトルのために用意されているからです。H3 、H4 より深いレベルの見出しが必要になったときは、小さい記事に分割し、ランディングページにまとめて{{TemplateLink("Next")}}, {{TemplateLink("Previous")}}, {{TemplateLink("PreviousNext")}} マクロでリンクすることを考慮してみてください。</p> + +<h4 id="Heading_dos_and_donts" name="Heading_dos_and_donts">見出しで行うことと行ってはいけないこと</h4> + +<ul> + <li>単独のサブセクションを作らないでください。トピックを一つに分割するというのは意味のわからないことです。2つ以上のサブ見出しを用意するか、まったくないかのどちらかです。</li> + <li>見出しの中でスタイルやクラスを使わないようにしましょう。これには、コード用語を書くための {{HTMLElement("code")}} 要素も含まれます。ですから、「<code>SuperAmazingThing</code> インターフェイスの使用」というような見出しを作らないようにしましょう。その代わりに、「SuperAmazingThing インターフェイスの使用」だけにすべきです。</li> + <li>見出し内でのマクロを使用することは避けてください (見出し内で使用するように特別に設計された特定のマクロを除く)。</li> + <li>見出しの後に内容のテキストをはさまずに小見出しが続く、 "bumping heads" を作らないようにしましょう。これは見栄えが悪く、読者には外側のセクションの最初に何の説明もないままになってしまいます。</li> +</ul> + +<p>キーボードで <kbd>Enter</kbd> (または <kbd>Return</kbd>) キーを押すと、新たな段落が始まります。新しい段落ではなく改行を挿入するには (つまり、 {{HTMLElement("br")}} を {{HTMLElement("p")}} の代わりに生成する場合は)、 <kbd>Shift</kbd> キーを押しながら <kbd>Enter</kbd> キーを押してください。</p> + +<h3 id="Lists">Lists</h3> + +<p>Lists should be formatted and structured uniformly across all contributions. Individual list items should be written with suitable punctuation, regardless of the list format. However, depending on the type of list you are creating, you will want to adjust your writing as described in the sections below.</p> + +<h4 id="Bulleted_lists">Bulleted lists</h4> + +<p>Bulleted lists should be used to group related pieces of concise information. Each item in the list should follow a similar sentence structure. Phrases and sentences in bulleted lists should include standard punctuation. Periods must appear at the end of each sentence in a bulleted list, including the item's final sentence, just as would be expected in a paragraph.</p> + +<p>An example of a correctly structured bulleted list:</p> + +<div class="example-good"> +<p>In this example we should include:</p> + +<ul> + <li>A condition, with a brief explanation.</li> + <li>A similar condition, with a brief explanation.</li> + <li>Yet another condition, with some further explanation.</li> +</ul> +</div> + +<p>Note how the same sentence structure repeats from bullet to bullet. In this example, each bullet point states a condition followed by a comma and a brief explanation, and each item in the list ends with a period.</p> + +<h4 id="Numbered_lists">Numbered lists</h4> + +<p>Numbered lists are used primarily to enumerate steps in a set of instructions. Because instructions can be complex, clarity is a priority, especially if the text in each list item is lengthy. As with bulleted lists, follow standard punctuation usage.</p> + +<p>An example of a correctly structured numbered list:</p> + +<div class="example-good"> +<p>In order to correctly structure a numbered list, you should:</p> + +<ol> + <li>Open with a heading or brief paragraph to introduce the instructions. It's important to provide the user with context before beginning the instructions.</li> + <li>Start creating your instructions, and keep each step in its own numbered item. Your instructions may be quite extensive, so it is important to write clearly and use correct punctuation.</li> + <li>After you have finished your instructions, close off the numbered list with a brief summary or explanation of the expected outcome upon completion.</li> +</ol> + +<p>This is an example of writing a closing explanation. We have created a short numbered list that provides instructive steps to produce a numbered list with the correct formatting.</p> +</div> + +<p>Note how the items in numbered lists read like short paragraphs. Because numbered lists are routinely used for instructional purposes, or to walk someone through an orderly procedure, be sure to keep each item focused: one item per number or step.</p> + +<h3 id="Text_Formatting" name="Text_Formatting">テキストの書式とスタイル</h3> + +<p>「スタイル」ドロップダウンリストを使うと、あらかじめ設定されたスタイルを選択範囲に適用できます。</p> + +<div class="note"><strong>"Note Box"</strong> スタイルは重要な注意を呼びかけるのに使われます。こんな感じです。</div> + +<div class="warning">同様に <strong>"Warning Box"</strong> は警告ボックスをこのように作成します。</div> + +<p>特別に指示された場合でない限り、 HTML の <code>style</code> 属性を手作業で付加<em>しない</em>ようにしてください。既存のクラスでうまくいかなければ、 <a href="https://discourse.mozilla.org/c/mdn">MDN discussion forum</a> で質問してみてください。</p> + +<h3 id="Code_sample_style_and_formatting" name="Code_sample_style_and_formatting">コードサンプルのスタイルと書式</h3> + +<div class="note"> +<p><strong>メモ</strong>: この節では、 MDN の記事に表示されるコードのスタイルや書式について扱います。実際にコード例を書くためのガイドラインが必要な場合は、 <a href="/ja/docs/MDN/Contribute/Guidelines/Code_samples">コード例のガイドライン</a> を参照してください。</p> +</div> + +<h4 id="Tabs_and_line_breaks" name="Tabs_and_line_breaks">タブと改行</h4> + +<p>タブは空白2つで統一して下さい。コードは綺麗にインデントしてください。始めの中括弧（"<code>{</code>"）は行頭に置きません。ブロック宣言の直後に配置します。</p> + +<pre class="brush: js notranslate">if (condition) { + /* handle the condition */ +} else { + /* handle the "else" case */ +} +</pre> + +<p>Long lines shouldn't be allowed to stretch off horizontally to the extent that they require horizontal scrolling to read. Instead, break at natural breaking points. Some examples follow:</p> + +<pre class="brush: js notranslate">if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION + || class.YET_ANOTHER_CONDITION ) { + /* something */ +} + +var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"] + .createInstance(Components.interfaces.nsIToolkitProfileService); +</pre> + +<h4 id="Inline_code_formatting" name="Inline_code_formatting">インラインコードの書式</h4> + +<p>「コード」ボタン ("<>" という山括弧記号が付いています) を使ってください。インライン コード スタイルの書式を関数名、変数名、メソッド名に適用することができます (これは、 {{HTMLElement("code")}} 要素を使います)。例えば、 "<code class="js plain">frenchText()</code> 関数" のようにします。。</p> + +<p>メソッド名の後には括弧をつけるべきです: <code>doSomethingUseful()</code> のように。括弧があることでメソッドとその他のコードの用語を区別できます。</p> + +<h4 id="Syntax_highlighting" name="Syntax_highlighting">構文の強調表示</h4> + +<p><img alt="Screenshot of the 'Syntax Highlighter' menu." src="https://mdn.mozillademos.org/files/12682/Language%20list.png" style="border-style: solid; border-width: 1px; float: right; margin: 2px 4px;">コード行全体（もしくは数行のコード）は構文の強調表示によってフォーマットされるのが好ましく、{{HTMLElement("code")}}要素は使われるべきではありません。ツールバーの"pre"ボタンをクリックしてください。書式設定されたコンテンツボックスが挿入されます。そこにコードを入力しましょう。それからテキスト入力カーソルをコンテンツボックス内に置いたまま、右図のように"pre"ボタンの右にあるリストボタンから適切な言語を選択しましょう。以下の例は JavaScript の書式です。</p> + +<div class="note"> +<p><strong>メモ:</strong> {{HTMLElement("code")}} 要素を {{HTMLElement("pre")}} ブロック内で使用<em>しない</em>でください。</p> + +<p>この構造はいくつかのサイトで使用されていますが、 MDN では使用していません。これらの要素を入れ子にすると、私たちのスタイル付けの一部が壊れます。</p> +</div> + +<p>The following example shows text with JavaScript formatting:</p> + +<div class="line number2 index1 alt1"> +<pre class="brush: js notranslate">for (let i = 0, j = 9; i <= 9; i++, j--) + document.writeln("a[" + i + "][" + j + "]= " + a[i][j]);</pre> +</div> + +<p>探している言語が見当たらなければ、言語を指定せずに<code> pre</code> タグを利用して下さい (リストの"No Highlight"を選びます)。</p> + +<pre class="brush: plain notranslate">x = 42;</pre> + +<h4 id="Syntax_definitions" name="Syntax_definitions">構文の定義</h4> + +<p>構文の定義を挿入する場合には、エディターのツールバーの「スタイル」ドロップダウンメニューから、 <em>"Syntax Box"</em> を選択してください。これは、他のコードブロックとは別に、構文定義専用の特別に書式化されたボックスを作成します。</p> + +<h4 id="コードを参照しないブロック">コードを参照しないブロック</h4> + +<p>There are a few use cases where a <code><pre></code> block does not refer to code and doesn't have syntax highlighting nor line numbers. In such cases you should add a <code><pre></code> without a <code>class</code> attribute. Those cases include things like tree structures:</p> + +<pre class="notranslate">root/ + + folder1/ + file1 + + folder2/ + file2 + file3 +</pre> + +<p>To create preformatted content without syntax highlighting and line numbers click the "pre" button in the toolbar. Then start to type the text.</p> + +<h4 id="Styling_mentions_of_HTML_elements" name="Styling_mentions_of_HTML_elements">HTML 要素に言及する際のスタイル</h4> + +<p>HTML 要素について記述する際に従うべき特定の規則があります。これらの規則によって、要素とその構成部分についての説明に一貫性が生まれます。また、詳細な説明への適切なリンクを保証することもできます。</p> + +<dl> + <dt>要素名</dt> + <dd>{{TemplateLink("HTMLElement")}} マクロを使ってその要素のページへのリンクを生成します。例えば \{{HTMLElement("title")}} と書けば、 "{{HTMLElement("title")}}" と出力されます。リンクを生成したくなければ、<strong>名前を山括弧に入れて</strong> "Inline Code" スタイルを使用してください (例えば <code><title></code>)。</dd> + <dt>属性名</dt> + <dd>"Inline Code" スタイルを使用して属性名を<code>コードフォント</code>に入れてください。加えて、属性が何をするのかの説明に関連して言及された場合、または文書中で最初に使用された場合は <strong><code>太字フォント</code></strong> を使用してください。</dd> + <dt>属性の定義</dt> + <dd>属性名の定義には {{TemplateLink("htmlattrdef")}} マクロを使用してください (例えば、<span class="nowiki">\{{htmlattrdef("type")}}</span>)。そうすれば他のページから属性の定義を参照するために、 {{TemplateLink("htmlattrxref")}} マクロを使用するだけで簡単にリンクすることができます (例えば <span class="nowiki">\{{htmlattrxref("attr","element")}}</span></dd> + <dt>属性値</dt> + <dd>属性値に <code><code></code> を適用するために "Inline Code" スタイルを使用し、文字列の値はコード例の構文で必要がない限り、引用符で囲まないでください。</dd> + <dd>例: 「<code><input></code> 要素の <code>type</code> 属性が <code>email</code> または <code>tel</code> に設定されている場合...」</dd> +</dl> + +<h3 id="Latin_abbreviations" name="Latin_abbreviations">ラテン文字の略記</h3> + +<h4 id="In_notes_and_parentheses" name="In_notes_and_parentheses">注釈と括弧内で</h4> + +<ul> + <li>よく使われるラテン語の略記（etc.、i.e.、e.g.）は括弧や注釈の中で使用できます。略記にはピリオドを使用してください。 + <ul> + <li><span class="correct"><strong>正しい</strong></span>: Web browsers (e.g. Firefox) can be used ...</li> + <li><span class="incorrect"><strong>間違い</strong></span>: Web browsers e.g. Firefox can be used ...</li> + <li><span class="incorrect"><strong>間違い</strong></span>: Web browsers, e.g. Firefox, can be used ...</li> + <li><span class="incorrect"><strong>間違い</strong></span>: Web browsers, (eg: Firefox) can be used ...</li> + </ul> + </li> +</ul> + +<h4 id="In_running_text" name="In_running_text">通常の文で</h4> + +<ul> + <li>通常の文では（つまり注釈や括弧の外で）、英語における同等の表現を使用してください。 + <ul> + <li><span class="correct"><strong>正しい</strong></span>: ... web browsers, and so on.</li> + <li><span class="incorrect"><strong>間違い</strong></span>: ... web browsers, etc.</li> + <li><span class="correct"><strong>正しい</strong></span>: Web browsers such as Firefox can be used ...</li> + <li><span class="incorrect"><strong>間違い</strong></span>: Web browsers e.g. Firefox can be used ...</li> + </ul> + </li> +</ul> + +<h4 id="Meanings_and_English_equivalents_of_Latin_abbreviations" name="Meanings_and_English_equivalents_of_Latin_abbreviations">ラテン語の略記表現と対応する英語表現</h4> + +<table class="fullwidth-table"> + <thead> + <tr> + <th scope="col">略記</th> + <th scope="col">ラテン語</th> + <th scope="col">英語</th> + </tr> + </thead> + <tbody> + <tr> + <td>cf.</td> + <td><em>confer</em></td> + <td>compare</td> + </tr> + <tr> + <td>e.g.</td> + <td><em>exempli gratia</em></td> + <td>for example</td> + </tr> + <tr> + <td>et al.</td> + <td><em>et alii</em></td> + <td>and others</td> + </tr> + <tr> + <td>etc.</td> + <td><em>et cetera</em></td> + <td>and so forth, and so on</td> + </tr> + <tr> + <td>i.e.</td> + <td><em>id est</em></td> + <td>that is, in other words</td> + </tr> + <tr> + <td>N.B.</td> + <td><em>nota bene</em></td> + <td>note well</td> + </tr> + <tr> + <td>P.S.</td> + <td><em>post scriptum</em></td> + <td>postscript</td> + </tr> + </tbody> +</table> + +<div class="note"> +<p>ラテン語の略記表現が有用かどうか常に考えるようにしましょう。めったに使われないようなものは、多くの読者にとっては理解できず、他のものと勘違いしてしまうこともありえます。</p> + +<p>使用する<em>あなた</em>が正しく使用することを肝に銘じてください。例えば、 "e.g." と "i.e." の取り違えはよくある間違いです。</p> +</div> + +<h3 id="Acronyms_and_abbreviations" name="Acronyms_and_abbreviations">頭字語と略語</h3> + +<h4 id="Capitalization_and_periods" name="Capitalization_and_periods">大文字とピリオド</h4> + +<p>頭字語と略語において、全て大文字とし、ピリオドは使用しないでください。組織の略称もこれに含まれます。"US"や"UN"などです。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: XUL</li> + <li><span class="incorrect"><strong>間違い</strong></span>: X.U.L.; Xul</li> +</ul> + +<h4 id="Expansion" name="Expansion">略語の展開</h4> + +<p>ある用語についてページ内で初めて言及がある場合は、ユーザにとって馴染みがないと思われる略語を展開しましょう。よく分からなければ、展開するかもしくは記事や、用語の説明をする <a href="/en-US/docs/Glossary">glossary</a> の項目へのリンクを貼りましょう。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: "XUL (XML User Interface Language) is Mozilla's XML-based language..."</li> + <li><strong>間違い</strong>: "XUL is Mozilla's XML-based language..."</li> +</ul> + +<h4 id="Plurals_of_acronyms_and_abbreviations" name="Plurals_of_acronyms_and_abbreviations">頭字語と略語の複数形</h4> + +<p>頭字語と略語の複数形については、<em>s </em>を末尾に付加するだけにしてください。アポストロフィは使用しないでください。絶対に。お願いします。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: CD-ROMs</li> + <li><span class="incorrect"><strong>間違い</strong></span>: CD-ROM's</li> +</ul> + +<h4 id="Versus_vs._and_v.">"Versus", "vs.", and "v."</h4> + +<p>The contraction "vs." is preferred.</p> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: this vs. that</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: this v. that</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: this versus that</li> +</ul> + +<h3 id="Capitalization" name="Capitalization">大文字の使用</h3> + +<p>Use standard English capitalization rules in body text, and capitalize "World Wide Web." It is acceptable to use lower case for "web" (used alone or as a modifier) and "internet;" this guideline is a change from a previous version of this guide, so you may find many instances of "Web" and "Internet" on MDN. Feel free to change these as you are making other changes, but editing an article just to change capitalization is not necessary.</p> + +<p>Keyboard keys should use sentence-style capitalization, not all-caps capitalization. For example, "Enter" not "ENTER." The only exception is that if you wish to abbreviate the name of the "Escape" key, you may use "ESC".</p> + +<p>Certain words should always be capitalized (such as trademarks which include capital letters), or words derived from the name of a person (unless it's being used within code, and the rules of the language in which the code is written mandate lower-casing). Some examples:</p> + +<ul> + <li>Boolean (named for English mathematician and logician {{interwiki("wikipedia", "George Boole")}})</li> + <li>JavaScript (a trademark of Oracle Corporation, it should always be written as trademarked)</li> + <li>Python, TypeScript, Django, and other programming languages and framework names</li> +</ul> + +<h3 id="Contractions" name="Contractions">短縮形</h3> + +<p>書体はカジュアルで構いません。なので気軽に短縮形を使ってください (例えば、"don't"、"can't"、"shouldn't")。無理にとは言いません。</p> + +<h3 id="Pluralization" name="Pluralization">複数形</h3> + +<p>英語におけるやり方にしてください。ラテン語やギリシア語に影響を受けた形は使わないでください。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: syllabuses, octopuses</li> + <li><span class="incorrect"><strong>間違い</strong></span>: syllabi, octopi</li> +</ul> + +<h3 id="Hyphenation" name="Hyphenation">ハイフンを用いた複合語</h3> + +<p>接頭辞と後に続く語間で同じ母音が連続する場合にハイフンを使用してください。</p> + +<ul> + <li><font color="green"><strong>正しい</strong></font>: email, re-elect, co-op</li> + <li><font color="red"><strong>間違い</strong></font>: e-mail, reelect, coop</li> +</ul> + +<h3 id="Gender-neutral_language" name="Gender-neutral_language">性別に中立な言葉</h3> + +<p>主題に性別が関係ない場合には、性別に中立な言葉を使って、できるだけ包括的な文章にするのが良いでしょう。例えば、特定の男性の行動について話している場合は、 "he"/"his" を使用しても問題ありませんが、主語がどちらでもありうる場合は、 "he"/"his" は適切ではありません。<br> + <br> + 以下に例をあげましょう。</p> + +<blockquote> +<p>A confirmation dialog appears, asking the user if he allows the Web page to make use of his Web cam.</p> +</blockquote> + +<blockquote> +<p>A confirmation dialog appears, asking the user if she allows the Web page to make use of her Web cam.</p> +</blockquote> + +<p>どちらも性的に偏りがある表現です。性別に中立な代名詞に修正しましょう:</p> + +<blockquote> +<p>A confirmation dialog appears, asking the user if they allow the Web page to make use of their Web cam.</p> +</blockquote> + +<div class="note"> +<p>MDN では、このとても一般的な構文 (これは使用法の権威の間で論争の的となっている) を使用して、英語の中性的な性別の欠如を補うことを許可しています。</p> + +<p>三人称複数型を中性名詞として使う (つまり、"they"、"them"、"their"、"theirs" を使う) ことは許容されるやり方で、一般には "<a href="http://en.wikipedia.org/wiki/Singular_they">単数形の 'they'</a>" として知られています。</p> +</div> + +<p>両方の性についての記述することもできます。</p> + +<blockquote> +<p>A confirmation dialog appears, asking the user if he or she allows the web page to make use of his/her web cam.</p> +</blockquote> + +<p>ユーザを複数とするとこうなります。</p> + +<blockquote> +<p>A confirmation dialog appears, asking the users if they allow the web page to make use of their web cams.</p> +</blockquote> + +<p>もちろん一番良い解決法は、代名詞を使用しないよう書き直すことです。</p> + +<blockquote> +<p>A confirmation dialog appears, requesting the user's permission for web cam access.</p> +</blockquote> + +<blockquote> +<p>A confirmation dialog box appears, which asks the user for permission to use the web cam.</p> +</blockquote> + +<p>最後の手段がおそらく、より良い手段と言えるでしょう。これは文法的に正しいだけでなく、性別の規則が大きく異なる可能性のある異なる言語間で、性別の取り扱いに関連した複雑さを軽減することができます。この解決策は、読者と翻訳者の両方にとって、翻訳をより簡単にすることができます。</p> + +<h3 id="Numbers_and_numerals" name="Numbers_and_numerals">数字と数詞</h3> + +<h4 id="Dates" name="Dates">日付</h4> + +<p>日付については（コード中の日付は関係ありません）、 "January 1, 1990" のような書式を使用してください。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: February 24, 2006</li> + <li><span class="incorrect"><strong>間違い</strong></span>: February 24th, 2006; 24 February, 2006; 24/02/2006</li> +</ul> + +<p>YYYY/MM/DD フォーマットを使っても構いません。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: 2006/02/24</li> + <li><span class="incorrect"><strong>間違い</strong></span>: 02/24/2006; 24/02/2006; 02/24/06</li> +</ul> + +<h4 id="Decades" name="Decades">年代の表現</h4> + +<p>年代の表現には、 "1990s" の書式を使って下さい。アポストロフィはいりません。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: 1990s</li> + <li><span class="incorrect"><strong>間違い</strong></span>: 1990's</li> +</ul> + +<h4 id="Plurals_of_numerals" name="Plurals_of_numerals">数詞の複数形</h4> + +<p>数詞の複数形には"s"を付加してください。アポストロフィはいりません。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: 486s</li> + <li><span class="incorrect"><strong>間違い</strong></span>: 486's</li> +</ul> + +<h4 id="Commas" name="Commas">カンマ</h4> + +<p>通常の文では、5桁以上の数字にだけカンマを使用してください。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: 4000; 54,000</li> + <li><span class="incorrect"><strong>間違い</strong></span>: 4,000; 54000</li> +</ul> + +<h3 id="Punctuation" name="Punctuation">句読点</h3> + +<h4 id="Serial_comma" name="Serial_comma">Serial Comma（連続のカンマ）</h4> + +<p><strong>Serial comma（連続のカンマ）を使用してください</strong>。 Serial Comma または "Oxford" comma（オックスフォードカンマ）としても知られるこのカンマは、3つ以上の文を並列する際に接続詞の直前に置きます。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: I will travel on trains, planes, and automobiles.</li> + <li><span class="incorrect"><strong>間違い</strong></span>: I will travel on trains, planes and automobiles.</li> +</ul> + +<div class="note"> +<p><strong>注記:</strong> これは <a href="http://www.mozilla.org/en-US/styleguide/" title="http://www.mozilla.org/en-US/styleguide/">One Mozilla style guide</a> のやり方とは対対照的です。Serial Comma （連続のカンマ）は使われないと明記しています。MDN のやり方はこのルールの例外です。</p> +</div> + +<h4 id="Apostrophes_and_quotation_marks" name="Apostrophes_and_quotation_marks">引用符と疑問符</h4> + +<p><strong>「曲がった」引用符と疑問符を使用しないで下し。</strong> MDN では、直線の引用符とアポストロフィのみを使用してください。</p> + +<p>これにはいくつかの理由があります。</p> + +<ol> + <li>一貫性のためにどちらかを選択しなければなりません。</li> + <li>曲がった引用符やアポストロフィがコードスニペットの中に入ってくると、インラインのものであっても、読み手はそれらをコピーして貼り付け、動作することを期待してしまうかもしれません (そうはならないでしょう)。</li> +</ol> + +<ul> + <li><span class="correct"><strong>Correct</strong></span>: Please don't use "curly quotes."</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: Please don’t use “curly quotes.”</li> +</ul> + +<h3 id="Spelling" name="Spelling">綴りの統一</h3> + +<p>綴りにゆれがある単語については、常にアメリカ英語の綴りを使用してください。</p> + +<p>一般的には、 <a href="http://www.dictionary.com/">Dictionary.com</a> の最初の項目を使用しますが、その項目が変種の綴りとして記載されていたり、主にアメリカ以外の英語の形で使用されている場合を除きます。例えば、 <a href="http://www.dictionary.com/browse/behaviour">"behavior" を検索</a>すると、 "Chiefly British" という言葉の後に、アメリカの標準形である "<a href="http://dictionary.reference.com/browse/behavior">behavior</a>" へのリンクが表示されます。変形スペルは使わないようにしましょう。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: localize, behavior</li> + <li><span class="incorrect"><strong>間違い</strong></span>: localise, behaviour</li> +</ul> + +<h3 id="Terminology" name="Terminology">用語</h3> + +<h4 id="HTML_elements" name="HTML_elements">HTML 要素</h4> + +<p>HTML や XML の要素を表すには「要素」を使用し、「タグ」を使用しないでください。加えて、基本的に常に「<>」で囲んで記述し、 {{HTMLElement("code")}} スタイルの中に入れてください。</p> + +<p>その要素を節の中で初めて参照するときは、 {{TemplateLink("HTMLElement")}} マクロを使用して要素の文書へのリンクを作成してください (その要素のリファレンス文書ページ内で書いている場合を除く)。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: the {{HTMLElement("span")}} element</li> + <li><span class="incorrect"><strong>間違い</strong></span>: the span tag</li> +</ul> + +<h4 id="Parameters_vs._arguments" name="Parameters_vs._arguments">parameter と argument</h4> + +<p>MDN で推奨する用語は <strong>parameter</strong> です。一貫性のためにできるだけ "argument" の用語は使用しないでください。</p> + +<h4 id="User_interface_actions" name="User_interface_actions">ユーザーインターフェイス操作</h4> + +<p>一連の作業を記述する際には、命令調でインターフェイスでの操作を指示しましょう。ユーザインターフェイスの要素をラベルと種類ではっきりと指定しましょう。</p> + +<ul> + <li><span class="correct"><strong>正しい</strong></span>: Click the Edit button.</li> + <li><span class="incorrect"><strong>間違い</strong></span>: Click Edit.</li> +</ul> + +<h3 id="Voice" name="Voice">能動態と受動態</h3> + +<p>能動態が一般的には好ましいですが、MDN の堅苦しくない雰囲気から考えると受動態も問題ありません。けれど、どちらか首尾一貫させる意識は必要です。</p> + +<h2 id="Wiki_のマークアップとその用法">Wiki のマークアップとその用法</h2> + +<h3 id="リンク">リンク</h3> + +<p>wikiが協力な学習・教育ツールとなるのに、大半はリンクのおかげです。以下にいくつかの基本情報がありますが、完全なガイドは編集ガイド内の <a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Editor/Links">MDNでリンクを作成・編集する</a> で見る事ができます。</p> + +<p>We encourage you to create appropriate links among articles; they help improve navigation and discoverability of content, and they provide important context to search engines like Google to help them provide better results. Every page should have a good set of links from words or phrases to other pages that expand upon the relevant ideas. This can be used both to define terms and to provide more in-depth or detailed documentation about a topic, or to connect to a related page that offers examples or information that may be of further interest.</p> + +<p>You can easily create links not only among pages on MDN (internal links) but also to pages outside MDN (external links).</p> + +<p>There are two ways to create links: you explicitly create a link using the Link button in the editor's toolbar—or by pressing <kbd>Ctrl</kbd>+<kbd>K</kbd> (<kbd>Cmd</kbd>-<kbd>K</kbd> on the Mac)—or you can use MDN's powerful macro system to generate links automatically or based on an input value.</p> + +<p>When deciding what text to use as a link, there are a few guidelines you can follow:</p> + +<ul> + <li>Whenever a macro exists which will create the link you need, and you are able to do so, please do. <a href="/en-US/docs/MDN/Contribute/Editor/Links#Using_link_macros">Using macros to create links</a> will not only help you get it right, but will allow future improvements to MDN to automatically be applied to your link.</li> + <li>For an API name, use the entire string of the API term as written in your content. The easiest way to do this is to <a href="/en-US/docs/MDN/Contribute/Editor/Links#Linking_to_documentation_for_APIs">use the appropriate macro</a> to construct a properly-formatted link for you.</li> + <li>For a term for which you're linking to a page defining or discussing that term, use the name of the term and no additional text as the link's text. For example: + <ul> + <li><span class="correct"><strong>Correct</strong></span>: You can use <a href="/en-US/docs/Web/JavaScript">JavaScript</a> code to create dynamic applications on the Web.</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: You can use <a href="/en-US/docs/Web/JavaScript">JavaScript code</a> to create dynamic applications on the Web.</li> + </ul> + </li> + <li>Otherwise, when adding a useful link to prose, try to choose an action and object phrase, such as: + <ul> + <li><span class="correct"><strong>Correct</strong></span>: If you'd like to <a href="/en-US/docs/Mozilla/Developer_guide">contribute to the Firefox project</a>, your first step is to <a href="/en-US/docs/Mozilla/Developer_guide/Build_Instructions">download and build Firefox</a>.</li> + <li><span class="incorrect"><strong>Incorrect</strong></span>: <a href="/en-US/docs/Mozilla/Developer_guide">If you'd like to contribute to the Firefox project</a>, your first step is to <a href="/en-US/docs/Mozilla/Developer_guide/Build_Instructions">download and build</a> Firefox.</li> + </ul> + </li> +</ul> + +<h4 id="URL_schemes" name="URL_schemes">URL スキーム</h4> + +<p>セキュリティの理由から、下記のスキームを使用したリンクだけを作成すべきです:</p> + +<ul> + <li><code>http://</code></li> + <li><code>https://</code></li> + <li><code>ftp://</code></li> + <li><code>mailto:</code></li> +</ul> + +<p>これ以外は動作したりしなかったりしますが、サポートされません。おそらく編集スタッフによって削除されるでしょう。</p> + +<div class="note"> +<p>特に、 <code>about:</code> や <code>chrome://</code> スキームは、動作しないので使用しないでください。同様に <code>javascript:</code> スキームは現代のたいていのブラウザーからブロックされ、<code>jar:</code> も同様です。</p> +</div> + +<h3 id="Page_tags" name="Page_tags">ページタグ</h3> + +<p>タグはページについてのメタ情報を提示するか、内容に改善すべき点があるということを示します。あるいはその両方です。 Wiki のどのページもタグづけする必要があります。</p> + +<p>タグ付けのやり方については<a href="/ja/docs/MDN/Contribute/Howto/Tag">適切にタグづけする方法</a>のガイドに詳しい説明があります。</p> + +<p>タグのインターフェイスは編集モードにおいて、ページ下部で機能しています。以下のような感じです。</p> + +<p><img alt="Screenshot of the UX for adding and removing tags on MDN" src="https://mdn.mozillademos.org/files/7859/tag-interface.png" style="border-style: solid; border-width: 1px; height: 167px; width: 863px;"></p> + +<p>タグを追加するには、タグリスト末尾の編集ボックスをクリックしてタグ名を入力します。タグには補完機能があります。Enter (かreturn) キーで新規タグを投稿できます。どの記事も必要なだけタグを追加してよいです。例えば、AJAX プログラミングにおける JavaScript の記事には "JavaScript" と "AJAX" のどちらのタグも必要でしょう。</p> + +<p>タグを削除するには、タグアイコンの "X" をクリックしてください。</p> + +<h4 id="手を加える必要がある記事にタグをつける">手を加える必要がある記事にタグをつける</h4> + +<p>記事の品質と内容についての情報を示すためだけでなく、ある種の作業が必要な記事にもタグをつけることがあります。</p> + +<h4 id="古くなったページにタグをつける">古くなったページにタグをつける</h4> + +<p>現状に即していない記事には以下のタグをつけてください。</p> + +<dl> + <dt>Junk</dt> + <dd>スパム記事、誤って作られたページ、見る価値の無い劣悪なページにはこのタグをつけて下さい。このタグがつけられたページは定期的に削除されます。</dd> + <dt>Obsolete</dt> + <dd>技術的に既に古いが、ある文脈上では使用されうることについての記事にはこのタグをつけて下さい。例えば、 HTML5 では時代遅れな HTML 要素も HTML 4.01 ではまだ有効です。そのトピックについて <span class="nowiki">{{TemplateLink("obsolete_header")}}</span> マクロを使って目印をつけることができます。</dd> + <dt>Archive</dt> + <dd>技術的に既に古く、もはや役に立たないものにはこのタグをつけてください。できれば、読者にもっと新しい記事を読むように促す注記をつけてください。例えば、 Mozilla CVS リポジトリをどのように使うかについての記事は Mercurial リポジトリについての新しい記事に読者を誘導するべきでしょう (対応する記事が存在しなければ、<em>NeedsUpdate </em>タグをつけてください。そして Talk ページに説明を加えて下さい)。 Archive タグのつけられた記事はそのうち、 MDN の主要部分から <a href="/ja/docs/Archive">Archive</a> セクションへと移されます。</dd> +</dl> + +<h3 id="SEO_summary">SEO summary</h3> + +<p>SEO summary は簡潔なページの概要です。サイトを巡回するプログラムに記事の概要として渡され、ページの検索結果として表示されます。 MDN のランディングページの作成を自動化するマクロにも利用されます。 (すなわち、 SEO ためだけのものではありません。)</p> + +<p>デフォルトでは、ページ最初の段落が SEO summary として利用されます。しかし、<a href="/ja/docs/Project:MDN/Contributing/Editor_guide/Editing#Formatting_styles">WYSIWYGエディタ内の "SEO summary" スタイル</a>を利用してセクションをマークすることで上書きすることができます。</p> + +<h3 id="ランディングページ">ランディングページ</h3> + +<p><strong>ランディングページ</strong> はサイトにおける、ある分野の起点となるページです。例えば <a href="/ja/docs/CSS" title="CSS">CSS</a> や <a href="/ja/docs/HTML" title="HTML">HTML</a> のメインページです。下記の３エリアからなる標準的なフォーマットがあります。</p> + +<ol> + <li>その技術がどういうもので、どのように使用されるかについての簡潔な（大抵はひとつのパラグラフからなる）概観。詳しくは {{anch("Writing a landing page overview")}} を参照してください。</li> + <li>適切に見出しがつけられた、2段組のリンクリスト。{{anch("Creating a page link list")}} のガイドラインを参照してください。</li> + <li>ページ最下部の "ブラウザの互換性" は<strong>任意</strong>です。</li> +</ol> + +<h4 id="ページリンクリストの作成">ページリンクリストの作成</h4> + +<p>MDN ランディングページのリンクリストセクションは２段組からなります。下記の HTML コードによって生成されます。</p> + +<pre class="brush: html notranslate"><div class="row topicpage-table"> + <div class="section"> + ... left column contents ... + </div> + <div class="section"> + ... right column contents ... + </div> +</div></pre> + +<p>左の段は記事のリストになります。<code>上部の <h2></code> ヘッダはとあるトピック（例えば、"Documentation and tutorials about foo"）についての記事のリストであることを説明します。つまり、このヘッダは CSS の "Documentation" クラスを使用するべきです。その下には、記事の <code><dl></code> リストが続きます。リストには各記事へリンクした <code><dt></code> ブロックと、1行から2行程度の記事の概要に対応した<code> <dd></code> ブロックがあります。</p> + +<p>右の段は以下のセクションをひとつ以上含む必要があります。順に、</p> + +<dl> + <dt>コミュニティの協力を得る</dt> + <dd>これは Matrix チャットルームと、トピックについて役に立つメーリングリストの情報を提供します。見出しには "Community" クラスを利用するべきです。</dd> + <dt>ツール</dt> + <dd>このMDNセクションに記述された技術を使う時に、ユーザの助けになるツールの一覧です。見出しには "Tools" クラスを利用するべきです。</dd> + <dt>関係するトピック</dt> + <dd>その他の、関係する技術についてのランディングページへのリンクリストです。見出しには "Related_Topics" クラスを利用するべきです。</dd> +</dl> + +<p><strong>{{TODO("Finish this once we finalize the landing page standards")}}</strong></p> + +<h2 id="Using_and_inserting_images" name="Using_and_inserting_images">画像の使用と挿入</h2> + +<p>自分で作成した記事や修正した記事の中に画像を入れておくと、特に技術的な内容の記事の場合に便利なことがあります。画像を利用するには、次のようにします。</p> + +<ol> + <li>画像をアップロードする前に、 <a href="https://imageoptim.com/mac">ImageOptim</a> (macOS)、 <a href="https://tinypng.com/">TinyPNG</a> (ウェブサービス)、 <a href="https://trimage.org/">Trimage</a> (Linux) などの画像最適化ツールを使って、できるだけ小さくしてください。</li> + <li>適切な画像ファイルを記事に添付しましょう (編集モードで記事の最下部にてできます)。</li> + <li>WYSIWYG エディターで画像を作成します。</li> + <li>WYSIWIG エディターの添付ファイルのドロップダウンリストから、新規作成した、がウの添付ファイルを選択します。</li> + <li>OK を押してください。</li> +</ol> + +<div class="warning"> +<p><strong>重要:</strong> 記事に添付ファイルをアップロードする前に、変更した内容を保存することを忘れないでください。アップロード処理中はエディターが閉じられており、現在のところ、アップロード時に画像を保存するかどうかは<em>確認されません</em>。</p> +</div> + +<h2 id="Other_references" name="Other_references">その他のリファレンス</h2> + +<h3 id="Preferred_style_guides" name="Preferred_style_guides">おすすめのスタイルガイド</h3> + +<p>ここで取り扱われていない用法とスタイルについて疑問があれば、 <a href="https://docs.microsoft.com/en-us/style-guide/welcome/">Microsoft Writing Style Guide</a> を、それでもダメなら <a href="https://www.amazon.com/Chicago-Manual-Style-16th/dp/0226104206">Chicago Manual of Style</a> を参照してください。 <a href="https://faculty.cascadia.edu/cma/HIST148/cmscrib.pdf">非公式の crib sheet for the Chicago Manual of Style</a> がオンラインで利用できます。</p> + +<h3 id="Preferred_dictionary" name="Preferred_dictionary">おすすめの辞書</h3> + +<p>単語の綴りでわからないことがあれば、 <a href="http://www.dictionary.com/">Dictionary.com</a> を参照してください。このサイトのスペルチェッカはアメリカ英語を基準にしています。それ以外の表記を使用しないでください (例えば <em>colour</em> でなく <em>color</em> です)。</p> + +<p>何度もガイドが拡張されることになるでしょう、ですからこのドキュメントで取り扱われていないことについて知りたければ、その質問を <a href="https://discourse.mozilla.org/c/mdn">MDN discussion forum</a> に投稿してください。MDNの協力者が追加すべき記事を知ることができます。</p> + +<h3 id="MDC-specific" name="MDC-specific">MDN 固有の内容について</h3> + +<ul> + <li>MDN の<a href="/ja/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros" title="Project:en/Custom_Templates">MDN Commonly-used macros</a> に説明があります。</li> +</ul> + +<h3 id="Language_grammar_spelling" name="Language_grammar_spelling">言語、文法、綴り</h3> + +<p>記事の執筆と編集スキルを磨きたければ、以下のリソースが役立つことでしょう。(英語の情報)</p> + +<ul> + <li><a href="http://www.amazon.com/Writing-Well-30th-Anniversary-Nonfiction/dp/0060891548">On Writing Well</a>, by William Zinsser (Amazon link)</li> + <li><a href="http://www.amazon.com/Style-Basics-Clarity-Grace-4th/dp/0205830765/" title="http://www.amazon.com/Style-Lessons-Clarity-Grace-Edition/dp/0321898680">Style: The Basics of Clarity and Grace</a>, by Joseph Williams and Gregory Colomb (Amazon link)</li> + <li><a href="https://brians.wsu.edu/common-errors-in-english-usage/">Common Errors in English</a></li> + <li><a href="http://www-personal.umich.edu/~jlawler/aue.html">English Grammar FAQ</a> (alt.usage.english)</li> + <li><a href="http://www.angryflower.com/bobsqu.gif">Bob's quick guide to the apostrophe, you idiots</a> (funny)</li> + <li><a href="http://www.amazon.com/Merriam-Websters-Concise-Dictionary-English-Usage/dp/B004L2KNI2" title="http://www.amazon.com/Merriam-Websters-Concise-Dictionary-English-Usage/dp/B004L2KNI2">Merriam-Webster's Concise Dictionary of English Usage</a> (Amazon link): Scholarly but user-friendly, evidence-based advice; very good for non-native speakers, especially for preposition usage.</li> + <li><a href="http://english.stackexchange.com/">English Language and Usage StackExchange</a>: Question and answer site for English language usage.</li> +</ul> diff --git a/files/ja/mdn/index.html b/files/ja/mdn/index.html new file mode 100644 index 0000000000..1a5a31291c --- /dev/null +++ b/files/ja/mdn/index.html @@ -0,0 +1,19 @@ +--- +title: MDN プロジェクト +slug: MDN +tags: + - Landing + - MDN Meta +translation_of: MDN +--- +<div>{{MDNSidebar}}</div> + +<p><strong>MDN Web Docs</strong> は、オープンウェブプラットフォームを文書化した無料のリソースです。私たちの使命は、<em>開発者</em>が<em>ウェブプラットフォーム</em>上でプロジェクトを<em>簡単</em>に構築するために必要な<em>情報</em>を提供することです。</p> + +<p>ここは MDN プロジェクトのランディングページです。ここでは、サイトがどのように動作するか、どのようにドキュメントを作成するか、どのようなガイドラインや規約を遵守するか、そしてどのようにして協力できるかについてのガイドを見ることができます。</p> + +<p>そして、私たちは誰でも助けを求めています。この重要なウェブ開発者のリソースを改善することに興味があるなら、コンテンツを追加したり編集したりするのを歓迎します。プログラマーである必要はありませんし、技術に詳しくなくても構いません。単純な作業 (校正やタイプミスの修正) から複雑な作業 (API ドキュメントの作成) まで、実行する必要のあるさまざまな作業があります。</p> + +<p>協力する方法を知りたい場合は、 <a href="/ja/docs/MDN/Contribute">MDN への協力</a>のページをご覧ください。私たちと話したり質問したりしたい場合は、 <a href="https://wiki.mozilla.org/Matrix">Matrix</a> の <a href="https://chat.mozilla.org/#/room/#mdn:mozilla.org">MDN Web Docs チャットルーム</a>で議論に参加してください。</p> + +<p>{{LandingPageListSubPages()}}</p> diff --git a/files/ja/mdn/kuma/index.html b/files/ja/mdn/kuma/index.html new file mode 100644 index 0000000000..af90402f86 --- /dev/null +++ b/files/ja/mdn/kuma/index.html @@ -0,0 +1,25 @@ +--- +title: 'Kuma: MDN の wiki プラットフォーム' +slug: MDN/Kuma +tags: + - Kuma + - Landing + - MDN + - MDN Meta +translation_of: MDN/Kuma +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p class="summary">Kuma は MDN Web Docs を強力にする Django コードです。</p> + +<p>{{SubpagesWithSummaries}}</p> + +<h2 id="Get_involved_with_Kuma" name="Get_involved_with_Kuma">Kuma に参加する</h2> + +<p>Kuma に参加するには:</p> + +<ul> + <li><a href="https://github.com/mozilla/kuma">GitHub の Kuma プロジェクト</a>を訪ねる。</li> + <li><a href="https://github.com/mozilla/kuma/blob/master/CONTRIBUTING.md">Contribution Guide</a> をチェックアウトする。</li> + <li>必要ならば、 <a href="http://kuma.readthedocs.org/en/latest/">Kuma の全ての文書</a>に飛び込んでみる。</li> +</ul> diff --git a/files/ja/mdn/kuma/server_charts/index.html b/files/ja/mdn/kuma/server_charts/index.html new file mode 100644 index 0000000000..d8664c5fa9 --- /dev/null +++ b/files/ja/mdn/kuma/server_charts/index.html @@ -0,0 +1,63 @@ +--- +title: サーバーチャート +slug: MDN/Kuma/Server_charts +tags: + - Kuma + - MDN Meta +translation_of: MDN/Kuma/Server_charts +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p class="summary"><span class="seoSummary">このページには MDN サーバのステータスチャートが一覧表示されます。</span></p> + +<h2 id="Last_30_minutes" name="Last_30_minutes">直近の 30 分</h2> + +<h3 id="Error_Rate" name="Error_Rate">エラーレート</h3> + +<p>{{EmbedNewRelicChart("2fKQPvMkSwU", 300)}}</p> + +<p>Kuma Web アプリのレスポンス時間 (平均)</p> + +<p>{{EmbedNewRelicChart("43yJ3xwUecU", 300)}}</p> + +<h3 id="Kuma_web_app_response_time_Percentiles" name="Kuma_web_app_response_time_Percentiles">Kuma Web アプリのレスポンス時間 (パーセンタイル)</h3> + +<p>{{EmbedNewRelicChart("6NzEi7ZBdoN", 300)}}</p> + +<h2 id="Last_24_Hours" name="Last_24_Hours">直近の 24 時間</h2> + +<h3 id="Error_Rate_2" name="Error_Rate_2">エラーレート</h3> + +<p>{{EmbedNewRelicChart("kVeeXx52g0l", 300)}}</p> + +<h3 id="Kuma_web_app_response_time_Average" name="Kuma_web_app_response_time_Average">Kuma Web アプリのレスポンス時間 (平均)</h3> + +<p>{{EmbedNewRelicChart("2yWkQ9WbEZW", 300)}}</p> + +<h3 id="Kuma_web_app_response_time_Percentiles_2" name="Kuma_web_app_response_time_Percentiles_2">Kuma Web アプリのレスポンス時間 (パーセンタイル)</h3> + +<p>{{EmbedNewRelicChart("aeFnbLonmvx", 300)}}</p> + +<h2 id="Last_3_Days" name="Last_3_Days">直近の 3 日間</h2> + +<h3 id="Error_Rate_3" name="Error_Rate_3">エラーレート</h3> + +<p>{{ EmbedNewRelicChart("iv2F4gQYjFX", 300)}}</p> + +<h3 id="Kuma_web_app_response_time_Average_2" name="Kuma_web_app_response_time_Average_2">Kuma Web アプリのレスポンス時間 (平均)</h3> + +<p>{{EmbedNewRelicChart("ddTq7AKgyaG", 300)}}</p> + +<h3 id="Kuma_web_app_response_time_Percentiles_3" name="Kuma_web_app_response_time_Percentiles_3">Kuma Web アプリのレスポンス時間 (パーセンタイル)</h3> + +<p>{{EmbedNewRelicChart("bRmyM6ujKA8", 300)}}</p> + +<h2 id="Last_3_Months" name="Last_3_Months">直近の 3 ヶ月</h2> + +<h3 id="Error_Rate_4" name="Error_Rate_4">エラーレート</h3> + +<p>{{EmbedNewRelicChart("fjJ7HnGYNLd", 300)}}</p> + +<h3 id="Kuma_web_app_response_time_Average_3" name="Kuma_web_app_response_time_Average_3">Kuma Web アプリのレスポンス時間 (平均)</h3> + +<p>{{EmbedNewRelicChart("sIaVOeAxNx", 300)}}</p> diff --git a/files/ja/mdn/kuma/コントリビュート/index.html b/files/ja/mdn/kuma/コントリビュート/index.html new file mode 100644 index 0000000000..da2ece7d4f --- /dev/null +++ b/files/ja/mdn/kuma/コントリビュート/index.html @@ -0,0 +1,52 @@ +--- +title: Kuma プロジェクトに貢献する +slug: MDN/Kuma/コントリビュート +tags: + - Kuma + - MDN +translation_of: MDN/Kuma +--- +<div>{{MDNSidebar}}</div> + +<p>Kuma プロジェクトに貢献して我々の優れた Wiki プラットフォームの構築を助け、Mozilla Developer Network サイトを改善したいのであれば、以下のドキュメントがプロジェクトに参加して活動する助けになるでしょう。</p> + +<div class="row topicpage-table"> +<div class="section"> +<h2 class="Documentation" id="Documentation" name="Documentation">Kuma への貢献</h2> + +<dl> + <dt><a href="/ja/docs/Project:MDN/Kuma/Contributing/Getting_started" title="/en-US/docs/Project:About">Kuma をはじめる</a></dt> + <dd>Kuma を GitHub からフォークして開発環境を構築する方法。</dd> + <dt><a href="/ja/docs/Project:MDN/Kuma/Contributing/Help_wanted" title="/docs/Project:MDN/Kuma/Contributing/Help_wanted">望んでいる手助け</a></dt> + <dd>我々は Kuma のバグをたくさん報告しています。この記事のリストは我々が心から助けに貢献してほしいと思うものです。</dd> +</dl> + +<h2 class="Tools" id="Tools" name="Tools">ツールとタスク</h2> + +<dl> + <dt><a href="https://bugzilla.mozilla.org/buglist.cgi?cmdtype=dorem&remaction=run&namedcmd=mdn-backlog&sharer_id=416309&list_id=6206936" title="https://bugzilla.mozilla.org/buglist.cgi?cmdtype=dorem&remaction=run&namedcmd=mdn-backlog&sharer_id=416309&list_id=6206936">バグ</a></dt> + <dd>Kuma のバグのリストです。気兼ねなく見渡してあなたが修正できるものを見つけてください。<em>このリンクは Bugzilla へのログインが必要です。</em></dd> + <dt><a href="https://bugzilla.mozilla.org/form.mdn" title="https://bugzilla.mozilla.org/enter_bug.cgi?product=Mozilla%20Developer%20Network">バグを報告する</a></dt> + <dd>Kuma の問題に遭遇したときや改善するためのアイデアを思いついたときは、バグ報告してください。</dd> + <dt><a href="/en-US/docs/Project:MDN/Kuma/Changelog" title="/en-US/docs/Project:MDN/Kuma/Changelog">変更ログ</a></dt> + <dd>最近反映された変更のリストです。これは最近何がおこっているかを見つけるのに最高の場所です。</dd> +</dl> + + +</div> + +<div class="section"> +<h2 class="Community" id="Community" name="Community">MDN 開発者コミュニティ</h2> + +<p>開発者と話をしたい場合や、Kuma プラットフォームのビルドや改善を助けたい場合は、開発者コミュニティに参加してください。</p> + +<ul> + <li>Join the conversation on IRC: <a href="irc://irc.mozilla.org/mdndev" title="irc://irc.mozilla.org/mdndev">#mdndev</a></li> + <li>Read the MDN developer forum: {{DiscussionList("dev-mdn", "mozilla.dev.mdn")}}</li> +</ul> + +<p><span class="alllinks"><a class="external" href="http://www.catb.org/~esr/faqs/smart-questions.html" title="http://www.catb.org/~esr/faqs/smart-questions.html">Don't forget about the <em>netiquette</em>...</a></span></p> +</div> +</div> + +<p><span class="alllinks"><a href="/docs/tag/MDC_Project" title="MDN project pages">すべて見る...</a></span></p> diff --git a/files/ja/mdn/mdn_product_advisory_board/index.html b/files/ja/mdn/mdn_product_advisory_board/index.html new file mode 100644 index 0000000000..c83c16adf5 --- /dev/null +++ b/files/ja/mdn/mdn_product_advisory_board/index.html @@ -0,0 +1,25 @@ +--- +title: MDN プロダクトアドバイザリーボード +slug: MDN/MDN_Product_Advisory_Board +tags: + - MDN + - PAB + - プロダクトアドバイザリーボード +translation_of: MDN/MDN_Product_Advisory_Board +--- +<p>{{MDNSidebar}}</p> + +<p>MDN Web Docs は、Wiki 技術に基づいたオープンソースのウェブ開発ドキュメントプラットフォーム上に構築されたウェブ開発者向けの技術ドキュメントの信頼できるソースです。これにより、ほぼ誰でもコンテンツを作成および編集できます。</p> + +<p>MDN プロダクトアドバイザリーボードのの使命は、 Mozilla、そのドキュメントチーム、そして MDN コミュニティが、最新のブラウザーやウェブ標準の最も重要な側面を網羅した最も包括的で完全な信頼できるリファレンスとして MDN を維持するための主要な協力組織との間の協力関係を構築することにあります。</p> + +<p>プロダクトアドバイザリーボードは外部リーダーからのアドバイスを提供し、MDN がその使命の中で HTML、CSS、JavaScript、および Web API の公平でブラウザーにとらわれないドキュメントを提供し、標準ベースのウェブ開発のトップリファレンスになるのを支援します。</p> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li><a href="https://github.com/mdn/pab">Product Advisory Board meeting minutes</a> (GitHub)</li> + <li><a href="/ja/docs/MDN/MDN_Product_Advisory_Board/Membership">Product Advisory Board Charter & Membership</a></li> + <li><a href="/ja/docs/MDN/MDN_Product_Advisory_Board/Members">Product Advisory Board members</a></li> + <li><a href="https://www.surveygizmo.com/s3/4024118/MDN-Advisory-Board-Application">Membership application</a></li> +</ul> diff --git a/files/ja/mdn/mdn_product_advisory_board/members/index.html b/files/ja/mdn/mdn_product_advisory_board/members/index.html new file mode 100644 index 0000000000..65d5ddbbf8 --- /dev/null +++ b/files/ja/mdn/mdn_product_advisory_board/members/index.html @@ -0,0 +1,88 @@ +--- +title: プロダクトアドバイザリーボード +slug: MDN/MDN_Product_Advisory_Board/Members +tags: + - MDN + - PAB + - プロダクトアドバイザリーボード + - メンバー +translation_of: MDN/MDN_Product_Advisory_Board/Members +--- +<div>{{MDNSidebar}}</div> + +<p>MDN プロダクトアドバイザリーボードの現在のメンバーは以下のとおりです。</p> + +<p><strong>Daniel Appelquist</strong><br> + Samsung Internet の Developer Advocacy ディレクター、W3C の Technical Architecture Group の共同議長</p> + +<dl> + <dd>Daniel Appelquist は、Samsung のモバイルおよび VR Web ブラウザである Samsung Internet <<a href="https://samsunginter.net">https://samsunginter.net</a>> の Web Developer Advocacy チームを率いています。2013年から <a href="https://www.w3.org/2001/tag/">W3C の Technical Architecture Group</a> の共同議長も務めています。彼は20年以上にわたって Web に取り組んできました。最初は Web 出版の分野で新興企業を創設し、その後 (99年にニューヨークからロンドンに引っ越した後)、さまざまなプロジェクトとイニシアチブを通じて Web とモバイルの融合に取り組んできました。また彼は、英国政府のオープンスタンダード戦略を指揮し、<a href="https://www.gov.uk/government/groups/open-standards-board">英国政府オープンスタンダード委員会</a>のメンバーであり続けています。この間、彼は活発なコミュニティビルダーおよびイベントオーガナイザーを務めています。</dd> +</dl> + +<p><strong>Jory Burson</strong><br> + COO, Bocoup</p> + +<dl> + <dd>Jory は、いくつかの業界委員会および Bocoup の標準設定団体のメンバーとして、オープンソースおよびオープンスタンダードのコミュニティにおけるコラボレーションの向上に取り組んでいます。彼女は Ecma International の Executive Committee、JS Foundation Technical Architecture Committee、W3C Advisory Council、MDN Board のメンバーであり、Ecma TC39、Ecma TC53、および Web Platform Tests のプロジェクトに取り組んでいます。暇な時に、Jory は標準の歴史と Web プラットフォームの社会的構築について研究し、書いて、話します。</dd> +</dl> + +<p><strong>Dominique Hazael-Massieux</strong><br> + W3C ウェブ技術エキスパート、<a href="https://www.w3.org/Telco/">電気通信分野のバーティカルチャンピオン</a>、<a href="https://www.w3.org/2011/04/webrtc/">Web リアルタイムコミュニケーションワーキンググループ</a>、<a href="https://www.w3.org/das/">デバイスおよびセンサーワーキンググループ</a>。</p> + +<dl> + <dd>Dominique Hazael-Massieux は W3C スタッフの一員で、開発者との関係における W3C の取り組みを率いています。Dom は2000年から W3C に取り組んでいて、devrel に加えて、現在 WebRTC、デバイス API、および WebVR の標準化に携わっています。</dd> +</dl> + +<p><strong>Joe Medley</strong><br> + Google のシニアテクニカルライター、 Web Developer Relations</p> + +<dl> + <dd>Joe は、過去5年間ウェブプラットフォームのリファレンス文書を作成する Google の取り組みを主導してきました。つまり、 MDN に多くを費やしています。ウェブ開発者を対象とした Chrome ベータリリースの発表の編集に加えて、彼は web.dev 向けの不定期の記事を執筆しています。 Joe は、中央ミズーリ大学でエンタープライズアプリケーションおよび教育学の学位を取得した開発者向けリファレンス文書を長年執筆してきた後、 Web Developer Relations に参加しました。</dd> +</dl> + +<p><strong>Chris Mills</strong><br> + Mozilla の MDN Web ドキュメントのコンテンツリーダーおよびライターチームマネージャ。</p> + +<dl> + <dd>Chris は、 MDN のコンテンツリーダーとして Mozilla に勤務しており、短期および長期の文書化が必要な場合の戦略をまとめるのに役立ちます。彼はまた、DOM API、HTML と CSS の機能、Web ゲーム、 WebAssembly などをカバーする多数の初心者向けチュートリアルと参考記事を寄稿しています。彼はまた MDN ライターチームを管理します。</dd> +</dl> + +<p><strong>Robert Nyman</strong><br> + Google のプログラムとイニシアチブ、Web Developer Relations のグローバルリード。</p> + +<dl> + <dd>Robert Nyman は、Google の Web Platform、開発者フィードバック＆コミュニティのグローバルリーダーです。彼の役割では、Web を開発者にとって最高のプラットフォームにするために働いています。Google に入社する前、Robert は Mozilla の技術的な伝道者でした。Open Web と同社のさまざまな製品や取り組みに焦点を当てていました。彼はストックホルムに住んでおり、旅行や人々との出会いに情熱を注いでいます。彼は42カ国で発表したLanyrdの「最もよく旅されたスピーカー」の称号を主張します。</dd> +</dl> + +<p><strong>Kyle Pflug</strong><br> + シニアプログラムマネージャー、 Microsoft Edge Developer Experiences</p> + +<dl> + <dd>Kyle Pflug は、マイクロソフトのプログラムマネージャーであり、 Microsoft Edge の開発者の関係構築とコミュニティアウトリーチをリードしています。過去5年間、彼はマイクロソフト内でウェブ開発者とパートナーの視点を擁護するために働いてきました。プラットフォームやデバイスを問わず、開発者がウェブをより包括的でアクセスしやすくすることに情熱を傾けています。</dd> +</dl> + +<p><strong>Ali Spivak</strong><br> + Mozilla の開発者エコシステム責任者、ブロダクトアドバイザリーボードチェア。</p> + +<dl> + <dd>Ali は Mozilla の開発者エコシステムの責任者で、以前は Mozilla の開発者マーケティングを担当していました。彼女は5年以上 MDN を管理しており、相互運用可能なクロスプラットフォームの Web に取り組んでいます。Mozilla 以前は、Cisco、Edmunds.com、および多数のスタートアップで Web 制作を管理していました。</dd> +</dl> + +<p><strong>Kadir Topal</strong><br> + Mozilla の MDN Web Docs プロダクトマネージャ。</p> + +<p><strong>MDN Product Advisory Board Alumni:</strong></p> + +<p>Meggin Kearney, Google<br> + Erika Doyle Navara, Microsoft<br> + Patrick Kettner, Microsoft<br> + Travis Leithead, Microsoft</p> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li><a href="/ja/docs/MDN/MDN_Product_Advisory_Board">プロダクトアドバイザリボードホーム</a></li> + <li><a href="https://github.com/mdn/pab">Product Advisory Board meeting minutes</a> (GitHub)</li> + <li><a href="/ja/docs/MDN/MDN_Product_Advisory_Board/Membership">Product Advisory Board Charter & Membership</a></li> + <li><a href="https://www.surveygizmo.com/s3/4024118/MDN-Advisory-Board-Application">Membership application</a></li> +</ul> diff --git a/files/ja/mdn/structures/api_references/api_reference_sidebars/index.html b/files/ja/mdn/structures/api_references/api_reference_sidebars/index.html new file mode 100644 index 0000000000..6695ab0969 --- /dev/null +++ b/files/ja/mdn/structures/api_references/api_reference_sidebars/index.html @@ -0,0 +1,132 @@ +--- +title: API リファレンスサイドバー +slug: MDN/Structures/API_references/API_reference_sidebars +tags: + - API + - Documentation + - Guide + - MDN + - MDN Meta + - Reference + - groupdata + - metadata + - onboarding + - sidebars +translation_of: MDN/Structures/API_references/API_reference_sidebars +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">API リファレンスページにカスタムサイドバーを追加して、関連するインターフェイス、チュートリアル、およびその API に関連する他のリソースへのリンクを表示することができます。この記事ではその方法を説明します。</p> + +<h2 id="Creating_a_sidebar" name="Creating_a_sidebar">サイドバーの作成</h2> + +<p>API サイドバーを作成するには、次の3つの手順を実行する必要があります。</p> + +<ol> + <li>API リファレンスページを作成します</li> + <li>特定の API の項目を <a href="https://github.com/mdn/kumascript">KumaScript リポジトリ</a>の <code>GroupData.json</code> データファイルに追加します</li> + <li>{{TemplateLink("APIRef")}} マクロを使用して、表示したい各ページにサイドバーを挿入します</li> +</ol> + +<p>これらのステップを順番に実行しましょう。この記事で参照する例は、<a href="/ja/docs/Web/API/Fetch_API">Fetch API</a> です。</p> + +<h3 id="Creating_your_API_reference_pages" name="Creating_your_API_reference_pages">API リファレンスページの作成</h3> + +<p>サイドバーをページに追加する前に、ページ自体を作成する必要があります (詳細については、<a href="/ja/docs/MDN/Contribute/Structures/API_references/What_does_an_API_reference_need">API リファレンスに必要なもの</a>ガイドを参照してください)。</p> + +<h3 id="Adding_an_entry_to_GroupData.json" name="Adding_an_entry_to_GroupData.json">GroupData.json への項目の追加</h3> + +<p><code><a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData.json</a></code> ファイルには、API 参照サイドバーに表示されるリンクに関するすべてのデータが格納されます。呼び出されると、{{TemplateLink("APIRef")}} マクロは引数として与えられた API 名を取り、<code>GroupData.json</code> でその名前を検索し、適切なサイドバーを作成してページに挿入します。</p> + +<p><code>GroupData.json</code> に項目を追加するには、以下を行う必要があります。</p> + +<ol> + <li><a href="https://github.com/">GitHub</a> アカウントを持っていることを確認します</li> + <li>KumaScript リポジトリをフォークし、新しいブランチを作成して変更を保存し、リポジトリをローカルにクローンします</li> + <li>作業を開始する前に新しいブランチをチェックアウトし、作業が終わったら変更を押してください</li> + <li>プルリクエストを作成して、MDN チームがあなたの作業をレビューし、必要に応じて変更を求めることができるようにします</li> +</ol> + +<p>GitHub の使用についてサポートが必要な場合は、<a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables#The_new_way_The_browser_compat_data_repo_and_dynamic_tables">互換性一覧表</a>に詳細なガイドがあります。</p> + +<p><code><a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData.json</a></code> ファイルは、KumaScript リポジトリの macros ディレクトリ内にあります。それを見ると、巨大な JSON 構造があり、それぞれの API に独自のメンバーがあります。名前は API 名で、値は生成するサイドバーリンクを定義するいくつかのサブメンバーを含むオブジェクトです。</p> + +<p>たとえば、MDN の <a href="/ja/docs/Web/API/Fetch_API">Fetch API</a> ページを見てください。 <code>GroupData.json</code> の対応する項目は次のようになります。</p> + +<pre class="brush: json notranslate">"Fetch API": { + "overview": [ "Fetch API"], + "interfaces": [ "Body", + "Headers", + "Request", + "Response", + "FetchController", + "FetchObserver", + "FetchSignal", + "ObserverCallback" ], + "methods": [ "WindowOrWorkerGlobalScope.fetch()" ], + "properties": [], + "events": [] +},</pre> + +<p>ご覧のとおり、名前には "Fetch API" を使用し、オブジェクト値の内側には多数のサブメンバーが含まれています。</p> + +<h4 id="Sub-members_to_include_inside_a_GroupData_entry" name="Sub-members_to_include_inside_a_GroupData_entry">GroupData 項目内に含めるサブメンバー</h4> + +<p>この節では、<code>GroupData</code> 項目に含めることができるすべてのサブメンバーを一覧表示します。</p> + +<p>リストされたサブメンバーの中に含まれる値のほとんどは、リンクテキストと、表示されるリンクの最終的な URL を生成するためのメイン API インデックスページ — <code>https://developer.mozilla.org/<em><language-code></em>/docs/Web/API</code> — の最後に追加されたスラッグの両方に相当することに注意してください。そのため、例えば "Body" とすると、 <em>en-US</em> ロケールではこのようなリンクが生成されます。</p> + +<pre class="brush: html notranslate"><li><a href="https://developer.mozilla.org/en-US/docs/Web/API">Body</a></li></pre> + +<p>いくつかの例外があります。例えば "guides" サブメンバーには、関連するガイド/チュートリアルへのリンクを定義するリンク情報 (タイトルとスラッグ) が1つ以上含まれています。この場合、スラッグは MDN の docs ルート — https://developer.mozilla.org/<em><language-code></em>/docs — の最後に追加され、MDN のどこにでも記事を含めることができます。</p> + +<p>以下が利用可能なメンバーです。それぞれの場合、ロケールが <em>en-US</em> であると仮定した例が含まれています。これらはすべて技術的にはオプションですが、これらを省略する代わりに空の配列を含めることを強く推奨します。</p> + +<ol> + <li> + <p><code>"overview"</code> — 値は配列で、 API 概要ページがあればその中にスラッグを含めます。"Fetch API" の場合、 <a href="/en-US/docs/Web/API/Fetch_API">https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API</a> へのリンクが生成されます。</p> + </li> + <li> + <p><code>"interfaces"</code> — 値は配列で、その API の一部を構成するすべてのインターフェイスをリストアップする必要があります。 "Body" の場合は <a href="/en-US/docs/Web/API/Body">https://developer.mozilla.org/en-US/docs/Web/API/Body</a> へのリンクが生成されます。</p> + </li> + <li> + <p><code>"methods"</code> — 値は、 {{domxref("Navigator")}} や {{domxref("Window")}} で生成されたインスタンス化メソッドなど、仕様が他の API に関連付けられたインターフェイスに追加するメソッドを含む配列です。膨大な数のメソッドがある場合は、最も人気のあるものだけをリストアップするか、リストの先頭に置くことを検討するとよいでしょう。 "WindowOrWorkerGlobalScope.fetch()" を実行すると <a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch">https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch</a> へのリンクが張られます。同じ API が所有するインターフェイスのメンバーであるメソッドを重複してリストアップしないようにしましょう。</p> + </li> + <li> + <p><code>"properties"</code> — 値は、 API に関連付けられたすべてのプロパティを含む配列です。これには API 仕様で定義されているインターフェイスのメンバーであるプロパティや、API が他のインターフェイス上で定義しているプロパティを含めることができます。膨大な数のプロパティがある場合は、最も人気のあるものだけをリストアップするか、リストの先頭に配置することを検討するとよいでしょう。 "Headers.append" を実行すると、 <a href="/en-US/docs/Web/API/Headers/append">https://developer.mozilla.org/en-US/docs/Web/API/Headers/append</a> へのリンクが生成されます。</p> + </li> + <li> + <p><code>"events"</code> — 値は、 API の仕様やその他の場所で定義されている API に関連するすべてのイベントを含む配列です。膨大な数のイベントがある場合は、最も人気のあるものだけをリストアップするか、リストの先頭に置くことを検討するとよいでしょう。 "animationstart" を実行すると、 <a href="/en-US/docs/Web/Events/animationstart">https://developer.mozilla.org/en-US/docs/Web/Events/animationstart</a> へのリンクが生成されます。</p> + </li> + <li> + <p><code>"guides"</code> — 値は、API の使用方法を説明するガイドへのリンクを定義する1つ以上のオブジェクトを含む配列です。各オブジェクトは、ガイド記事を指す部分的な URL を含む "url" と、リンクのリンクテストを定義する "title" の2つのサブメンバーを含みます。例として、次のようなオブジェクトがあります。</p> + + <pre class="brush: json notranslate">{ "url": "/docs/Web/API/Detecting_device_orientation", +"title": "Detecting device orientation" }</pre> + + <p>"Detecting device orientation" というタイトルのリンクを生成し、 <a href="/en-US/docs/Web/API/Detecting_device_orientation">https://developer.mozilla.org/en-US/docs/Web/API/Detecting_device_orientation</a> を指します。</p> + </li> + <li> + <p><code>"dictionaries"</code> — API の一部であるすべての辞書を一覧にした文字列の配列。一般的に、特別な意味がある場合や、複数のページから参照する必要がある場合を除き、複数のプロパティやメソッドで使用される辞書のみをここにリストアップすべきです。 "RTCConfiguration" の場合は <a href="https://developer.mozilla.org/en-US/docs/Web/API/RTCConfiguration">https://developer.mozilla.org/en-US/docs/Web/API/RTCConfiguration</a> へのリンクを表示します。</p> + </li> + <li> + <p><code>"types"</code> — API で定義されている型定義子と列挙型の配列。リストを短くするために、特別に重要なものや複数のページから参照されるものだけをリストアップすることもできます。 "RTCCodecType" は <a href="https://developer.mozilla.org/en-US/docs/Web/API/RTCCodecType">https://developer.mozilla.org/en-US/docs/Web/API/RTCCodecType</a> へのリンクを生成します。</p> + </li> + <li> + <p><code>"callbacks"</code> — 値は、その API で定義されているすべてのコールバック型のリストを含む配列です。コールバック型を含む API であっても、このグループを使用する必要はないと思われるかもしれません。文字列 "RTCSessionDescriptionCallback" を含むこの配列の項目は、 <a href="https://developer.mozilla.org/en-US/docs/Web/API/RTCSessionDescriptionCallback">https://developer.mozilla.org/en-US/docs/Web/API/RTCSessionDescriptionCallback</a> へのリンクが生成されます。</p> + </li> +</ol> + +<h2 id="Tags_used_by_sidebars" name="Tags_used_by_sidebars">サイドバーで使用されるタグ</h2> + +<p>サブメンバーによっては、ページタグに基づいて子ページから自動的に発見されるものがあります。最上位 API 以下のページはサイドバーがレンダリングされるたびにクロールされ、メソッド ("Method" タグ)、プロパティ ("Property" タグ)、コンストラクター ("Constructor"タグ) の項目が自動的に生成されます。</p> + +<p>サブメンバーにも、タグに基づいた警告アイコンが自動的に表示されます。実験的な ("Experimental" タグ)、標準外 ("Non Standard" または "Non-standard" タグ)、非推奨 ("Deprecated" タグ)、廃止 ("Obsolete" タグ) サブメンバーには装飾が追加されます。</p> + +<p>タグベースの処理に関する詳細情報は、 <a href="https://github.com/mdn/kumascript/blob/master/macros/APIRef.ejs">APIRef ソースの中</a>にあります。</p> + +<h2 id="Inserting_the_sidebar" name="Inserting_the_sidebar">サイドバーの挿入</h2> + +<p><code>GroupData.json</code> に API の項目を追加してプルリクエストとして送信し、その変更がメインリポジトリに受け入れられたら、 {{TemplateLink("APIRef")}} マクロを使用して API リファレンスページに設置することができ、 GroupData の API に引数として使用されます。例として、 <a href="/ja/docs/Web/API/WebVR_API">WebVR API</a> のサイドバーは、各ページに次のように設置されています。</p> + +<pre class="notranslate">\{{APIRef("WebVR API")}}</pre> diff --git a/files/ja/mdn/structures/api_references/index.html b/files/ja/mdn/structures/api_references/index.html new file mode 100644 index 0000000000..c1d806b234 --- /dev/null +++ b/files/ja/mdn/structures/api_references/index.html @@ -0,0 +1,58 @@ +--- +title: API リファレンス +slug: MDN/Structures/API_references +tags: + - API + - Contribute + - Guide + - Reference +translation_of: MDN/Structures/API_references +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p class="summary">クライアント側の JavaScript API は、ウェブ上で利用可能な技術の大部分を占めています。MDN には、これらの API で使用できる機能とその使用方法を説明する広範囲な参考資料が含まれています。このガイドセットでは MDN で API リファレンス資料を作成する方法について説明します。</p> + +<h2 id="Prerequisite_resources" name="Prerequisite_resources">事前に準備するリソース</h2> + +<p>API の文書化を開始する前に、次のものが必要です。</p> + +<ol> + <li><strong>最新の仕様:</strong> W3C 勧告か初期の編集者の草稿かどうかに関わらず、その API をカバーする仕様の最新の草稿 (またはその仕様を参照) を参照する必要があります。通常それはウェブ検索で見つかります。最新のバージョンは「最新草稿」、またはそれに類するものの下にリストされている仕様のすべてのバージョンからリンクされることがよくあります。</li> + <li><strong>最新のウェブブラウザー:</strong> <a href="https://nightly.mozilla.org/">Firefox Nightly</a>/<a href="https://www.google.com/intl/en/chrome/browser/canary.html">Chrome Canary</a> のような実験的/アルファ版のものが、あなたが文書化している機能をサポートする可能性が高いはずです。これは初期の/実験的な API を文書化している場合に特に関係します。</li> + <li><strong>デモ/ブログ記事/その他の情報:</strong> できるだけ多くの情報を探しましょう。主なインターフェイス/プロパティ/メソッドが何であるか、主要な用途は何であるか、そしてそれを使って簡単な機能を書く方法を学ぶことで、API の仕組みに慣れるための時間を費やすことから始めておくと便利です。</li> + <li><strong>有益なエンジニアリングの連絡先:</strong> 仕様、API の標準化に携わっている人、またはブラウザでの実装について質問するためのフレンドリーなエンジニアリング担当者を見つけることは本当に便利です。見つけるのに適した場所は次のとおりです。 + <ul> + <li>関連会社に勤めている場合は、社内のアドレス帳。</li> + <li>Mozilla の <a href="https://lists.mozilla.org/listinfo/dev-platform">dev-platform</a> や <a href="https://lists.mozilla.org/listinfo/dev-webapi">dev-webapi</a> のリスト、<a href="https://lists.w3.org/Archives/Public/public-webapps/">public-webapps</a> のような W3C のリストなど、その API の議論に関係する公開メーリングリスト。</li> + <li>仕様そのもの。たとえば、 <a href="https://webaudio.github.io/web-audio-api/">Web Audio API</a> の仕様書では著者とその連絡先の詳細が上部に表示されています。</li> + </ul> + </li> +</ol> + +<h2 id="High_level_structure" name="High_level_structure">高水準の構造</h2> + +<dl> + <dt><a href="/ja/docs/MDN/Contribute/Structures/API_references/What_does_an_API_reference_need">What does an API reference need?</a></dt> + <dd>この記事では完全な API リファレンスに必要なページについて説明します。</dd> + <dt><a href="/ja/docs/MDN/Contribute/Structures/Page_types">Page types</a></dt> + <dd>MDN に繰り返し使用されるいくつかの種類のページがあります。この記事では、これらのページ種別とその目的、および新しいページを作成するときに使用する各テンプレートとテンプレートの例について説明します。</dd> +</dl> + +<h2 id="Individual_page_features" name="Individual_page_features">個々のページの特徴</h2> + +<p>これらの記事では、API リファレンスページに必要な個々のページの特徴を作成する方法について説明します。</p> + +<dl> + <dt><a href="/ja/docs/MDN/Contribute/Structures/API_references/API_reference_sidebars">API リファレンスサイドバー</a></dt> + <dd>MDN API リファレンス記事にサイドバーを含めると、その API に関連する関連インタフェース、チュートリアル、その他のリソースへのリンクが表示されるようにカスタマイズできます。この記事では、この方法について説明します。</dd> + <dt><a href="/ja/docs/MDN/Contribute/Structures/Syntax_sections">構文の節</a></dt> + <dd>MDN リファレンスページの構文の節には、その機能が持つ正確な構文 (例えば、どのような引数を受け付けるか、どの引数がオプションかなど) を定義する構文ボックスが含まれています。</dd> + <dt><a href="/ja/docs/MDN/Contribute/Structures/Code_examples">コード例</a></dt> + <dd>MDN には、ウェブプラットフォーム機能の使用方法を示すために、ページ全体に挿入された多数のコード例があります。この記事ではコードの例をページに追加する際に使用できるさまざまなメカニズムと、使用する必要があるものとそのタイミングについて説明します。</dd> + <dt><a href="/ja/docs/MDN/Contribute/Structures/Specification_tables">仕様書一覧表</a></dt> + <dd>MDN のすべてのリファレンスページは、その API または技術が定義されている仕様または仕様に関する情報を提供する必要があります。この資料では、これらのテーブルの外観とその構成方法について説明します。</dd> + <dt><a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables">互換性一覧表</a></dt> + <dd>MDN には、公開されているウェブ文書の互換性一覧表の標準フォーマットがあります。つまり、すべてのブラウザーで共有されているDOM、HTML、CSS、JavaScript、SVG などの技術の文書です。この記事では、機能を使用して MDN ページに互換性データを追加する方法について説明します。</dd> +</dl> diff --git a/files/ja/mdn/structures/api_references/what_does_an_api_reference_need/index.html b/files/ja/mdn/structures/api_references/what_does_an_api_reference_need/index.html new file mode 100644 index 0000000000..952c49ed70 --- /dev/null +++ b/files/ja/mdn/structures/api_references/what_does_an_api_reference_need/index.html @@ -0,0 +1,168 @@ +--- +title: API リファレンスには何が必要ですか？ +slug: MDN/Structures/API_references/What_does_an_API_reference_need +tags: + - API + - ページ + - リファレンス +translation_of: MDN/Structures/API_references/What_does_an_API_reference_need +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">この記事では、完全な API リファレンスに必要なページについて説明します。</p> + +<div class="note"> +<p><strong>メモ</strong>: API リファレンスで作業しているときに書いたり更新したりする必要があるドキュメントのリストを作成し、完了したらチェックを外すことをお勧めします。</p> +</div> + +<h2 id="API_ページの概要">API ページの概要</h2> + +<p>An API reference will generally contain the following pages. You can find more details of what each page contains, examples, and templates, in our <a href="/en-US/docs/MDN/Contribute/Structures/Page_types">Page types</a> article.</p> + +<ol> + <li>Overview page</li> + <li>Interface pages</li> + <li>Constructor pages</li> + <li>Method pages</li> + <li>Property pages (including event handlers properties)</li> + <li>Event pages</li> + <li>Concept/guide pages</li> + <li>Examples</li> +</ol> + +<div class="note"> +<p><strong>Note</strong>: We'll be referring to the <a href="/en-US/docs/Web/API/Web_Audio_API">Web Audio API</a> for examples in this article.</p> +</div> + +<div class="note"> +<p><strong>Note</strong>: To create a page as specified below, the easiest way is to go to the parent page you want it to hang off, and choose <em>Cog icon > New sub-article</em>. If you haven't got this option available on your MDN interface, you'll need to request this privilege (ask at <code>mdn-admins@mozilla.org</code>), or ask another MDN contributor to create them for you.</p> +</div> + +<h3 id="概要ページ">概要ページ</h3> + +<p>A single API overview page is used to describe the role of the API, its top-level interfaces, related features contained in other interfaces, and other high level details. Its name and slug should be the name of the API plus "API" on the end. It is placed at the top level of the API reference, as a child of <a href="/en-US/docs/Web/API">https://developer.mozilla.org/en-US/docs/Web/API</a>.</p> + +<p>例:</p> + +<ul> + <li>Title: <em>Web Audio API</em></li> + <li>Slug: <em>Web_Audio_API</em></li> + <li>URL: <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API</a></li> +</ul> + +<h3 id="インターフェイスページ">インターフェイスページ</h3> + +<p>Each interface will have its own page too, describing the purpose of the interface, listing any members (constructors, methods, properties, etc. it contains), and showing what browsers it is compatible with. A page's name and slug should be the name of the interface, exactly as written in the spec. Each page is placed at the top level of the API reference, as a child of <a href="/en-US/docs/Web/API">https://developer.mozilla.org/en-US/docs/Web/API</a>.</p> + +<p>例:</p> + +<ul> + <li>Title: <em>AudioContext</em></li> + <li>Slug: <em>AudioContext</em></li> + <li>URL: <a href="https://developer.mozilla.org/en-US/docs/Web/API/AudioContext">https://developer.mozilla.org/en-US/docs/Web/API/AudioContext</a></li> +</ul> + +<ul> + <li>Title: <em>AudioNode</em></li> + <li>Slug: <em>AudioNode</em></li> + <li>URL: <a href="https://developer.mozilla.org/en-US/docs/Web/API/AudioNode">https://developer.mozilla.org/en-US/docs/Web/API/AudioNode</a></li> +</ul> + +<div class="note"> +<p><strong>Note:</strong> We document every member appearing in the interface. You should bear the following rules in mind:</p> + +<ul> + <li>We document methods defined on the <u>prototype</u> of an object implementing this interface (instance methods), and methods defined on the actual class itself (static methods). On the rare occasions that they both exist on the same interface, you should list them in separate sections on the page (Static methods/Instance methods). Usually only instance methods exist, in which case you can put these under the title "Methods".</li> + <li>We do not document inherited properties and methods of the interface: they are listed on the respective parent interface. We do hint at their existence though.</li> + <li>We do document properties and methods defined in mixins, though we use the mixin name as interface name. (This is not optimal as the mixin name will not appear in the console, but it prevents the duplication of documentation. We may revisit this in the future.)</li> + <li>Special methods like the stringfier (<code>toString()</code>) and the jsonizier (<code>toJSON()</code>) are also listed if they do exist.</li> + <li>Named constructors (like <code>Image()</code> for {{domxref("HTMLImageElement")}} ) are also listed, if relevant.</li> +</ul> +</div> + +<h3 id="コンストラクタページ">コンストラクタページ</h3> + +<p>Each interface has 0 or 1 constructors, documented on a subpage of the interface's page. It describes the purpose of the constructor and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug is the name of the constructor, which is exactly the same as the interface name, and the title is interface name, dot, constructor name, then parentheses on the end.</p> + +<p>Example:</p> + +<ul> + <li>Title: <em>AudioContext.AudioContext()</em></li> + <li>Slug: <em>AudioContext</em></li> + <li>URL: <a href="https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/AudioContext">https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/AudioContext</a></li> +</ul> + +<h3 id="プロパティページ">プロパティページ</h3> + +<p>Each interface has zero or more properties, documented on subpages of the interface's page. each page describes the purpose of the property and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug is the name of the property, and the title is interface name, dot, then property name.</p> + +<p>Examples:</p> + +<ul> + <li>Title: <em>AudioContext.state</em></li> + <li>Slug: <em>state</em></li> + <li>URL: <a href="/en-US/docs/Web/API/AudioContext/state">https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/state</a></li> +</ul> + +<ul> + <li>Title: <em>AudioContext.onstatechange</em></li> + <li>Slug: <em>onstatechange</em></li> + <li>URL: <a href="/en-US/docs/Web/API/AudioContext/onstatechange">https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/onstatechange</a></li> +</ul> + +<div class="note"> +<p><strong>Note:</strong> Event handler properties are treated in the same way as regular properties; they are generally listed in a separate section on the interface page though.</p> +</div> + +<ul> +</ul> + +<h3 id="メソッドページ">メソッドページ</h3> + +<p>Each interface has zero or more methods, documented on subpages of the interface's page. each page describes the purpose of the method and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug is the name of the method, and the title is interface name, dot, method name, then parentheses.</p> + +<p>Examples:</p> + +<ul> + <li>Title: <em>AudioContext.close()</em></li> + <li>Slug: <em>close</em></li> + <li>URL: <a href="/en-US/docs/Web/API/AudioContext/close">https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/close</a></li> +</ul> + +<ul> + <li>Title: <em>AudioContext.createGain()</em></li> + <li>Slug: <em>createGain</em></li> + <li>URL: <a href="/en-US/docs/Web/API/AudioContext/createGain">https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/createGain</a></li> +</ul> + +<h3 id="イベントページ">イベントページ</h3> + +<p>Each event handler property you create will have a corresponding event page, describing the event that causes the handler to fire, documented on a subpage of <a href="/en-US/docs/Web/Events">https://developer.mozilla.org/en-US/docs/Web/Events</a>. Each page describes the purpose of the event and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug and title is the name of the event.</p> + +<p>Example:</p> + +<ul> + <li>Title: <em>statechange</em></li> + <li>Slug: <em>statechange</em></li> + <li>URL: <a href="/en-US/docs/Web/Events/statechange">https://developer.mozilla.org/en-US/docs/Web/Events/statechange</a></li> +</ul> + +<h3 id="Conceptguide_pages">Concept/guide pages</h3> + +<p>Most API references have at least one guide and sometimes also a concept page to accompany it. At minimum, an API reference should contain a guide called "Using the <em>name-of-api</em>", which will provide a basic guide to how to use the API. More complex APIs may require multiple usage guides to explain how to use different aspects of the API.</p> + +<p>If required, you can also including a concepts article called "<em>name-of-api</em> concepts", which will provide explanation of the theory behind any concepts related to the API that developers should understand to effectively use it.</p> + +<p>These articles should all be created as subpages of the API overview page. For example, the Web Audio has four guides and a concept article:</p> + +<ul> + <li><a href="/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API</a></li> + <li><a href="/en-US/docs/Web/API/Web_Audio_API/Visualizations_with_Web_Audio_API">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Visualizations_with_Web_Audio_API</a></li> + <li><a href="/en-US/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics</a></li> + <li><a href="/en-US/docs/Web/API/Web_Audio_API/Porting_webkitAudioContext_code_to_standards_based_AudioContext">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Porting_webkitAudioContext_code_to_standards_based_AudioContext</a></li> + <li><a href="/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API</a></li> +</ul> + +<h3 id="例">例</h3> + +<p>You should create some examples that demonstrate at least the most common use cases of the API. You can put these anywhere that is appropriate, although the recommended place is the <a href="https://github.com/mdn/">MDN GitHub repo</a>.</p> diff --git a/files/ja/mdn/structures/banners_and_notices/index.html b/files/ja/mdn/structures/banners_and_notices/index.html new file mode 100644 index 0000000000..54cce6a78f --- /dev/null +++ b/files/ja/mdn/structures/banners_and_notices/index.html @@ -0,0 +1,56 @@ +--- +title: バナーと通知 +slug: MDN/Structures/Banners_and_notices +tags: + - MDN Meta + - ガイド + - 構造 +translation_of: MDN/Structures/Banners_and_notices +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p><span class="seoSummary">場合によっては、記事に特別な通知が必要になることがあります。これは、プロダクションコードで使用すべきではない古い技術やその他の資料がページに含まれている場合に発生する可能性があります。この記事では最も一般的なケースについて説明します。</span></p> + +<h2 id="How_to_add_notice_boxes">How to add notice boxes</h2> + +<p>In most cases, you apply these notices by adding a macro call to inject an appropriate banner into the page content, and by adding a tag to the page's list of tags. Also, if the page includes a compatibility table (most API reference pages do, for example), you should update that table to reflect any compatibility changes.</p> + +<p>To do this, you open the editor, then insert the macro call at the top of the article, and change the browser <a href="/en-US/docs/Project:Compatibility_tables" title="/en-US/docs/Project:Compatibility_tables">compatibility table</a> (if any); the table should be near the end of the article. Once that's done, scroll to the bottom of the article to find the tag list, and add the new tag to the list. Once you've done that, click the Save Changes button near the top of the window to commit your updates. From then on, an appropriate banner will appear on the page, and any macros that reference page tags when looking for up-to-date articles will know that the page you've updated is obsolete.</p> + +<ul> + <li>To learn more about editing, see the <a href="/en-US/docs/Project:MDN/Contributing/Editor_guide" title="/en-US/docs/Project:MDN/Contributing/Editor_guide">MDN editor guide</a>.</li> + <li>For more information about tagging, see our <a href="/en-US/docs/Project:MDN/Contributing/Tagging_standards" title="/en-US/docs/Project:MDN/Contributing/Tagging_standards">Tagging standards</a> guide.</li> + <li>To discover more of our custom macros, see the article <a href="/en-US/docs/Project:MDN/Contributing/Custom_macros" title="/en-US/docs/Project:MDN/Contributing/Custom_macros">Custom macros for MDN</a>.</li> +</ul> + +<p>Sometimes, you might want to flag just a single item in a list of items, or in a table, as obsolete, deprecated, or the like. There are special versions of each of the following macros for that; simply change "_header" to "_inline" to the end of the macro's name.</p> + +<h2 id="Obsolete_content">Obsolete content</h2> + +<p>If you come across an article whose content is obsolete -- meaning that everything on that page is out of date and shouldn't be used -- you can mark the page as such by adding the {{TemplateLink("obsolete_header")}} macro at the top of the article. Just open the page's editor and insert this at the top of the article:</p> + +<pre class="notranslate">\{{obsolete_header}}</pre> + +<p>You should also add the tag "Obsolete" to the tag list at the bottom of the page.</p> + +<div class="note"> +<p><strong>Note:</strong> If the article covers a Mozilla-specific technology, you can add the Gecko version in which the technology was removed from Gecko as a parameter to the {{TemplateLink("obsolete_header")}} macro, like this:</p> + +<pre class="notranslate">\{{obsolete_header(21)}}</pre> + +<p>This will make the banner specificy that the technology became obsolete in Gecko 21, with a link to the article <a href="/en-US/docs/Mozilla/Firefox/Releases/21" title="/en-US/docs/Mozilla/Firefox/Releases/21">Firefox 21 for developers</a>.</p> +</div> + +<p>Eventually, once something is very, very obsolete (that is, it's so obsolete that reading the material might actually cause serious problems), we can move content into our <a href="/en-US/docs/Archive">Archive</a> section. If you see material that you think should be archived, <a href="mailto:mdn-admins@mozilla.org?subject=Archival%20of%20content&body=%3C%3CPlease%20list%20the%20page%20to%20archive%20and%20why%20you%20think%20it%20should%20be%20archived%20here%3E%3E">contact an MDN administrator</a>.</p> + +<h2 id="Deprecated_content">Deprecated content</h2> + +<p>Deprecated content is content that covers a technology or idea that is in the process of becoming obsolete. It's no longer recommended, and is expected to be removed from browsers in the relatively near future. You can mark pages as deprecated using the {{TemplateLink("deprecated_header")}} macro. Just like with obsolete content, you can specify the Gecko version in which the technology was deprecated as a parameter, if the technology is Gecko-specific.</p> + +<p>You should also add the tag "Deprecated" to the page.</p> + +<h2 id="Non-standard_content">Non-standard content</h2> + +<p>Non-standard content is any content not yet part of a Web standard; this includes any technology that isn't even proposed as a draft specification, even if it's implemented by multiple browsers. You should use the {{TemplateLink("non-standard_header")}} macro on these pages, and tag the pages with "Non-standard".</p> diff --git a/files/ja/mdn/structures/code_examples/index.html b/files/ja/mdn/structures/code_examples/index.html new file mode 100644 index 0000000000..e6a25a49ec --- /dev/null +++ b/files/ja/mdn/structures/code_examples/index.html @@ -0,0 +1,218 @@ +--- +title: コード例 +slug: MDN/Structures/Code_examples +tags: + - Code + - Landing + - Live + - MDN Meta + - Static + - Structures + - インタラクティブ + - 例 +translation_of: MDN/Structures/Code_examples +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p class="summary">MDN には、Web プラットフォーム機能の使用方法を示すために、多数のコード例がページ全体に挿入されています。この記事では、コード例をページに追加する際に使用できるさまざまなメカニズムと、使用する必要があるものとそのタイミングについて説明します。</p> + +<h2 id="どのような種類のコード例が利用できますか？">どのような種類のコード例が利用できますか？</h2> + +<p>There are four types of code example available on MDN:</p> + +<ul> + <li>Static examples — plain code blocks, possibly with a screenshot to statically show the result of such code if it were to be run.</li> + <li>Traditional MDN "live samples" — A macro that takes plain code blocks, dynamically puts them into a document inside an {{htmlelement("iframe")}} element, and embeds it into the page to show the code running live.</li> + <li>GitHub "live samples" — A macro that takes a document in a GitHub repo inside the <a href="https://github.com/mdn/">mdn organization</a>, puts it inside an {{htmlelement("iframe")}} element, and embeds it into the page to show the code running live.</li> + <li>Interactive examples — Our system for creating <a href="https://github.com/mdn/interactive-examples">live interactive examples</a> that show the code running live but also allow you to change code on the fly to see what the effect is.</li> +</ul> + +<p>We'll discuss each one in later sections.</p> + +<h2 id="いつそれらを使うべきですか？">いつそれらを使うべきですか？</h2> + +<p>Each type of code example has it own use cases. When should you use each one?</p> + +<ul> + <li>Static examples are useful if you just need to show some code, and it isn't super important to show what the live result is. Some people just want something to copy and paste. Maybe you are just showing an intermediate step, or the source code is enough. (For example, the article is for an advanced audience, and they just need to see the code.) Also, you might be demonstrating an API feature that doesn't work well as an embedded example, which might need its own separate page to link to.</li> + <li>Traditional live samples are useful if you want to show source code on a page, then show it running, and you’re not that bothered about it being accessible as a standalone example. This approach also has the advantage that if you are showing source code and live examples side by side, you only need to update the code once to update both. They can however be awkward to edit and get working.</li> + <li>GitHub live samples are useful when you’ve got an existing example you want to embed, don’t want to show the source code for, and/or you want to make sure the example is available in standalone form. They have a better contribution workflow, but it does require you to know GitHub. Also because on-page code and source code are in two different places, it is easier for them to get out of sync.</li> + <li>The new interactive examples are great as readers can modify values on the fly — this is very valuable for learning. However, they are more complex to set up than the other forms, with more limitations, and are intended for specific purposes.</li> +</ul> + +<p>If you are not sure which one to use, you should default to traditional or GitHub live samples, depending on which one you are most comfortable with. You are also welcome to ask for advice on our <a href="https://discourse.mozilla.org/c/mdn">Discourse forum</a>.</p> + +<h2 id="一般的なガイドライン">一般的なガイドライン</h2> + +<p>Aside from the specific system for presenting the live samples, as summarized above, there are style and content cconsiderations to keep in mind when adding or updating samples on MDN?</p> + +<ul> + <li>When placing samples on a page, try to ensure that all of the features or options of the API or concept you're writing about are covered. At a minimum, at least the most-common options or properties should be included in examples.</li> + <li>Precede each example with an explanation of what the example does and why it's interesting or useful.</li> + <li>Follow each piece of code with an explanation of what it does.</li> + <li>When possible, break large examples into smaller pieces. For instance, the "live sample" system will automatically concatenate all your code together into one piece before running the example, so you can actually break your JavaScript, HTML, and/or CSS into smaller pieces with descriptive text after each piece if you choose to do so. This is a great way to help explain long or complicated stretches of code more clearly.</li> + <li>Go beyond just demonstrating how each piece of the API or technology works. Consider possible real-world use cases you might try to demonstrate.</li> +</ul> + +<h2 id="静的サンプル">静的サンプル</h2> + +<p>By static examples, we are talking about static code blocks that show how a feature might be used in code. These are put on a page using the <strong>PRE</strong> and <strong>Syntax Highlighter</strong> buttons on the MDN editor UI. An example result might look like this:</p> + +<pre class="brush: js notranslate">// This is a JS example +var test = "Hello"; +console.log(test);</pre> + +<div class="note"> +<p><strong>Note</strong>: For more details on adding code blocks to MDN pages, see our <a href="/en-US/docs/MDN/Contribute/Editor/Syntax_highlighting">Syntax highlighting</a> article.</p> +</div> + +<p>Optionally, you might want to show a static image of the code's resulting output. For example:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15523/console-example.png" style="border-style: solid; border-width: 1px; display: block; margin: 0px auto;"></p> + +<div class="note"> +<p><strong>Note</strong>: For more details on adding images to MDN pages, see our <a href="/en-US/docs/MDN/Contribute/Editor/Images">Images</a> article.</p> +</div> + +<h2 id="従来のライブサンプル">従来のライブサンプル</h2> + +<p>Traditional live samples are inserted into the page using the <span class="templateLink"><code><a class="external external-icon" href="https://github.com/mdn/kumascript/blob/master/macros/EmbedLiveSample.ejs">EmbedLiveSample</a></code></span> macro. An \{{EmbedLiveSample}} call dynamically grabs the code blocks in the same document section as itself and puts them into a document, which it then inserts into the page inside an {{htmlelement("iframe")}}. This is most easily demonstrated with an example, so let's look at one in this section and the next.</p> + +<ol> + <li>The easiest way is to press the <strong>Insert Code Sample Template</strong> button, which asks us for a title. For the example in the "{{anch("test")}}" section below, we entered "test" for the title, and the button generated the entire section for us.</li> + <li>Next, we entered some very simple sample code into the HTML, CSS, and JavaScript code blocks.</li> + <li>Finally, we published the page; the \{{EmbedLiveSample('test')}} call you can see in the edit view was replaced with an <code><iframe></code> containing the code running live.</li> +</ol> + +<p>If you look at the source inside the <code><iframe></code>, you'll see this:</p> + +<pre class="brush: html notranslate"><!DOCTYPE html> +<html> + <head> + <link href="https://developer.cdn.mozilla.net/static/build/styles/samples.37902ba3b7fe.css" + rel="stylesheet" type="text/css"> + + <style type="text/css"> + h1 { + color: blue; + } + </style> + </head> + <body> + <h1>Your example?</h1> + + + <script type="text/javascript"> + document.querySelector('h1').onclick = function() { + document.querySelector('h1').textContent = 'Your example?'; + }; + </script> + + </body> +</html></pre> + +<h3 id="その他のマクロパラメータ">その他のマクロパラメータ</h3> + +<p>The call we've used in the below example only uses one parameter — \{{EmbedLiveSample('test')}}. This simply defines which section of the document the code blocks should be grabbed from — <code>test</code> is the ID defined on the heading "test" below, so the macro will will grab all the code blocks inside that heading. Put another way, it will grab all the blocks below that heading, up until another {{htmlelement("h2")}} is encountered.</p> + +<p>There are some other optional parameters available too. You can include a second and third parameter, which will be a set width and height for the <code><iframe></code>. For example \{{EmbedLiveSample('test', '100%', '100px')}}. You can use pixel values or percentage values. Reasonable defaults are used if you omit these.</p> + +<p>There are also optional fourth and fifth parameters available, a screenshot URL that points to a screenshot showing the example should look like, and a page slug that points to another page on MDN —this is only used if you want to embed an example from another page. You won't use these two very often.</p> + +<p>See <a href="/en-US/docs/MDN/Contribute/Structures/Live_samples#EmbedLiveSample_macro">EmbedLiveSample macro</a> for more details on all these parameters.</p> + +<h3 id="伝統的なライブサンプルを使用するためのヒント">伝統的なライブサンプルを使用するためのヒント</h3> + +<ul> + <li>You don't need to use the <strong>Insert Code Sample Template</strong> button — but it is easier when you are getting used to using it. It is possible to just insert a \{{EmbedLiveSample('test')}} macro call inside any section of your page that contains code blocks, and it will work — as long as you set the first parameter to the ID of the document section it is inside.</li> + <li>You don't need the <em>HTML</em>, <em>CSS</em>, <em>JavaScript</em>, and <em>Result</em> headings, but it is considered best practice to include them where appropriate as it makes it easier to see what is going on. If you don't include them, you should include descriptive text to tell the reader what is happening.</li> + <li>You don't need HTML, CSS, and JavaScript code blocks — you can embed any combination you like — HTML and CSS, HTML and JavaScript, or even HTML only.</li> + <li>Another approach is to wrap your code blocks inside a block-level element with an ID, and then give the macro call that ID. For example, you could put your code blocks inside <code><div id="test"></div></code>, then use \{{EmbedLiveSample('test')}}.</li> + <li>In fact, this is a better option when you have a complex document hierarchy, and you are having trouble getting just the right code blocks to be embedded. In a complex document, this can be troublesome.</li> +</ul> + +<div class="note"> +<p><strong>Note</strong>: You can find a lot more information about traditional Live samples in our <a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">Live samples</a> article.</p> +</div> + +<h2 id="テスト">テスト</h2> + +<h3 id="HTML">HTML</h3> + +<pre class="brush: html notranslate"><h1>My example?</h1></pre> + +<h3 id="CSS">CSS</h3> + +<pre class="brush: css notranslate">h1 { + color: blue; +}</pre> + +<h3 id="JavaScript">JavaScript</h3> + +<pre class="brush: js notranslate">document.querySelector('h1').onclick = function() { + document.querySelector('h1').textContent = 'Your example?'; +};</pre> + +<h3 id="結果">結果</h3> + +<p>{{EmbedLiveSample('test')}}</p> + +<h2 id="GitHub_ライブサンプル">GitHub ライブサンプル</h2> + +<p>GitHub live samples are inserted into the page using the <span class="templateLink"><code><a class="external external-icon" href="https://github.com/mdn/kumascript/blob/master/macros/EmbedGHLiveSample.ejs">EmbedGHLiveSample</a></code></span> macro. An \{{EmbedGHLiveSample}} call dynamically grabs the document at a specified URL (which has to be inside the <strong>mdn</strong> GitHub organization), and inserts into the page inside an {{htmlelement("iframe")}}.</p> + +<p>These work in a very similar way to the {{anch("Traditional live samples")}}, but they are a lot simpler:</p> + +<p>You don't have to worry about placement of code blocks on the page — it simply grabs an HTML document in a GitHub repo, and puts it in the <code><iframe></code>.</p> + +<p>The macro only has three parameters:</p> + +<ol> + <li>The URL of the document to embed — this is relative to the mdn organization, the top level directory of which is at <span class="pl-s1"><span class="pl-s"><code>https://mdn.github.io/</code>. So this parameter needs to contain the part of the URL after that, e.g. </span></span><code>my-subdirectory/example.html</code>. You can omit the filename if it is called <code>index.html</code>.</li> + <li>The width of the <code><iframe></code>, which can be expressed as a percentage or in pixels.</li> + <li>The height of the <code><iframe></code>, which can be expressed as a percentage or in pixels.</li> +</ol> + +<p>Let's look at an example. Say we wanted to embed the code at <a href="https://mdn.github.io/learning-area/css/styling-boxes/backgrounds/">https://mdn.github.io/learning-area/css/styling-boxes/backgrounds/</a>. We could use the following call:</p> + +<p>\{{EmbedGHLiveSample("learning-area/css/styling-boxes/backgrounds/", '100%', 100)}}</p> + +<p>This looks like so when rendered:</p> + +<p>{{EmbedGHLiveSample("learning-area/css/styling-boxes/backgrounds/", '100%', 100)}}</p> + +<h3 id="GitHub_ライブサンプルを使用するためのヒント">GitHub ライブサンプルを使用するためのヒント</h3> + +<ul> + <li>You obviously need to get a suitable code sample onto the <a href="https://github.com/mdn/">mdn GitHub organization</a> first. This needs to be done using Git. If you are not familiar with Git, check out our <a href="/en-US/docs/Learn/Common_questions/Using_Github_pages">How do I use GitHub Pages?</a> article, and <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables#Preparing_to_add_the_data">Preparing to add the data</a> for more advanced uses.</li> + <li>Your code sample needs to be suitable to show what you are trying to demonstrate — it should contain one simple example that does one thing well, should have no offensive content in it, and should follow the MDN <a href="/en-US/docs/MDN/Contribute/Guidelines/Code_samples">Code sample guidelines</a>.</li> +</ul> + +<h2 id="インタラクティブな例">インタラクティブな例</h2> + +<p>The newest form of live example available on MDN is interactive live examples. These provide a step up from live examples, because the reader can edit the code and the live example updates on the fly. This is great for learning and experimentation.</p> + +<p>The interactive examples are intended to be used at the top of MDN reference pages — we are aiming to provide these to improve their value to beginners and other readers who want to just grab and play with an example quickly before seeing all the details of whatever they are looking up. There are a few important limitations to note about the interactive examples:</p> + +<ul> + <li>They are specialised for a particular technology — the UI for JavaScript is different from the UI for CSS, and they only illustrate one technology in isolation. They are not appropriate if you want to show, for example, how to combine a particular HTML/CSS/JS structure.</li> + <li>The interactive live examples are currently only set up to show CSS and JavaScript. For other technologies, you'll just have to wait.</li> + <li>The UI is more performance-intensive than other code examples; you shouldn't put more than one on each MDN article you apply them to.</li> + <li>They are not intended for large code examples — the UI supports a range of fixed sizes, which only really work for short (say, 10–15 line) examples.</li> +</ul> + +<p>If you want to submit an example, you can find out how at the <a href="https://github.com/mdn/interactive-examples/blob/master/CONTRIBUTING.md">interactive examples repo Contribution guide</a>.</p> + +<p>If you find a page that doesn't have an associated interactive example, you are welcome to contribute one! The <a href="https://discourse.mozilla.org/c/mdn">MDN Discourse forum</a> is a good place to ask for help or advice.</p> + +<h3 id="インタラクティブなサンプルデモ">インタラクティブなサンプルデモ</h3> + +<p>The <code>\{{EmbedInteractiveExample}}</code> macro is used to embed finished examples into MDN pages. For example, the macro call <code>\{{EmbedInteractiveExample("pages/js/array-push.html")}}</code> displays the following code example:</p> + +<div>{{EmbedInteractiveExample("pages/js/array-push.html")}}</div> + +<div> </div> + +<div>Try adjusting the code to see what happens, and playing with the controls.</div> diff --git a/files/ja/mdn/structures/compatibility_tables/index.html b/files/ja/mdn/structures/compatibility_tables/index.html new file mode 100644 index 0000000000..e93cfb04d2 --- /dev/null +++ b/files/ja/mdn/structures/compatibility_tables/index.html @@ -0,0 +1,476 @@ +--- +title: 互換性一覧表とブラウザー互換性データリポジトリ (BCD) +slug: MDN/Structures/Compatibility_tables +tags: + - MDN Meta + - ガイド + - ブラウザー互換性 + - 互換性テーブル + - 互換性一覧表 + - 構造 +translation_of: MDN/Structures/Compatibility_tables +--- +<div>{{MDNSidebar}}</div> + +<p class="summary"><span class="seoSummary">MDN には、オープンなウェブ文書のための互換性一覧表の標準形式があります。これは、すべてのブラウザーにわたって共有される DOM, HTML, CSS, JavaScript, SVG などの技術の文書で使用されます。</span>この記事は、作成した互換性一覧表をデータベースにどのように追加して維持するか、また、一覧表を記事に統合する方法についての「始め方」のガイドです。</p> + +<p class="summary">より高度なドキュメントや、データを表現するために使用される手続きや JSON スキーマの最新の変更点については、データリポジトリの <a href="https://github.com/mdn/browser-compat-data/blob/master/docs/contributing.md">contributor guide</a> や <a href="https://github.com/mdn/browser-compat-data/blob/master/docs/data-guidelines.md">data guidelines guide</a> をご覧ください。</p> + +<p class="summary">質問がある場合や問題を発見した場合は、 <a href="https://discourse.mozilla-community.org/c/mdn">MDN ディスカッションフォーラム</a>で相談してください。</p> + +<h2 id="How_to_access_the_data_repository" name="How_to_access_the_data_repository">データリポジトリにアクセスする方法</h2> + +<p>データは GitHub リポジトリに保存されています - <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> を参照してください。アクセスするには GitHub アカウントを取得し、 browser-compat-data を自分のアカウントで<ruby>フォーク<rp> (</rp><rt>fork</rt><rp>) </rp></ruby>し、フォークしたものをローカルマシンに<ruby>クローン<rp> (</rp><rt>クローン</rt><rp>) </rp></ruby>する必要があります。</p> + +<h2 id="Preparing_to_add_the_data" name="Preparing_to_add_the_data">データを追加する準備</h2> + +<p>新しいデータを追加する前に、フォークがメインリポジトリの最新である (同じ内容を含む) ことを確認し、フォーク内に追加を格納するための新しい<ruby>ブランチ<rp> (</rp><rt>ブランチ</rt><rp>) </rp></ruby>を作成し、そのブランチをローカルのクローンにプルすれば、その中で作業を始めることができます。</p> + +<p>フォークが最新であることを、次のように簡単な方法で確認してみましょう。</p> + +<h3 id="Adding_the_main_browser-compat-data_repo_as_a_remote" name="Adding_the_main_browser-compat-data_repo_as_a_remote">メインの browser-compat-data リポジトリをリモートとして追加</h3> + +<p>端末またはコマンドラインでフォークをローカルにクローンした場所へ行き、次のようにしてリモートにメイン (upstream) リポジトリを指すよう追加します (これを行う必要があるのは一度だけです)。</p> + +<pre class="brush: bash notranslate">git remote add upstream https://github.com/mdn/browser-compat-data.git</pre> + +<p>もしこれをしたか不明確であれば、次のようにリポジトリがどのリモートを指しているかを確認することができます。</p> + +<pre class="brush: bash notranslate">git remote -v</pre> + +<h3 id="Updating_your_fork_with_the_remotes_content" name="Updating_your_fork_with_the_remotes_content">リモートのコンテンツでフォークを更新する</h3> + +<p>では、フォークを更新したいときは、次のようにできます。</p> + +<ol> + <li> + <p>master ブランチにいることを確認します。</p> + + <pre class="brush: bash notranslate">git checkout master</pre> + </li> + <li> + <p>以下のように更新されたリポジトリのコンテンツを<ruby>フェッチ<rp> (</rp><rt>fetch</rt><rp>) </rp></ruby>します。</p> + + <pre class="brush: bash notranslate">git fetch upstream</pre> + </li> + <li> + <p>ローカルの master の内容をメイン (upstream) リポジトリの master の内容に<ruby>リベース<rp> (</rp><rt>rebase</rt><rp>) </rp></ruby>します。</p> + + <pre class="brush: bash notranslate">git rebase upstream/master</pre> + </li> + <li> + <p>以下のようにしてここまでの変更をあなたがフォークしたリモートへ反映します。</p> + + <pre class="brush: bash notranslate">git push</pre> + </li> +</ol> + +<h3 id="Creating_a_new_branch_to_do_your_work_in" name="Creating_a_new_branch_to_do_your_work_in">作業用の新しいブランチの作成</h3> + +<p>次に、自分のリモートフォーク (普通は<code>https://github.com/<em>自分のユーザー名</em>/browser-compat-data</code>) へ行き、以下の手順で新しいブランチを作成します。変更したい内容をここに追加していくことになります。</p> + +<ol> + <li>"Branch: Master" ボタンをクリックします。</li> + <li>新しいブランチの名前を "Find or create a branch..." と書かれたところに入力します。</li> + <li>"Create branch <em>ブランチ名</em> from Master" と書かれたボタンを押します。</li> +</ol> + +<p>例えば、 WebVR API についてデータを追加したい場合 "webvr" という名前がブランチ名として考えられるでしょう。</p> + +<h3 id="Switching_to_the_new_branch" name="Switching_to_the_new_branch">新しいブランチへの切り替え</h3> + +<p>ここから先は作業が端末またはコマンドラインに戻ります。ローカルにクローンしたものを更新して新しく作成したブランチを使えるようにするには、下のコマンドを使います。</p> + +<pre class="brush: bash notranslate">git pull</pre> + +<p>そして以下のように新しく作成したブランチに切り替えます。</p> + +<pre class="brush: bash notranslate">git checkout <em>name-of-branch</em></pre> + +<p>これでデータを追加するための準備が完了しました！</p> + +<h2 id="Adding_the_data" name="Adding_the_data">データの追加</h2> + +<p>データを追加するには、新たに互換性データを書いたファイルを作成する必要があります。作成する必要があるファイルは、どの技術分野について作業しようとするかによって異なります。</p> + +<ul> + <li><strong><a href="/ja/docs/Web/HTML">HTML</a>:</strong> HTML の要素ごとに一つのファイルが<a href="https://github.com/mdn/browser-compat-data/tree/master/html/elements">browser-compat-data/html/elements</a>に格納されています。ファイル名は要素の名前をすべて小文字でつけるべきです。 例) <code>div.json</code></li> + <li><strong><a href="/ja/docs/Web/CSS">CSS</a>:</strong> CSS のプロパティないしセレクターごとに一つのファイルが <a href="https://github.com/mdn/browser-compat-data/tree/master/css">browser-compat-data/css</a> 以下の適切なディレクトリに格納されています。ファイル名はその機能の名前をすべて小文字でつけてください。 例) <code>background-color.json</code>, <code>hover.json</code></li> + <li><strong><a href="/ja/docs/Web/JavaScript">JS</a>:</strong> JavaScriptオブジェクトごとに一つのファイルが<a href="https://github.com/mdn/browser-compat-data/tree/master/javascript/builtins">browser-compat-data/javascript/builtins</a>に格納されています。ファイル名は大文字小文字を含めて完全にオブジェクト名と一致させてください。 例) <code>Date.json</code>, <code>InternalError.json</code></li> + <li><strong><a href="/ja/docs/Web/API">APIs</a>:</strong> API のインターフェイスごとに一つのファイルが<a href="https://github.com/mdn/browser-compat-data/tree/master/api">browser-compat-data/api</a>に格納されています。ファイル名は大文字小文字を含めて完全にインターフェイス名と一致させてください。 例) WebVR API には<code>VRDisplay.json</code>や<code>VRDisplayCapabilities.json</code>などがあります</li> +</ul> + +<p>あなたが作成するファイルは、このリポジトリに含まれているスキーマで定義されている構造に従わなければなりません。<a href="https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md">詳細なスキーマの説明はこちら</a>で見ることができます。</p> + +<h3 id="Basic_compat_data_structure" name="Basic_compat_data_structure">基本的な互換性データの構造</h3> + +<p>では例を見ていきましょう。例として CSS プロパティの JSON ファイルに求められる基本構造を次に示します。</p> + +<pre class="brush: json notranslate">{ + "css": { + "properties": { + "border-width": { + "__compat": { + ... + } + } + } + } +}</pre> + +<p>まず <code>css</code> オブジェクトがあります。その中に <code>properties</code> オブジェクトがあります。 <code>properties</code> オブジェクトの中には、互換性データとして定義したい特定の機能につき一つのメンバーが必要です。それぞれのメンバーは <code>__compat</code> をメンバーに持ち、この中に実際のデータを記述します。</p> + +<p>上記のデータは <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/border-width.json">border-width.json</a> にあります。 <a href="/ja/docs/Web/CSS/border-width#Browser_compatibility">MDN で表示された border-width の表</a>と見比べてみてください。</p> + +<p>他の種類の機能についても同様ですが、ただしオブエジェクトの名前が異なります。</p> + +<ul> + <li>CSS セレクターは CSS プロパティと基本的に同様ですが、最上位のオブジェクト構造が <code>css.properties</code> ではなく <code>css.selectors</code> になります。例として <a href="https://github.com/mdn/browser-compat-data/blob/master/css/selectors/cue.json">cue.json</a> を見てください。</li> + <li>HTML についても基本的に同様ですが、最上位のオブジェクト構造が <code>html.elements</code> です。例として <a href="https://github.com/mdn/browser-compat-data/blob/master/html/elements/article.json">article.json</a> を見てください。</li> + <li>JavaScript の組込みオブジェクトについての最上位のオブジェクト構造は <code>javascript.builtins</code> です。例として <a href="https://github.com/mdn/browser-compat-data/blob/master/javascript/builtins/Array.json">Array.json</a> を見てください。</li> +</ul> + +<div> +<p>HTML や CSS、 JavaScript のページにおいては、普通一つだけの機能について記述するでしょう。しかし API インターフェイスについては少し事情が異なります。なぜなら常に複数のサブ機能を持つからです (下の {{anch("Sub-features", "サブ機能")}} を参照してください)。</p> + +<h3 id="Basic_structure_inside_a_feature" name="Basic_structure_inside_a_feature">機能内の基本構造</h3> + +<p>機能の <code>__compat</code> メンバーの中には、以下のメンバーを記述する必要があります。</p> + +<ul> + <li><code>mdn_url</code>: MDN 上のこの機能の参照ページの URL を指定します。これは、ロケールのディレクトリを含めずに記述する必要があることに注意してください。例えば、 <code>/docs/...</code> であり、 <code>/ja/docs/...</code> ではありません。これは、ローカライゼーションのために、データがページに置かれるときにマクロで追加されます。</li> + <li><code>support</code>: 報告したいすべての各ブラウザーにおける、この機能のブラウザーの対応情報を表すメンバーが含まれています。</li> + <li><code>status</code>: この機能の標準化過程の状態を報告するメンバーが含まれています。</li> +</ul> + +<p>ブラウザーメンバーの名前はスキーマで定義されています (<a href="https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md#browser-identifiers">Browser identifiers</a> を参照してください)。現在定義されている識別子の完全な一覧のもの使用してください。他のブラウザーを追加したい場合は、広範な影響があり、慎重に考えずに行うべきではありませんので、まず私たちに相談してください。</p> + +<p>基本的なブラウザーの compat データファイルでは、ブラウザー識別子のメンバーの中に "version_added" を含めるだけでよいでしょう (後ほど {{anch("Adding_data_Advanced_cases", "データの追加: 高度な場合")}} で説明します)。記述することができる値は以下の通りです。</p> + +<ul> + <li>バージョン番号: ブラウザーがその機能に対応し始めた正確なバージョンが分かる場合は、その番号を表す文字列を使用してください。例) <code>"47"</code>.</li> + <li><code>true</code>: ブラウザがその機能に対応しているが、正確なバージョン番号がわからない場合は、 <code>true</code> の値を使用してください。</li> + <li><code>false</code>: ブラウザーがその機能に対応していない場合は、 <code>false</code> の値を使用してください。</li> + <li><code>null</code>: ブラウザーがその機能に対応しているかどうかわからない場合は、 <code>null</code> の値を使用してください。</li> +</ul> + +<p><code>status</code> メンバーの内容には、以下の3つのサブメンバーの記述してください。</p> + +<ul> + <li><code>experimental</code>: この機能が<a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">実験的</a>であれば <code>true</code> を設定し、そうでない場合は <code>false</code> を設定してください。</li> + <li><code>standard_track</code>: この機能が何らかの標準化過程 (最も有名なものは W3C/WHATWG ですが、他にも Khronos, TC39, など) にある場合は <code>true</code> を設定し、そうでない場合は <code>false</code> を設定してください。</li> + <li><code>deprecated</code>: この機能が<a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">非推奨</a>であれば <code>true</code> に設定し、そうでない場合は <code>false</code> を設定してください。</li> +</ul> + +<p><a href="/ja/docs/Web/CSS/border-width#Browser_compatibility">border-width</a> の機能データ (<a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/border-width.json">border-width.json</a> も参照) を一例として以下に示します。</p> + +<pre class="brush: json notranslate">"__compat": { + "mdn_url": "https://developer.mozilla.org/docs/Web/CSS/border-width", + "support": { + "chrome": { + "version_added": "1" + }, + "webview_android": { + "version_added": "2" + }, + "edge": { + "version_added": true + }, + "edge_mobile": { + "version_added": true + }, + "firefox": { + "version_added": "1" + }, + "firefox_android": { + "version_added": "1" + }, + "ie": { + "version_added": "4" + }, + "ie_mobile": { + "version_added": "6" + }, + "opera": { + "version_added": "3.5" + }, + "opera_android": { + "version_added": "11" + }, + "safari": { + "version_added": "1" + }, + "safari_ios": { + "version_added": "3" + } + }, + "status": { + "experimental": false, + "standard_track": true, + "deprecated": false + } +}</pre> + +<h4 id="Adding_a_description" name="Adding_a_description">説明の追加</h4> + +<p><code>__compat</code> メンバーには、4つ目のオプションのメンバである、<code>description</code>があります。これを使用することで、その機能に関する人間にとって読みやすい説明を含めることができます。これを含めるべきなのは、データを少し見ただけではその機能が何であるかがわかりにくい場合だけです。例えば、データ構造を見ただけではコンストラクタが何であるかわからないかもしれないので、次のような記述を含めることができます。</p> + +<pre class="brush: json notranslate">{ + "api": { + "AbortController": { + "__compat": { + ... + }, + "AbortController": { + "__compat": { + "mdn_url": "https://developer.mozilla.org/docs/Web/API/AbortController/AbortController", + "description": "<code>AbortController()</code> constructor", + "support": { + ... + } + } + } + + ... etc. + } + } +}</pre> + +<h3 id="Sub-features" name="Sub-features">サブ機能</h3> + +<p>互換性一覧表が複数の行を持つページでは、各行の情報を定義するために、各機能の中に複数の副機能が必要になります。これは、例えば、ある機能の基本的なサポートが一つの行に格納されていても、そのしばらく後に、その機能が新しいプロパティや値の型を持つようになった場合などに起こります。</p> + +<p>例として、<code>background-color</code>プロパティの<a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/background-color.json">互換性データ</a> と <a href="/ja/docs/Web/CSS/background-color">対応するMDNページ</a> を参照してください。基本的なサポートは上で説明したように <code>__compat</code> オブジェクトの中に存在しており、ブラウザの "16進数値のアルファチャンネル "のサポートするに関する追加の行は、それ自身の<code>__compat</code> オブジェクトを含んでいます。</p> + +<pre class="brush: json notranslate">{ + "css": { + "properties": { + "background-color": { + "__compat": { + ... + }, + "alpha_ch_for_hex": { + "__compat": { + ... + }, + } + } + } + } +}</pre> + +<p>API の場合、上位 2 つのレベルを <code>api.<em>name-of-the-interface</em></code> として定義し、次に上位の <code>__compat</code> セクションでインターフェイスの全体的なブラウザ互換性を定義し、インターフェイス内に含まれるメソッド、プロパティ、およびコンストラクタのそれぞれのサブ機能を定義します。基本的な構造は以下のようになります。</p> + +<pre class="brush: json notranslate">{ + "api": { + "VRDisplay": { + "__compat": { + ... + }, + "cancelAnimationFrame": { + "__compat": { + ... + } + }, + "capabilities": { + "__compat": { + ... + } + }, + + ... etc. + + } + } +}</pre> + +<p>完全な例は、<a href="https://github.com/mdn/browser-compat-data/blob/master/api/VRDisplay.json">VRDisplay.json</a>を参照してください。</p> +</div> + +<h2 id="Adding_data_Advanced_cases" name="Adding_data_Advanced_cases">データの追加: 高度な場合</h2> + +<p>ブラウザの互換性データには、いくつかの高度な機能があります。このセクションの目的は、最も一般的なものをリストアップし、それぞれの例を提供して、あなた自身の互換性データにそれらを実装する方法を示すことです。</p> + +<h3 id="Including_a_footnote" name="Including_a_footnote">脚注を含める</h3> + +<p>しばしば互換性一覧表には、有益な詳細や、開発者にとって有用な奇妙な動作を説明する、特定のエントリに関連した脚注が含まれています。例として、{{domxref("VRDisplay.capabilities")}} (<a href="https://github.com/mdn/browser-compat-data/blob/master/api/VRDisplay.json">VRDisplay.json</a>も参照) の Chrome Android エントリには、(執筆時点では)"現在はGoogle Daydreamのみでサポートされています "という脚注がありました。これを互換性データに含めるために、関連する "chrome_android "サブメンバーの中に "notes "サブメンバーを追加しました。これはこのようになります。</p> + +<pre class="brush: json notranslate">"chrome_android": { + "version_added": true, + "notes": "Currently supported only by Google Daydream." +}</pre> + +<h3 id="Including_a_vendor_prefix" name="Including_a_vendor_prefix">ベンダープレフィックスを含める</h3> + +<p>ある機能が、あるブラウザでベンダープレフィックス付きでサポートされている場合、ブラウザの互換性データでそのことを明確にしたいと思うでしょう。Firefoxにおいて、 <code>-moz-</code> プレフィックスによりサポートされている機能を想像してください。互換性データでこれを指定するには、該当する "firefox" サブメンバーの中に "prefix" サブメンバーを追加する必要があります。これは次のようになります。</p> + +<pre class="brush: json notranslate">"firefox": { + "version_added": true, + "prefix": "-moz-" +}</pre> + +<h3 id="Including_browser_preferences_or_flags" name="Including_browser_preferences_or_flags">ブラウザーの設定やフラグを含める</h3> + +<p>いくつかの機能はブラウザでサポートされているかもしれませんが、それらは実験的なものであり、デフォルトではオフになっています。ユーザがこの機能を使いたい場合は、環境設定/フラグを使ってオンにする必要があります。</p> + +<p>互換性データでこれを表現するには、関連するブラウザ識別子サブメンバーの中に "flags" サブメンバーを追加する必要があります。flags" の値は、3つのメンバを含むオブジェクトの配列です。</p> + +<ul> + <li><code>type</code>: フラグやプリファレンスのタイプ。最も一般的な値は "preference"で、これはブラウザ内部で設定されます(例えば、Firefoxではabout:config、Chromeではchrome://flagsを使用します)が、時には "compile_flag "という、ブラウザのビルドがコンパイルされるときに設定される値を使用することもあります。</li> + <li><code>name</code>: これは、値を設定する必要がある設定の名前を表す文字列です。例えば、"Enable Experimental Web Platform Features" はChromeに存在する環境設定で、Chromeでは<code>chrome://flags</code>にあります。</li> + <li><code>value_to_set</code>: 設定する値を表す文字列で、例えば "true "などです。</li> +</ul> + +<p>つまり、ある機能のChromeのサポートに環境設定/フラグを追加するには、次のようにします。</p> + +<pre class="brush: json notranslate">"chrome": { + "version_added": "50", + "flags": [ + { + "type": "preference", + "name": "Enable Experimental Web Platform Features", + "value_to_set": "true" + } + ] +},</pre> + +<p>もしその機能が2つ以上のフラグの元にある場合、この例のように "flags"配列にオブジェクトを追加することができます。</p> + +<pre class="brush: json notranslate">"firefox": { + "version_added": "57", + "flags": [ + { + "type": "preference", + "name": "dom.streams.enabled", + "value_to_set": "true" + }, + { + "type": "preference", + "name": "javascript.options.streams", + "value_to_set": "true" + } + ] +},</pre> + +<h3 id="Including_a_version_where_support_was_removed" name="Including_a_version_where_support_was_removed">対応が削除されたバージョンを含める</h3> + +<p>あるブラウザのバージョンで追加された機能が、非推奨となったために再び削除されることがあります。これは、削除されたバージョン番号を表す文字列を値として受けとる、"version_removed" サブメンバーを使えば簡単に表現できます。例えば、以下のようになります。</p> + +<pre class="brush: json notranslate">"firefox": { + "version_added": "35", + "version_removed": "47", +},</pre> + +<h3 id="Including_multiple_support_points_for_the_same_browser_entry" name="Including_multiple_support_points_for_the_same_browser_entry">同じブラウザーの項目に複数の対応ポイントを含む</h3> + +<p>同じブラウザの複数のサポートデータポイントを、同じ機能の中に追加したい場合もあるでしょう。</p> + +<p>例えば、 {{cssxref("text-align-last")}} プロパティ（<a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/text-align-last.json">text-align-last.json</a>も参照）は、バージョン35でChromeに追加され、プレフィックス付きでサポートされました。</p> + +<p>上記のサポートはバージョン 47 で削除されましたが、バージョン 47 でもデフォルトで <code>text-align-last</code> が有効になるようにサポートが追加されました。</p> + +<p>これらのデータポイントの両方を含めるために、"chrome "サブメンバーの値を、単一のサポート情報オブジェクトではなく、2つのサポート情報オブジェクトを含む配列にすることができます。</p> + +<pre class="brush: json notranslate">"chrome": [ + { + "version_added": "47" + }, + { + "version_added": "35", + "version_removed": "47", + "flags": [ + { + "type": "preference", + "name": "Enable Experimental Web Platform Features", + "value_to_set": "true" + } + ] + } +],</pre> + +<div class="blockIndicator note"> +<p><strong>注:</strong> 配列の中には、最新または重要なサポートポイントを最初に配置するべきです。こうすることで、単に最新の情報を取得したい人にとって読みやすいデータとなります。</p> +</div> + +<h3 id="Including_an_alternative_name" name="Including_an_alternative_name">別名を含める</h3> + +<p>時々、ブラウザが仕様とは異なる名前で機能をサポートすることがあります。これは例えば、あるブラウザがある機能の実験的なサポートを早くから追加していて、仕様が安定する前に名前が変わってしまったというような場合が考えられます。</p> + +<p>このようなケースをブラウザの互換性データに含めるには、"alternative_name"メンバの中に代替名を指定するサポート情報ポイントを含めます。</p> + +<div class="blockIndicator note"> +<p><strong>注:</strong> 代替名は正確なエイリアスではないかもしれません。標準バージョンとは異なる動作をするかもしれません。</p> +</div> + +<p>では例を見てみましょう。{{cssxref("border-top-right-radius")}} プロパティ（<a href="https://github.com/mdn/browser-compat-data/blob/2a0cc3f6bb17aa4345441bed47a059dffd847793/css/properties/border-top-right-radius.json">border-top-right-radius.json</a>も参照）のFirefoxでのサポートは以下の通りです。</p> + +<ul> + <li>バージョン 4 以降では <code>border-top-right-radius</code> という標準的な名前でサポートされています。</li> + <li>バージョン 49 以降では、ブラウザの互換性を考慮し、<code>-webkit-</code>プレフィクスと共に使用されます。</li> + <li>バージョン 1 以降では <code>-moz-border-radius-topright</code> という代替名を使用しています。このエイリアスのサポートはバージョン12で削除されました。</li> +</ul> + +<p>これをデータで表現するために、以下のJSONを使用しました。</p> + +<pre class="brush: json notranslate">"firefox": [ + { + "version_added": "4", + "notes": "Prior to Firefox 50.0, border styles of rounded corners were always rendered as if <code>border-style</code> was solid. This has been fixed in Firefox 50.0." + }, + { + "prefix": "-webkit-", + "version_added": "49", + "notes": "From Firefox 44 to 48, the <code>-webkit-</code> prefix was available with the <code>layout.css.prefixes.webkit</code> preference. Starting with Firefox 49, the preference defaults to <code>true</code>." + }, + { + "alternative_name": "-moz-border-radius-topright", + "version_added": "1", + "version_removed": "12" + } +],</pre> + +<h2 id="Pushing_a_change_back_to_the_main_repo" name="Pushing_a_change_back_to_the_main_repo">変更のメインリポジトリへの反映</h2> + +<p>互換性データの追加が終わったら、まず以下のコマンドを使ってテストしてみてください。</p> + +<ul> + <li><code>npm run lint</code> — すべての互換性データをテストして、JSONが有効であること、正しいスタイルで書かれていること、例えば正しいインデント、カンマの欠落がないことなどを確認します。ファイル名とテスト結果の長いリストが表示されます。エラーが見つかった場合、リンターは見つかったファイルに対してエラーをスローし、行番号やエラーメッセージなどのデバッグに役立つ情報を表示します。</li> + <li><code>npm run show-errors</code> — JSON をデータスキーマと照らし合わせて検証し、無効なブラウザのバージョン番号が使用されているなどのエラーをハイライトします。</li> +</ul> + +<p>問題がなさそうであれば、コミットして、GitHub上のあなたのリモートフォークにプッシュする必要があります。これは、以下のようなターミナルコマンドで簡単に行うことができます。</p> + +<pre class="brush: bash notranslate">git add . +git commit -m 'adding compat data for <em>name-of-feature</em>' +git push</pre> + +<p>リモートフォーク (URLの例: <code>https://github.com/<em>your-username</em>/browser-compat-data</code>) に行くと、ファイルリストの一番上 (「最近プッシュしたブランチ」の下) にあなたのプッシュに関する情報が表示されているはずです。プルリクエスト（あなたのリモートフォークをメインリポジトリに取り込むための、最初の過程のことです）を作成するには、"Compare & pull request" ボタンを押して、続く画面の簡単なプロンプトに従ってください。</p> + +<p>これが終われば、ただ待つのみです。レビュアーがあなたのプルリクエストをレビューし、メインリポジトリにマージします。そうでない場合は、変更を依頼します。変更が必要な場合は、変更を加えて、プルリクエストが受理されるまで再度投稿してください。</p> + +<h2 id="Inserting_the_data_into_MDN_pages" name="Inserting_the_data_into_MDN_pages">MDN ページへのデータの挿入</h2> + +<p>一度あなたの新しいデータがメインリポジトリに含められたら、{{TemplateLink("Compat")}} マクロを使って、MDNページ上でそのデータに基づいてブラウザの互換性一覧表を動的に生成することができます。これは、JSONデータを探索して、互換性一覧表を生成したい機能を表すオブジェクトを見つけるために必要なドット記法を唯一のパラメータとして受け取ります。</p> + +<p><br> + マクロ呼び出しの上に、他のコントリビューターにとって使いやすくするために、編集モードのMDNでコントリビューターにのみ表示される隠しテキストを追加します。</p> + +<pre class="brush: html notranslate"><div class="hidden"> +The compatibility table on this page is generated from structured data. +If you'd like to contribute to the data, please check out +<a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> +and send us a pull request. +</div></pre> + +<p>例として、HTTPヘッダーに関するページである {{HTTPHeader("Accept-Charset")}} では、マクロの呼び出しは次のようになっています。 <code>\{{Compat("http.headers.Accept-Charset")}}</code>リポジトリ内の<a href="https://github.com/mdn/browser-compat-data/blob/master/http/headers/accept-charset.json">accept-charset.json</a>ファイルを見ると、これが JSON データにどのように反映されているかがわかると思います。</p> + +<p>別の例として、{{domxref("VRDisplay.capabilities")}} プロパティの互換性一覧表は、 <code>\{{Compat("api.VRDisplay.capabilities")}}</code>を使用して生成されます。マクロ呼び出しにより、以下の表（および対応する一連の注釈）が生成されます。</p> + +<hr> +<div class="hidden">このページの互換性一覧表は構造化データから生成されています。データに協力していただけるのであれば、 <a class="external" href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> をチェックアウトしてプルリクエストを送信してください。</div> + +<p>{{Compat("api.VRDisplay.capabilities")}}</p> + +<div class="blockIndicator note"> +<p><strong>注:</strong> ファイル名は、JSON 構造体内のインターフェイスに与えられたラベルと一致することがよくありますが、必ずしもそうとは限りません。マクロ呼び出しがテーブルを生成するときには、使用する JSON を見つけるまですべてのファイルを探索するので、ファイル名はそれほど重要ではありません。そうは言っても、常に可能な限り直感的な名前を付けるべきです。</p> +</div> diff --git a/files/ja/mdn/structures/index.html b/files/ja/mdn/structures/index.html new file mode 100644 index 0000000000..a3118f3080 --- /dev/null +++ b/files/ja/mdn/structures/index.html @@ -0,0 +1,16 @@ +--- +title: 文書の構造 +slug: MDN/Structures +tags: + - Landing + - MDN Meta + - Structures +translation_of: MDN/Structures +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p>MDN 全体で見ると、MDNの記事内で統一的な情報の提示を行うために、繰り返し使われている様々な文書の構造があります。ここにあるのは、それらの構造について述べた記事です。これは文書を書いたり、編集したり、翻訳したりするのにふさわしい構造であると、MDN の執筆者であるあなたが気づき、適用し、そして変更できるものです。</p> + +<p>（訳注：下位の各ページを和訳すると、ここに表示されます）</p> + +<p>{{LandingPageListSubPages()}}</p> diff --git a/files/ja/mdn/structures/live_samples/index.html b/files/ja/mdn/structures/live_samples/index.html new file mode 100644 index 0000000000..b45feb16a9 --- /dev/null +++ b/files/ja/mdn/structures/live_samples/index.html @@ -0,0 +1,258 @@ +--- +title: ライブサンプル +slug: MDN/Structures/Live_samples +tags: + - Intermediate + - MDN Meta + - Structures + - ガイド +translation_of: MDN/Structures/Live_samples +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">MDN は、記事に表示されているサンプルコードを、実際に見ている実行可能なサンプルに変換することをサポートしています。これらのライブサンプルには、HTML、CSS、およびJavaScriptを任意の組み合わせで含めることができます。</span>「ライブ」サンプルはインタラクティブではありません。ただし、実際にコードサンプルによって生成されるため、サンプルの表示出力はサンプルのコードと正確に一致します。</p> + +<h2 id="How_does_the_live_sample_system_work" name="How_does_the_live_sample_system_work">ライブサンプルシステムの仕組み</h2> + +<p>ライブサンプルシステムは、グループ内のすべてのコードを集め、1 つの HTML ファイルにマージし、その HTML を {{HTMLElement("iframe")}} にレンダリングします。このためライブサンプルは2つの部分で構成されています。</p> + +<ul> + <li>コードブロックのグループ</li> + <li>コードブロックの結果を表示する (フレームまたはリンクを作成する) マクロ</li> +</ul> + +<p>このコンテキストでは、コードブロックの「グループ」は、見出しまたはブロック要素 ( {{HTMLElement("div")}} など) の ID によって識別されます。</p> + +<ul> + <li>ID がブロック要素に属する場合、そのグループは、その ID が使用される囲むブロック要素内のすべてのコードブロックを含む。</li> + <li>ID が見出しに属する場合、その見出しの後ろで同じ見出しレベルの次の見出しの前にあるすべてのコードブロックがグループに含まれます。指定された見出しの小見出しのコードブロックはすべて使用されていることに注意してください。これがあなたが望む効果でない場合は、代わりにブロック要素に ID を使用してください。</li> +</ul> + +<p>このマクロでは、特別な URL を使用して、<code>http://<em>url-of-page</em>$samples/<em>group-id</em></code> (<code>group-id</code> はコードが配置されている見出しまたはブロックの ID) という特定のグループのサンプルコードを取得します。</p> + +<p>結果として得られるフレーム (またはページ) はサンドボックスで保護されており、技術的にはウェブ上で動作するものすべてを行う可能性があります。もちろん、実際の問題として、コードはそのページの要点に貢献しなければなりません。MDN 上で実行されているランダムなものは、エディターコミュニティによって削除されます。</p> + +<div class="note"> +<p><strong>注意:</strong> ライブサンプルの出力を表示するには、マクロを使用する<strong>必要があります。</strong>MDN のエディターは、セキュリティを確保するために <code><iframe></code> 要素の直接使用を取り除きます。</p> +</div> + +<p>サンプルのコードを含む各 {{HTMLElement("pre")}} ブロックには、HTML、CSS、または JavaScript コードのいずれかを示すクラスがあり、それぞれ「brush:html」、「brush:css」、「brush:js」です。これらのクラスは、wiki が正しく使うために、対応するコードブロック上になければなりません。幸いにも、各クラスはエディターのツールバーで構文ハイライト機能を使用すると自動的に追加されます。</p> + +<p>ライブサンプルシステムには多数のオプションが用意されており、少しずつ見ていきます。</p> + +<h3 id="Live_sample_macros" name="Live_sample_macros">ライブサンプルのマクロ</h3> + +<p>ライブサンプルを表示するために使用できるマクロは 2 つあります。</p> + +<ul> + <li><span class="templateLink"><code><a href="https://github.com/mdn/kumascript/blob/master/macros/EmbedLiveSample.ejs">EmbedLiveSample</a></code></span> はライブサンプルをページに埋め込みます。</li> + <li><span class="templateLink"><code><a href="https://github.com/mdn/kumascript/blob/master/macros/LiveSampleLink.ejs">LiveSampleLink</a></code></span> はライブサンプルを新しいページに開くリンクを作成します。</li> +</ul> + +<p>多くの場合、<span class="templateLink"><code><a href="https://github.com/mdn/kumascript/blob/master/macros/EmbedLiveSample.ejs">EmbedLiveSample</a></code></span> や <span class="templateLink"><code><a href="https://github.com/mdn/kumascript/blob/master/macros/LiveSampleLink.ejs">LiveSampleLink</a></code></span> マクロは、追加の作業をほぼ全くすることなくページに追加することができます。サンプルが見出しの ID で識別されるか、ID を持つブロックに含まれていれば、マクロを追加するだけでその作業が行われるはずです。</p> + +<h4 id="EmbedLiveSample_macro" name="EmbedLiveSample_macro">EmbedLiveSample マクロ</h4> + +<pre class="syntaxbox notranslate"> \{{EmbedLiveSample(<em>block_ID</em>, <em>width</em>, <em>height</em>, <em>screenshot_URL</em>, <em>page_slug</em>)}}</pre> + +<div class="Note"> +<dl> + <dd>見出しが翻訳されている場合、その ID 属性が自動的に翻訳されたテキストに合わせてアップデートされます。そのため、マクロ内で呼び出される <em>block_ID</em> の値を変更しなくていけません。{{訳注("日本語では見出し要素には <code>name</code> 属性を追加して英語版と同じ ID となるようにしています。")}}</dd> +</dl> +</div> + +<dl> + <dt>block_ID</dt> + <dd>必須: コードを描画する見出しまたは囲みブロックの ID。適切な ID であるかどうかを確認する最善の方法は、ページの目次のセクションの URL を見ることです。<strong>注記:</strong> 見出しが翻訳されている場合、その ID 属性が自動的に翻訳されたテキストに合わせてアップデートされます。そのため、マクロ内で呼び出される <em>block_ID</em> の値を変更しなくていけません。 {{訳注("日本語では見出し要素には <code>name</code> 属性を追加して英語版と同じ ID となるようにしています。")}}</dd> + <dt>width</dt> + <dd>作成する {{HTMLElement("iframe")}} の幅で、<code>px</code> で指定します。これはオプションで、省略すると合理的なデフォルト幅が使用されます。特定の幅を使用する場合は、height パラメーターも指定する<em>必要があります。</em></dd> + <dt>height</dt> + <dd>作成する {{HTMLElement("iframe")}} の高さで、<code>px</code> で指定します。これはオプションで、省略すると合理的なデフォルトの高さが使用されます。特定の高さを使用する場合は、width パラメーターも指定する<em>必要があります。</em>どちらか一方しか使用しない場合は、デフォルトのフレームサイズが使用されます。</dd> + <dt>screenshot_URL</dt> + <dd>ライブサンプルの外観を示すスクリーンショットの URL。これはオプションですが、新しいテクノロジが動作しないユーザのブラウザに対して役立つ可能性があるため、サンプルがブラウザーでサポートされている場合の様子を確認できます。このパラメータを含めると、ライブサンプルの横に、適切な見出し付きのスクリーンショットが表示されます。</dd> + <dt>page_slug</dt> + <dd>サンプルが入っているページのスラグ。これはオプションで、指定されていない場合はマクロが使用されている同じページからサンプルが引き出されます。</dd> +</dl> + +<ol> +</ol> + +<h4 id="LiveSampleLink_macro" name="LiveSampleLink_macro">LiveSampleLink マクロ</h4> + +<pre class="syntaxbox notranslate"> \{{LiveSampleLink(<em>block_ID</em>, <em>link_text</em>)}}</pre> + +<dl> + <dt>block_ID</dt> + <dd>コードを引っ張ってくる見出しまたは囲みブロックの ID。正しいIDであるかどうかを確認する最善の方法は、ページの目次のセクションの URL を見ることです。<strong>注記:</strong> 見出しが翻訳されている場合、その ID 属性が自動的に翻訳されたテキストに合わせてアップデートされます。そのため、マクロ内で呼び出される <em>block_ID</em> の値を変更しなくていけません。{{訳注("日本語では見出し要素には <code>name</code> 属性を追加して英語版と同じ ID となるようにしています。")}}</dd> + <dt>link_text</dt> + <dd>リンクテキストとして使用する文字列。</dd> +</dl> + +<h2 id="Using_the_live_sample_system" name="Using_the_live_sample_system">ライブサンプルシステムを使用する</h2> + +<p>以下のセクションでは、ライブサンプルシステムの一般的な使用例をいくつか説明します。</p> + +<p>これらのすべてのケースでライブサンプルの結果を表示するには、エディターで<strong>公開</strong>をクリックする必要があります (編集モードから離れます)。ライブサンプルには<a href="https://ja.wikipedia.org/wiki/%E3%82%A4%E3%83%B3%E3%82%BB%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3">インセプション</a>のように再帰的な性質があるため、<strong>プレビュー</strong>機能でライブサンプルを表示することは<em>できません。</em></p> + +<h3 id="Turning_snippets_into_live_samples" name="Turning_snippets_into_live_samples">スニペットをライブサンプルにする</h3> + +<p>よく使用されるケースの 1 つは、既に MDN に表示されている既存のコードスニペットを実際のサンプルに変換することです。</p> + +<h4 id="Prepare_the_code_samples" name="Prepare_the_code_samples">コードサンプルを準備する</h4> + +<p>最初のステップでは、コードスニペットを追加するか、既存のサンプルをコンテンツやマークアップの観点からライブサンプルとして使用できるようにします。コードスニペットは、まとめて実行可能な完全な例を構成する必要があります。たとえば、既存のスニペットに CSS のみが表示されている場合は、CSS が操作する HTML のスニペットを追加する必要があります。<br> + <br> + それぞれのコードは {{HTMLElement("pre")}} ブロックにあり、各ブロックはブロックごとに言語ごとに適切にマークされていなければなりません。ほとんどの場合、これは既に行われていますが、コードの各部分が正しい構文で構成されていることを確認することは、常に二重チェックしておく価値があります。ツールバーの <strong>PRE</strong> アイコンの隣には、MDN が構文強調表示を行うさまざまな言語のドロップダウンメニューアイコン (ツールヒント: 構文ハイライター) があります。構文の強調表示のためにブロックの言語を設定することで、ライブサンプルシステムの目的のための言語と関連付けられます。</p> + +<div class="note"> +<p><strong>注意:</strong> 複数の言語のブロックが独立していて、すべて一緒に連結する場合があるかもしれません。コードの塊りに続いて、動作原理の説明があって、また次の塊り、…という構成ができます。これにより、説明テキストを交えたライブサンプルを利用するチュートリアルなどを作成することがより容易になります。</p> +</div> + +<p>HTML、CSS、JavaScript コードの {{HTMLElement("pre")}} ブロックがそれぞれの言語の構文強調表示に対して正しく設定されていることを確認してください。</p> + +<div class="note"> +<p><strong>注意:</strong> MDN にコンテンツを貼り付ける際には、意図せず不要なスタイルやクラスを取り込む可能性のあるスタイル付きコンテンツ (たとえば、別のサイトからコピーされたコードの構文強調を含む) を貼り付けることを意識してください。こうならないように注意してください。必要に応じて、ソースモードで編集内容を確認し、不要なスタイルやクラスを削除してください (貼り付ける前に確認するか、代わりに「プレーンテキストとして貼り付け」オプションを使用してください)。</p> +</div> + +<h4 id="Insert_the_live_sample_macro" name="Insert_the_live_sample_macro">ライブサンプルマクロを挿入する</h4> + +<p>コードが配置され、各ブロックの言語を識別するように適切に構成されたら、iframeを作成するマクロを挿入する必要があります。</p> + +<ol> + <li>ツールバーの<strong>コードサンプルの iFrame を挿入</strong>ボタン (<img alt="" src="https://mdn.mozillademos.org/files/5383/insert-live-sample-btn.png" style="height: 18px; width: 19px;">) をクリックします。<br> + ライブサンプルフレームを設定するためのダイアログボックスが開きます<br> + <img alt="" src="https://mdn.mozillademos.org/files/5385/sample-finder.png" style="height: 358px; width: 405px;"></li> + <li><strong>ドキュメント</strong>に埋め込みたいサンプルが含まれている記事のタイトルを入力します。<br> + デフォルトでは現在編集中の記事ですが、MDN の別の場所で記事を選択することもできます。これにより、必要に応じて複数ページのサンプルを再利用することができます。(このフィールドに新しいテキストを入力すると、部分的に一致するページのメニューが表示され、必要なページのタイトルを選択します)</li> + <li><strong>ドキュメント内のセクション</strong>メニューで、埋め込みたいサンプルのコードブロックを含む記事のセクションを選択します</li> + <li><strong>OK</strong>ボタンをクリックして、サンプルフレームを作成するマクロ呼び出しを生成して挿入します。マクロ呼び出しは次のようになります<br> + <strong>\{{ EmbedLiveSample('Live_sample_demo') }}</strong></li> +</ol> + +<h3 id="Adding_a_new_live_sample" name="Adding_a_new_live_sample">新規ライブサンプルを追加する</h3> + +<p>新しいページを作成していて、ライブサンプルとして提示したいコードを挿入したい場合は、さらに多くの作業をエディターで行うことができます！</p> + +<ol> + <li>ツールバーの<strong>コードサンプルテンプレートを挿入</strong>ボタン (<img alt="" src="/files/4265/live-sample-button.png" style="height: 19px; width: 21px;">) をクリックします。<br> + ライブサンプルに名前を付けるよう求める簡単なダイアログが表示されます。<br> + <img alt="" src="https://mdn.mozillademos.org/files/5387/insert-live-sample-template.png" style="height: 155px; width: 251px;"></li> + <li>サンプルのタイトルを入力します。これはサンプルの見出しとして使用されます。このタイトルがページの文脈の中で意味が通ることを確認してください。</li> + <li>入力したタイトルの新しい見出しが、HTML、CSS、およびJavaScript用のサブ見出しと空のコードブロックとともに作成されます。</li> + <li>必要のない見出しやコードブロックを削除してください。</li> + <li>適切なコードブロックでサンプルを構成するコードを入力します。</li> + <li><a href="#conventions">取り決めを確認します。</a></li> +</ol> + +<h3 id="Using_the_Sample_Finder" name="Using_the_Sample_Finder">サンプルファインダーを使う</h3> + +<p>前述のように、サンプルファインダーは、<strong>コードサンプルの iFrame を挿入</strong>アイコンをクリックするとアクティブになります。残念なことに、サンプルファインダーは編集しないと<strong>使用できない</strong>マクロを生成することがあります。必要に応じて慎重にチェックして編集すべき 2 つの問題エリアがあります。</p> + +<ol> + <li><strong>ドキュメント</strong>フィールド。このフィールドは入力時に検索され、入力した文字列にマッチするドキュメントのリストが表示されます。しかし、提示されたリストにはサブページは<strong>含まれません</strong>。たとえば、メインページの <a href="https://developer.mozilla.org/ja/docs/Web/CSS/@counter-style">@counter-style</a> の下にある <a href="https://developer.mozilla.org/ja/docs/Web/CSS/@counter-style/negative">Negative </a>のサブページで作業しているとします。サンプルファインダーでの検索では Negative は見つかりませんが、メインページの @counter-style が検索されます。@counter-style を選択すると、フィールドの背景が緑色に変わります。このことによる問題については以下を参照してください。</li> + <li><strong>ドキュメントのセクション</strong>。ドキュメント内のプルダウンメニューのセクションに、必要なセクションが表示されないことがあります。例のように、ただ一つ選択して簡単な編集をすることで修正することができます。</li> +</ol> + +<p>サンプルファインダーは次のようになりました。</p> + +<pre class="notranslate"><code>\{{ EmbedLiveSample('Examples', '', '', '', 'Web/CSS/@counter-style') }}</code></pre> + +<p>このマクロは動作しません。block_ID が Examples となっていますが、この場合は Example でなければなりません。(このセクションのソース ID を調べて、使用する必要のある block_ID を確認してください。) 同様に page_slug が @counter-style になっていますが、@counter-style/negative となるべきです。これらの修正は、編集ページで直接行うことができます。</p> + +<p>編集すると、マクロは次のようになります。</p> + +<pre class="notranslate"><code>\{{ EmbedLiveSample('Example', '', '', '', 'Web/CSS/@counter-style/negative') }}</code></pre> + +<p>この編集されたマクロは動作します。マクロが正常に動作している場合は、<strong>Open in CodePen </strong>ボタンが表示されます。この例のサムネイルは、<strong>Open in CodePen</strong> ボタンの上に表示されます。ボタンがあるがサムネイルがない場合は、少し待ってください。サーバーがこれを生成するには時間がかかることがあります。</p> + +<h2 id="Live_sample_demo" name="Live_sample_demo">更新が必要なサンプルを検索する</h2> + +<p>既存のサンプルを探して更新する場合は、更新の主な 3 つの種類があります:</p> + +<ul> + <li>既存の非ライブサンプルスニペットをライブサンプルに変換。</li> + <li>既存のライブサンプルのバグを修正。</li> + <li>既存のライブサンプルを改善、または、技術の変化に基づいてサンプルを更新。</li> +</ul> + +<div class="note"> +<p><strong>注意:</strong> ライブサンプルシステムを使用するために更新が必要なサンプルがある記事を見つけた場合は、タグ「NeedsLiveSample」をページに追加してください。</p> +</div> + +<h3 id="Finding_samples_to_turn_into_live_samples" name="Finding_samples_to_turn_into_live_samples">ライブサンプルに変換するサンプルを検索する</h3> + +<p>MDN にはライブサンプルシステムをまだ使用していない古いサンプルがたくさんあります。私たちの目標は、これらのほとんどまたはすべてをライブサンプルに更新することです。これにより、一貫性とユーザビリティが向上します。MDN を日常的に使用するときには、これらの多くがほぼ確実に見つかるでしょう。しかし、あなたが特にそれらを更新しようと探している場合、それらを見つけることができますか？残念ながら簡単な方法はありません。ですが、それらを追跡するのに役立つガイドラインがいくつかあります：</p> + +<ul> + <li>まず、<a href="/ja/docs/tag/NeedsLiveSample">「NeedsLiveSample」というタグが付けられたこのページのリスト</a>を見てみましょう。これらは、ユーザーが更新が必要とマークしたページです。ライブサンプルを使用するように更新する必要のあるページが表示されてもすぐに修正する時間がない場合は、このタグを自分で追加する必要があります。</li> + <li><a href="/ja/docs/Web/JavaScript/Guide">JavaScript ガイド</a>、<a href="/ja/docs/Web/HTML">HTML ドキュメント</a>、<a href="/ja/docs/Web/CSS/Reference">CSS リファレンス</a>などのサンプルが含まれている可能性のあるドキュメントツリーを参照してください。</li> + <li>「<a href="/search?q=example">example</a>」や 「<a href="/search?q=sample">sample</a>」のような用語を検索し、更新するページがないか、検索結果を調べます。</li> +</ul> + +<h2 id="Live_sample_demo" name="Live_sample_demo">ライブサンプルのデモ</h2> + +<p>このセクションは、ライブサンプルテンプレートボタンを使用してメイン見出し (「ライブサンプルデモ」) だけでなく、HTML、CSS、および JavaScript コンテンツのサブ見出しも作成した結果です。それぞれのブロックに限定されませんし、さらに、特定の順序である必要はありません。</p> + +<p>削除したいものを削除することもできます。スクリプトが必要ない場合は、その見出しとその {{HTMLElement("pre")}} ブロックを削除してください。コードブロック (HTML、CSS、または JavaScript) の見出しは、ライブサンプルマクロでは使用されないため、削除することもできます。</p> + +<p>テンプレートが挿入されたので、いくつかのコード、さらには説明テキストを挿入することができます。</p> + +<h3 id="HTML" name="HTML">HTML</h3> + +<p>この HTML は、メッセージの配置とスタイルに役立つ段落とブロックを作成します。</p> + +<pre class="brush: html notranslate"><p>A simple example of the live sample system in action.</p> +<div class="box"> + <div id="item">Hello world! Welcome to MDN</div> +</div> +</pre> + +<h3 id="CSS" name="CSS">CSS</h3> + +<p>CSS コードは、ボックスとその内部のテキストのスタイルを設定します。</p> + +<pre class="brush: css notranslate">.box { + width: 200px; + height: 100 px; + border-radius: 6px; + background-color: #ffaabb; +} + +#item { + width: 100%; + font-weight: bold; + text-align: center; + font-size: 2em; +} +</pre> + +<h3 id="JavaScript" name="JavaScript">JavaScript</h3> + +<p>このコードは非常に簡単です。クリックすると警告が表示されるテキスト「Hello world!」にイベントハンドラーをアタッチするだけです。</p> + +<pre class="brush: js notranslate">var el = document.getElementById('item'); +el.onclick = function() { + alert('Owww, stop poking me!'); +} +</pre> + +<h3 id="結果">結果</h3> + +<p>下記は <code>\{{EmbedLiveSample('Live_sample_demo')}}</code> を通じて、上のコードブロックを実行した結果です。<br> + <br> + {{EmbedLiveSample('Live_sample_demo')}}</p> + +<p>下記は <code>\{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}</code> を通じて、これらのコードブロックを経由して呼び出される結果のリンクです。</p> + +<p>{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}</p> + +<h2 id="Conventions_regarding_live_samples" name="Conventions_regarding_live_samples"><a id="conventions" name="conventions">ライブサンプルに関する取り決め</a></h2> + +<dl> + <dt>コードブロックの順序</dt> + <dd>ライブサンプルを追加する場合、コードブロックは最初のものがこのサンプルのメイン言語に対応するようにソートする必要があります。たとえば、HTML リファレンスのライブサンプルを追加する場合、最初のブロックは HTML でなければならず、CSS リファレンスのライブサンプルを追加するときは CSS でなければなりません。</dd> + <dt>見出しの名前付け</dt> + <dd>曖昧さがない場合 (例: サンプルが「Examples」セクションの下にある場合)、見出しは対応する言語の唯一の名前である HTML、CSS、JavaScript、SVG など (上記参照) で直接的に表します。「HTML コンテンツ」や「JavaScript コンテンツ」のような見出しは使用しないでください。しかし、そのような短い見出しがコンテンツを不明瞭にする場合、より思慮深いタイトルを使用することができます。</dd> + <dt>「Result」ブロックを使用する</dt> + <dd>異なるコードブロックの後、<code>EmbedLiveSample</code> マクロを使用する直前に、「Result」ブロックを使用してください (上記参照)。このようにして、この例の意味は、読者とページを解析するツール (スクリーンリーダー、ウェブクローラーなど) の両方にとってより明確になります。</dd> +</dl> diff --git a/files/ja/mdn/structures/live_samples/simple_live_sample_demo/index.html b/files/ja/mdn/structures/live_samples/simple_live_sample_demo/index.html new file mode 100644 index 0000000000..9e550d81ac --- /dev/null +++ b/files/ja/mdn/structures/live_samples/simple_live_sample_demo/index.html @@ -0,0 +1,37 @@ +--- +title: ライブコードサンプルの簡単なデモ +slug: MDN/Structures/Live_samples/Simple_live_sample_demo +tags: + - MDN Meta + - Structures + - 例 +translation_of: MDN/Structures/Live_samples/Simple_live_sample_demo +--- +<div>{{MDNSidebar}}</div> + +<h2 id="The_example" name="The_example">例</h2> + +<p id="Simple_example_of_a_live_demo">これは、MDN でライブデモを行う方法を示す非常に簡単な例です。詳細については、<a href="/ja/docs/MDN/Contribute/Structures/Live_samples">ライブサンプル</a>を参照してください。</p> + +<pre class="brush: html notranslate"><form> + <label>Try me<input type="text" name="name"></label> + <input type="submit" value="go"> +</form></pre> + +<pre class="brush: css notranslate">form { + border-radius: 10px; + background: powderblue; +}</pre> + +<pre class="brush: js notranslate">var f = document.querySelector('form'); + +f.addEventListener('submit', function(ev) { + ev.preventDefault(); + document.querySelectorAll('input')[1].value = 'sending'; +}, false);</pre> + +<p>{{ EmbedLiveSample('The_example', '', '', '') }}</p> + +<div class="blockIndicator note"> +<p>注: ローカライズしたページでは、最初の引数の値は、サンプルを含む見出しの ID と同じにしてください．</p> +</div> diff --git a/files/ja/mdn/structures/macros/commonly-used_macros/creating_templates_for_multi-languages/index.html b/files/ja/mdn/structures/macros/commonly-used_macros/creating_templates_for_multi-languages/index.html new file mode 100644 index 0000000000..a22ce9c70e --- /dev/null +++ b/files/ja/mdn/structures/macros/commonly-used_macros/creating_templates_for_multi-languages/index.html @@ -0,0 +1,12 @@ +--- +title: creating templates for multi-languages +slug: >- + MDN/Structures/Macros/Commonly-used_macros/creating_templates_for_multi-languages +--- +<div>{{MDNSidebar}}</div> +<div class="note"><strong>註：</strong> このページは執筆中です。</div> +<h2 id="執筆用memo">執筆用memo</h2> +<ul> <li>span 要素を使って言語版毎にテンプレートを用意するタイプの「ページ・プロパティ」は「なし（デフォルト）」にする。「English」などにするとテンプレートが英語版とその言語版とで二重に表示される現象が起きる。</li> +</ul> +<h2 id="テンプレートの_2_つのタイプ">テンプレートの 2 つのタイプ</h2> +<h2 id="page.langage_を使わない">page.langage を使わない</h2> diff --git a/files/ja/mdn/structures/macros/commonly-used_macros/index.html b/files/ja/mdn/structures/macros/commonly-used_macros/index.html new file mode 100644 index 0000000000..f7cc685313 --- /dev/null +++ b/files/ja/mdn/structures/macros/commonly-used_macros/index.html @@ -0,0 +1,210 @@ +--- +title: よく使われるマクロ +slug: MDN/Structures/Macros/Commonly-used_macros +tags: + - CSS + - Macros + - Reference + - Structures +translation_of: MDN/Structures/Macros/Commonly-used_macros +--- +<p>{{MDNSidebar}}</p> + +<p><span class="seoSummary">このページには MDN で使うために作られた汎用のマクロがたくさん掲載されています。これらのマクロの使い方については、<a href="/ja/docs/MDN/Contribute/Structures/Macros"> マクロの使い方</a> と <a href="/ja/docs/MDN/Contribute/Editor/Links#Using_link_macros">リンクを生成するマクロ</a> を見てください。</span> <a href="/ja/docs/MDN/Contribute/Structures/Macros/Other">その他のマクロ</a> には、めったに使われないマクロ、特殊な文脈でのみ使われるマクロ、使用が推奨されないマクロについての情報が書かれています。また、<a href="/en-US/dashboards/macros">MDNで使用できるマクロの完全な一覧</a>もあります。</p> + +<p><a href="/ja/docs/MDN/Contribute/Guidelines/CSS_style_guide">CSS スタイルガイド</a>も見てください。</p> + +<h2 id="Linking" name="Linking">リンク</h2> + +<h3 id="Creating_a_single_hyperlink" name="Creating_a_single_hyperlink">単一のハイパーリンクを作成する</h3> + +<p id="To_another_MDN_page_or_its_section_(anch_SectionOnPage_manch_Link_LinkItem_LinkItemDL)">一般的に、単なるリンクを作成するためにマクロを使う必要はありません。エディターインターフェイスにある <strong>リンク</strong> ボタンを使えば、リンクを作成できます。</p> + +<ul> + <li>{{TemplateLink("Glossary")}} マクロは MDN <a href="/ja/docs/Glossary">用語集</a>の中の指定した用語のエントリへのリンクを作成するのに使います。このマクロは、1つの必須の引数または2つの任意の引数を受け付けます。 + + <p>例:</p> + + <ol> + <li>用語の名前 (例えば "HTML")</li> + <li>用語の名前の代わりに記事内に表示するテキスト (これはあまり使用するべきではありません)。 {{Optional_Inline}}</li> + <li>この引数が指定されており 0 以外である場合、用語集へのリンクに使われるカスタムスタイルが適用されません。{{Optional_Inline}}</li> + </ol> + + <ul> + <li><code>\{{Glossary("HTML")}}</code> の表示は {{Glossary("HTML")}} となり、</li> + <li><code>\{{Glossary("CSS", "カスケーディングスタイルシート")}}</code> の表示は {{Glossary("CSS", "カスケーディングスタイルシート")}} となり、</li> + <li><code>\{{Glossary("HTML", "", 1)}}</code> の表示は {{Glossary("HTML", "", 1)}} となります。</li> + </ul> + </li> + <li>{{TemplateLink("anch")}} - ページ内の節へのリンクを生成 + <ul> + <li><code>\{{anch("Linking to pages in references")}}</code></li> + <li> + <p>デモ: {{anch("Linking to pages in references")}}</p> + </li> + </ul> + </li> +</ul> + +<h3 id="Linking_to_pages_in_references" name="Linking_to_pages_in_references">リファレンス内のページへのリンク</h3> + +<p>いろいろなマクロがあり、MDN の指定したリファレンスエリア内のページへのリンクを作成することができます。</p> + +<ul> + <li>{{TemplateLink("cssxref")}} は、<a href="/ja/docs/Web/CSS/Reference">CSS リファレンス</a>のページにリンクします。<br> + 例: <code>\{{CSSxRef("cursor")}}</code> の結果は {{CSSxRef("cursor")}} になります</li> + <li>{{TemplateLink("domxref")}} は DOM リファレンス内のページにリンクします。最後にカッコを入れると、関数名のようにリンクが表示されます。たとえば、<code>\{{DOMxRef("document.getElementsByName()")}}</code> は {{DOMxRef("document.getElementsByName()")}} になります。<code>\{{DOMxRef("Node")}}</code> は {{DOMxRef("Node")}} になります</li> + <li>{{TemplateLink("event")}} は DOM イベントリファレンスのページにリンクします。たとえば、<code>\{{Event("change")}}</code> は {{Event("change")}} になります</li> + <li>{{TemplateLink("HTMLElement")}} は HTML リファレンスの HTML 要素にリンクします</li> + <li>{{TemplateLink("htmlattrxref")}} は HTML 属性にリンクします。属性のみを指定する場合はグローバル属性の、属性名と要素名を指定する場合は特定の要素に関連付けられた属性の説明にリンクします。たとえば、<code>\{{HTMLAttrxRef("lang")}}</code> は {{HTMLAttrxRef("lang")}} のリンクを生成します。<code>\{{HTMLAttrxRef("type","input")}}</code> は {{htmlattrxref("type","input")}} のリンクを生成します。</li> + <li>{{TemplateLink("jsxref")}} は <a href="/ja/docs/Web/JavaScript/Reference">JavaScript リファレンス</a>のページにリンクします。</li> + <li>{{TemplateLink("SVGAttr")}} は特定の SVG 属性にリンクします。たとえば、<code>\{{SVGAttr("d")}}</code> は {{SVGAttr("d")}} のリンクを生成します。</li> + <li>{{TemplateLink("SVGElement")}} は SVG リファレンスの SVG 要素にリンクします。</li> + <li>{{TemplateLink("HTTPHeader")}} は <a href="/ja/docs/Web/HTTP/Headers">HTTP ヘッダー</a>にリンクします。</li> + <li>{{TemplateLink("HTTPMethod")}} は <a href="/ja/docs/Web/HTTP/Methods">HTTP リクエストメソッド</a>にリンクします。</li> + <li>{{TemplateLink("HTTPStatus")}} は <a href="/ja/docs/Web/HTTP/Status">HTTP レスポンスステータスコード</a>にリンクします。</li> +</ul> + +<h3 id="Linking_to_bugs" name="Linking_to_bugs">バグへのリンク</h3> + +<ul> + <li>バグ + <ul> + <li>{{TemplateLink("bug")}} を使うと、 bugzilla.mozilla.org に登録されているバグへのリンクを簡単に作ることができます。文法は <code>\{{Bug(123456)}}</code> です。 {{Bug(123456)}} のようなリンクになります。</li> + <li>{{TemplateLink("WebkitBug")}} は WebKit バグのデータベースへのリンクを挿入します。例えば <code>\{{WebkitBug(31277)}}</code> は {WebkitBug(31277)}} のようになります。</li> + </ul> + </li> +</ul> + +<h3 id="Navigation_aids_for_multi-page_guides" name="Navigation_aids_for_multi-page_guides">複数のページからなるガイドのためのナビゲーション補助</h3> + +<p>{{TemplateLink("Previous")}}、{{TemplateLink("Next")}}、{{TemplateLink("PreviousNext")}} は、一連の記事の中でのナビゲーションコントロールを提供します。一方向用のテンプレートでは、 前の または 次の 記事の Wiki 位置を指す1つの引数が必要です。{{TemplateLink("PreviousNext")}} については、前の記事、次の記事を指す 2つの引数を取ります。最初の引数が前の記事を指し、2番めの引数が次の記事を指します。</p> + +<h2 id="Code_samples" name="Code_samples">コードのサンプル</h2> + +<h3 id="Live_samples" name="Live_samples">Live サンプル</h3> + +<ul> + <li>{{TemplateLink("EmbedLiveSample")}} はコードサンプルの出力をページに埋め込むのに使います。解説は <a href="/ja/docs/MDN/Contribute/Structures/Live_samples">Live サンプル</a>のページにあります</li> + <li>{{TemplateLink("LiveSampleLink")}} はコードサンプルの出力を含むページへのリンクを作成します。解説は <a href="/ja/docs/MDN/Contribute/Structures/Live_samples">Live サンプル</a>のページにあります</li> +</ul> + +<h2 id="Sidebar_generation" name="Sidebar_generation">サイドバーの生成</h2> + +<p>ほぼすべての大きなページの集まりについて、雛形があります。典型的には、リファレンス、ガイド、チュートリアルでメインページに戻るためのリンク (パンくずリストではできないことがある) を提供し、記事を適切なカテゴリに配置します。</p> + +<ul> + <li>{{TemplateLink("CSSRef")}} は CSS リファレンスページのサイドバーを生成します</li> + <li>{{TemplateLink("HTMLRef")}} は HTML リファレンスページのサイドバーを生成します</li> + <li>{{TemplateLink("APIRef")}} は Web API リファレンスページのサイドバーを生成します</li> +</ul> + +<h2 id="General-purpose_formatting" name="General-purpose_formatting">汎用の書式</h2> + +<h3 id="Inline_indicators_for_API_documentation" name="Inline_indicators_for_API_documentation">API 文書のためのインラインインジケーター</h3> + +<p>{{TemplateLink("optional_inline")}} と {{TemplateLink("ReadOnlyInline")}} は API 文書の中で通常、オブジェクトのプロパティまたは関数の引数のリストを記述するのに使われます。</p> + +<p>用法: <code>\{{optional_inline()}}</code> または <code>\{{ReadOnlyInline}}</code>. 例:</p> + +<dl> + <dt><code>isCustomObject</code>{{ReadOnlyInline}}</dt> + <dd><code>true</code> の場合、オブジェクトはカスタムオブジェクトであることを示します。</dd> + <dt><code>parameterX</code>{{Optional_Inline}}</dt> + <dd>ごにょごにょごにょ...</dd> +</dl> + +<h2 id="Status_and_compatibility_indicators" name="Status_and_compatibility_indicators">状態と互換性についての表示</h2> + +<h3 id="Inline_indicators_with_no_additional_parameters" name="Inline_indicators_with_no_additional_parameters">インラインインジケーター (追加引数なし)</h3> + +<h4 id="Non-standard" name="Non-standard">標準外のもの</h4> + +<p>{{TemplateLink("non-standard_inline")}} は、その API が標準化されておらず、また標準化の予定もないことを示すインラインマークを付けます。</p> + +<h5 id="Syntax" name="Syntax">構文</h5> + +<p><code>\{{Non-standard_Inline}}</code></p> + +<h5 id="Examples" name="Examples">例</h5> + +<ul> + <li>アイコン: {{Non-standard_Inline}}</li> +</ul> + +<h4 id="Experimental" name="Experimental">実験的なもの</h4> + +<p>{{TemplateLink("experimental_inline")}} は、その API が広く実装されておらず、また将来変更される可能性があることを示すインラインマークを付けます。</p> + +<h5 id="Syntax_2" name="Syntax_2">構文</h5> + +<p><code>\{{Experimental_Inline}}</code></p> + +<h5 id="Examples_2" name="Examples_2">例</h5> + +<ul> + <li>アイコン: {{Experimental_Inline}}</li> +</ul> + +<h3 id="Inline_indicators_that_support_specifying_the_technology" name="Inline_indicators_that_support_specifying_the_technology">特定の技術の対応状況を表すインラインインジケーター</h3> + +<p>これらのマクロにパラメータを指定する場合は、"html", "js", "css", "gecko",のうちの1つにバージョン番号を加えたものとなります。</p> + +<h4 id="Deprecated" name="Deprecated">非推奨のもの</h4> + +<p>{{TemplateLink("deprecated_inline")}} はインラインの非推奨(deprecated) マークを付け、その API が公式には非推奨であり、使用を控えるべきであることを示します。<strong>注:</strong> 非推奨 (deprecated) が意味するのは、その項目はもう使用されるべきではないが、まだ機能するものであることです。もう機能しないものを示す用語としては、廃止 (obsolete) を使ってください。</p> + +<p>ブラウザー特有の記述 (HTML, API, JS, CSS, …) では、引数を使用しないでください。</p> + +<h5 id="Syntax_3" name="Syntax_3">構文</h5> + +<p><code>\{{Deprecated_Inline}}</code> または <code>\{{Deprecated_Inline("gecko5")}}</code></p> + +<h5 id="Examples_3" name="Examples_3">例</h5> + +<ul> + <li>アイコン: {{Deprecated_Inline}}</li> + <li>バッジ: {{Deprecated_Inline("gecko5")}}</li> +</ul> + +<h4 id="Obsolete" name="Obsolete">廃止</h4> + +<p>{{TemplateLink("obsolete_inline")}} はインラインの廃止 (obsolete) マークを付け、例えばその関数、メソッド、またはプロパティ等を使用してはいけないことを示します。</p> + +<p>ブラウザー特有の記述 (HTML, API, JS, CSS, …) では、引数を使用しないでください。</p> + +<h5 id="Syntax_4" name="Syntax_4">構文</h5> + +<p><code>\{{Obsolete_Inline}}</code> または <code>\{{Obsolete_Inline("js1.8.5")}}</code></p> + +<h5 id="Examples_4" name="Examples_4">例</h5> + +<ul> + <li>アイコン: {{Obsolete_Inline}}</li> + <li>バッジ: {{Obsolete_Inline("js1.8.5")}}</li> +</ul> + +<h3 id="Template_badges" name="Template_badges">テンプレートバッジ</h3> + +<p>これらのマクロはほとんど <a href="/ja/docs/Web/API">WebAPI</a> ページで使われます。{{anch("Creating new badges")}} に新しいバッジを作成するための情報があります。</p> + +<h3 id="Page_or_section_header_indicators" name="Page_or_section_header_indicators">ページまたはセクションのヘッダーを示すインジケーター</h3> + +<p>これらのテンプレートが示すのは、上記の対応するインラインマークと同じものです。テンプレートはリファレンスページのメインページタイトルの (または、パンくずリストがあるならばその) 直下に置きます。ページ内のセクションをマークアップすることもできます。</p> + +<ul> + <li>{{TemplateLink("non-standard_header")}}: <code>\{{Non-standard_Header}}</code> {{Non-standard_Header}}</li> + <li><a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">実験的な機能</a>を説明するページでは {{TemplateLink("SeeCompatTable")}} を使用する必要があります。例: <code>\{{SeeCompatTable}}</code> {{SeeCompatTable}}</li> + <li>{{TemplateLink("deprecated_header")}}: <code>\{{Deprecated_Header}}</code> {{Deprecated_Header}}</li> + <li>{{TemplateLink("deprecated_header")}} with parameter: <code>\{{Deprecated_Header("gecko5")}}</code> {{Deprecated_Header("gecko5")}} ブラウザーに依存しない領域 (HTML、API、JS、CSS など) でこの引数を使用しないでください</li> + <li>{{TemplateLink("obsolete_header")}}: <code>\{{Obsolete_Header}}</code> {{Obsolete_Header}}</li> + <li>{{TemplateLink("obsolete_header")}} with parameter: <code>\{{Obsolete_Header("gecko30")}}</code> {{Obsolete_Header("gecko30")}} ブラウザーに依存しない領域 (HTML、API、JS、CSS など) でこの引数を使用しないでください</li> + <li>{{TemplateLink("secureContext_header")}}: <code>\{{SecureContext_Header}}</code> {{SecureContext_Header}}</li> +</ul> + +<h3 id="Indicating_that_a_feature_is_available_in_web_workers" name="Indicating_that_a_feature_is_available_in_web_workers">ウェブワーカーで使用できる機能であることを示す</h3> + +<p>{{TemplateLink("AvailableInWorkers")}} マクロは、その機能が<a href="/ja/docs/Web/API/Web_Workers_API">ウェブワーカー</a>のコンテキストで有効であることを示すためのローカライズされた注記ボックスを挿入するのに使われます。</p> + +<p>{{AvailableInWorkers}}</p> diff --git a/files/ja/mdn/structures/macros/index.html b/files/ja/mdn/structures/macros/index.html new file mode 100644 index 0000000000..40cddcf091 --- /dev/null +++ b/files/ja/mdn/structures/macros/index.html @@ -0,0 +1,46 @@ +--- +title: マクロ +slug: MDN/Structures/Macros +tags: + - Guide + - Kuma + - KumaScript + - MDN Meta + - Structures +translation_of: MDN/Structures/Macros +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary">MDN が動作している <a href="/ja/docs/MDN/Kuma" title="/en-US/docs/Project:MDN/Kuma">Kuma</a> プラットフォームは、幅広い作業の自動化を可能にする強力なマクロシステムである <a href="/ja/docs/MDN/Contribute/Tools/KumaScript" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript</a> を提供しています。この記事は MDN のマクロを記事中で呼び出す方法について情報を提供します。</span></p> + +<p><a href="/ja/docs/MDN/Contribute/Tools/KumaScript" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript ガイド</a>では MDN 上でマクロを利用する方法について詳細な情報を提供しているので、このセクションではむしろ全体の簡潔なまとめをします。</p> + +<h2 id="How_macros_are_implemented" name="How_macros_are_implemented">マクロはどのように実装されているか</h2> + +<p>MDN 上で動作するマクロは、サーバーで実行される <a href="/ja/docs/Web/JavaScript" title="/ja/docs/Web/JavaScript">JavaScript</a> コードを使用して実装され、 <a href="https://nodejs.org/en/" title="https://nodejs.org/en/">Node.js</a> によって解釈されます。そのうえ数多くのライブラリを用意しており、 Wiki 風のサービスを提供します。また、 Wiki プラットフォームとそのコンテンツを、マクロと連携させる機能を提供します。もっと詳細に興味があるのであれば、 <a href="/ja/docs/MDN/Contribute/Tools/KumaScript" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript ガイド</a>を参照して下さい。</p> + +<h2 id="Using_a_macro_in_content" name="Using_a_macro_in_content">コンテンツでのマクロの利用</h2> + +<p>実際にマクロを使うには、マクロの呼び出しを二重の中括弧で囲むだけです。引数があれば括弧で囲みます。つまり以下のようになります。</p> + +<pre class="notranslate">\{{macroname(parameter-list)}}</pre> + +<p>マクロ呼び出しに関するいくつかのポイント</p> + +<ul> + <li>マクロ名は大文字と小文字を区別します。それに関するエラーはよくあるので幾つかののパターンがあります。例えば、マクロ名に大文字があるのに全て小文字で入力しているかもしれません。また、小文字から始まる所を大文字にしてしまっているのかもしれません。</li> + <li>引数はコンマで区切ります。</li> + <li>引数が無ければ括弧は取ってしまって構いません。 <code>\{{macroname()}}</code> と <code>\{{macroname}}</code> はまったく同等です。</li> + <li>数値の引数は引用符で囲む必要がありませんが、囲んでも構いません（ただし、複数のピリオドを含むバージョン番号を渡す場合などは、引用符で囲む必要があります）。</li> + <li>エラーが発生した場合は、コードを丁寧に読み返して下さい。何が問題なのかそれでも特定できなかった場合には、 <a href="/ja/docs/MDN/Kuma/Troubleshooting_KumaScript_errors">KumaScript エラーのトラブルシューティング</a>を参照して下さい。</li> +</ul> + +<p>マクロは高度にキャッシュ化されています。どの入力値についても（引数や、マクロを動作させる URL といった環境変数のいずれでも）、その結果は記憶され再利用されます。つまり、入力が変化した時だけマクロは実行されます。</p> + +<div class="note"> +<p><strong>注:</strong> ブラウザーでページを強制的に再読み込み（つまり、 Shift を押しながら再読み込み）すると、そのページのマクロを再評価することが出来ます。</p> +</div> + +<p>マクロは大きなテキストブロックを挿入したり、 MDN の他記事からの内容で置き換えたりするようなシンプルなこともできますし、サイトを走査して目次をまるごと作り上げたり、出力のスタイリングをしたり、リンクを張ったりといった複雑なこともできます。</p> + +<p>最もよく使われるマクロについて<a href="/ja/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros" title="/ja/docs/Project:MDN/Contributing/Custom_macros">良く使われるマクロ</a>のページで学習することが出来ます。また、<a href="https://developer.mozilla.org/ja/docs/templates" title="https://developer.mozilla.org/en-US/docs/templates">マクロの完全なリスト</a>もあります。そして多くのマクロには最上部のコメントとして、ソースに説明が組み込まれています。</p> + +<p>{{EditorGuideQuicklinks}}</p> diff --git a/files/ja/mdn/structures/page_types/api_event_subpage_template/index.html b/files/ja/mdn/structures/page_types/api_event_subpage_template/index.html new file mode 100644 index 0000000000..d211a4606f --- /dev/null +++ b/files/ja/mdn/structures/page_types/api_event_subpage_template/index.html @@ -0,0 +1,121 @@ +--- +title: API イベントサブページのテンプレート +slug: MDN/Structures/Page_types/API_event_subpage_template +tags: + - API + - Event + - Event subpage + - Template + - reference page +translation_of: MDN/Structures/Page_types/API_event_subpage_template +--- +<div>{{MDNSidebar}}</div> + +<div class="note"> +<h2 id="Remove_before_publishing" name="Remove_before_publishing">公開前に削除してください</h2> + +<h3 id="Title_and_slug" name="Title_and_slug">タイトルとスラッグ</h3> + +<p>API イベントサブページの<em>タイトル</em>は、 <em>所属するインターフェイス名 + ": " + イベント名 + " イベント"</em>としてください。例えば、 <a href="/ja/docs/Web/API/Window/vrdisplaypresentchange_event">vrdisplaypresentchange</a> イベントが <a href="/ja/docs/Web/API/Window">Window</a> インターフェイスに所属している場合は、<em>タイトル</em>は <em>Window: vrdisplaypresentchange イベント</em>となります。</p> + +<p><em>スラッグ</em> (URL の最後の部分) は、<em>イベント名 + "_event"</em> としてください。したがって、 <code>vrdisplaypresentchange</code> のスラッグは <em>vrdisplaypresentchange_event</em> です。</p> + +<h3 id="Top_macros" name="Top_macros">先頭で使用するマクロ</h3> + +<p>既定では、テンプレートの先頭に5つのマクロ呼び出しがあります。以下のアドバイスに従って、更新や削除をしてください。</p> + +<ul> + <li>\{{draft()}} — this generates a <strong>Draft</strong> banner that indicates that the page is not yet complete, and should only be removed when the first draft of the page is completely finished. After it is ready to be published, you can remove this.</li> + <li>\{{SeeCompatTable}} — this generates a <strong>This is an experimental technology</strong> banner that indicates the technology is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">experimental</a>). If the technology you are documenting is not experimental, you can remove this. If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the <a href="/ja/docs/Mozilla/Firefox/Experimental_features">Experimental features in Firefox</a> page.</li> + <li>\{{securecontext_header}} — this generates a <strong>Secure context</strong> banner that indicates the technology is only available in a <a href="/ja/docs/Web/Security/Secure_Contexts">secure context</a>. If it isn't, then you can remove the macro call. If it is, then you should also fill in an entry for it in the <a href="/ja/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts">Features restricted to secure contexts</a> page.</li> + <li>\{{deprecated_header}} — this generates a <strong>Deprecated</strong> banner that indicates the technology is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">deprecated</a>. If it isn't, then you can remove the macro call.</li> + <li> + <div>\{{APIRef("<em>GroupDataName</em>")}} — this generates the left hand reference sidebar showing quick reference links related to the current page. For example, every page in the <a href="/ja/docs/Web/API/WebVR_API">WebVR API</a> has the same sidebar, which points to the other pages in the API. To generate the correct sidebar for your API, you need to add a GroupData entry to our KumaScript GitHub repo, and include the entry's name inside the macro call in place of <em>GroupDataName</em>. See our <a href="/ja/docs/MDN/Contribute/Structures/API_references/API_reference_sidebars">API reference sidebars</a> guide for information on how to do this.</div> + </li> +</ul> + +<h3 id="Tags" name="Tags">タグ</h3> + +<p>In an API event subpage, you need to include the following tags (see the <em>Tags</em> section at the bottom of the editor UI): <strong>API</strong>, <strong>Reference</strong>, <strong>Event</strong>, <em>the name of the API</em> (e.g. <strong>WebVR</strong>), the name of the parent interface (e.g. <strong>Window</strong>), <strong>Experimental</strong> (if the technology is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">experimental</a>), <strong>Secure context</strong> (if it is available in a secure context only), and <strong>Deprecated</strong> (if it is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">deprecated</a>).</p> + +<p>Optionally, you can elect to include some other tags that effective represent terms people might search for when looking for information on that technology. For example on WebVR interface pages we include <strong>VR</strong> and <strong>Virtual reality</strong>.</p> + +<h3 id="Browser_compatibility" name="Browser_compatibility">ブラウザーの互換性</h3> + +<p>To fill in the browser compat data, you first need to fill in an entry for the API into our <a href="https://github.com/mdn/browser-compat-data">Browser compat data repo</a> — see our <a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables#The_new_way_The_browser_compat_data_repo_and_dynamic_tables">guide on how to do this</a>.</p> + +<p>Once that is done, you can show the compat data for the method with a \{{Compat()}} macro call.</p> +</div> + +<div>{{draft}}{{SeeCompatTable}}{{securecontext_header}}{{deprecated_header}}{{APIRef("GroupDataName")}}</div> + +<p class="summary">The summary paragraph — start by naming the event, saying what interface it is part of, and saying what it does. This should ideally be 1 or 2 short sentences. You could copy most of this from the property's summary on the corresponding API reference page.</p> + +<table class="properties"> + <tbody> + <tr> + <th scope="row">バブリング</th> + <td>あり/なし</td> + </tr> + <tr> + <th scope="row">キャンセル</th> + <td>可/不可</td> + </tr> + <tr> + <th scope="row">インターフェイス</th> + <td>イベントが発生する親インターフェイスへのリンクです。例えば {{domxref("VRDisplayEvent")}}</td> + </tr> + <tr> + <th scope="row">イベントハンドラープロパティ</th> + <td>イベントに対応するイベントハンドラープロパティへのリンクです。例えば {{domxref("Window/onvrdisplaypresentchange", "onvrdisplaypresentchange")}}</td> + </tr> + </tbody> +</table> + +<h2 id="Examples" name="Examples">例</h2> + +<p>Fill in a simple example that nicely shows a typical usage of the event, then perhaps some more complex examples (see our guide on how to add <a href="/ja/docs/MDN/Contribute/Structures/Code_examples">code examples</a> for more information).</p> + +<pre class="brush: js notranslate">my code block</pre> + +<p>And/or include a list of links to useful code samples that live elsewhere:</p> + +<ul> + <li>x</li> + <li>y</li> + <li>z</li> +</ul> + +<h2 id="Specifications" name="Specifications">仕様書</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">仕様書</th> + <th scope="col">状態</th> + <th scope="col">備考</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName("NameOfSpecificationfromSpecName","#document-fragment-linking-directly-to-event-definition","NameOfTheEvent")}}</td> + <td>{{Spec2('NameOfSpecificationFromSpec2')}}</td> + <td>初回定義</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility_2" name="Browser_compatibility_2">ブラウザーの互換性</h2> + +<div class="hidden">このページの互換性一覧表は構造化データから生成されています。データに協力していただけるのであれば、 <a class="external" href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> をチェックアウトしてプルリクエストを送信してください。</div> + +<p>{{Compat("path.to.feature.NameOfTheEvent_event")}}</p> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li>Include list of</li> + <li>other links related to</li> + <li>this API that might</li> + <li>be useful</li> +</ul> diff --git a/files/ja/mdn/structures/page_types/api_method_subpage_template/index.html b/files/ja/mdn/structures/page_types/api_method_subpage_template/index.html new file mode 100644 index 0000000000..f418b66752 --- /dev/null +++ b/files/ja/mdn/structures/page_types/api_method_subpage_template/index.html @@ -0,0 +1,124 @@ +--- +title: API メソッドサブページのテンプレート +slug: MDN/Structures/Page_types/API_method_subpage_template +tags: + - API + - Method + - Template + - method subpage + - reference page +translation_of: MDN/Structures/Page_types/API_method_subpage_template +--- +<div>{{MDNSidebar}}</div> + +<div class="blockIndicator note"> +<h2 id="Remove_before_publishing" name="Remove_before_publishing">公開前に削除してください</h2> + +<h3 id="Title_and_slug" name="Title_and_slug">タイトルとスラッグ</h3> + +<p>API メソッドサブページの<em>タイトル</em>は、<em>インターフェイス名</em> + "." + <em>メソッド名</em> + "()" としてください。例えば、 <a href="/ja/docs/Web/API/IDBIndex">IDBIndex</a> インターフェイスの <a href="/ja/docs/Web/API/IDBIndex/count">count()</a> メソッドの<em>タイトル</em> は "IDBIndex.count()" です。</p> + +<p><em>スラッグ</em> (URL の最後の部分) は、<em>メソッド名</em>を括弧なして記述してください。ですから <code>count()</code> のスラッグは "count" です。</p> + +<h3 id="Top_macros" name="Top_macros">先頭で使用するマクロ</h3> + +<p>既定では、テンプレートの先頭に5つのマクロ呼び出しがあります。以下のアドバイスに従って、更新や削除をしてください。</p> + +<ul> + <li>\{{APIRef("<em>GroupDataName</em>")}} — this generates the left hand reference sidebar showing quick reference links related to the current page. For example, every page in the <a href="/ja/docs/Web/API/WebVR_API">WebVR API</a> has the same sidebar, which points to the other pages in the API. To generate the correct sidebar for your API, you need to add a GroupData entry to our KumaScript GitHub repo, and include the entry's name inside the macro call in place of <em>GroupDataName</em>. See our <a href="/ja/docs/MDN/Contribute/Structures/API_references/API_reference_sidebars">API reference sidebars</a> guide for information on how to do this.</li> + <li>\{{Draft}} — this generates a <strong>Draft</strong> banner that indicates that the page is not yet complete, and should only be removed when the first draft of the page is completely finished. After it is ready to be published, you can remove this.</li> + <li>\{{SeeCompatTable}} — this generates a <strong>This is an experimental technology</strong> banner that indicates the technology is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">experimental</a>). If the technology you are documenting is not experimental, you can remove this. If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the <a href="/ja/docs/Mozilla/Firefox/Experimental_features">Experimental features in Firefox</a> page.</li> + <li>\{{SecureContext_Header}} — this generates a <strong>Secure context</strong> banner that indicates the technology is only available in a <a href="/ja/docs/Web/Security/Secure_Contexts">secure context</a>. If it isn't, then you can remove the macro call. If it is, then you should also fill in an entry for it in the <a href="/ja/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts">Features restricted to secure contexts</a> page.</li> + <li>\{{Deprecated_Header}} — this generates a <strong>Deprecated</strong> banner that indicates the technology is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">deprecated</a>. If it isn't, then you can remove the macro call.</li> +</ul> + +<h3 id="Tags" name="Tags">タグ</h3> + +<p>In an API method subpage, you need to include the following tags (see the <em>Tags</em> section at the bottom of the editor UI): <strong>API</strong>, <strong>Reference</strong>, <strong>Method</strong>, <em>the name of the API</em> (e.g. <strong>WebVR</strong>), the name of the parent interface (e.g. <strong>IDBIndex</strong>), the name of the method (e.g. <strong>count()</strong>), <strong>Experimental</strong> (if the technology is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">experimental</a>), <strong>Secure context</strong> (if it is available in a secure context only), and <strong>Deprecated</strong> (if it is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">deprecated</a>).</p> + +<p>Optionally, you can elect to include some other tags that effective represent terms people might search for when looking for information on that technology. For example on WebVR interface pages we include <strong>VR</strong> and <strong>Virtual reality</strong>.</p> + +<h3 id="Browser_compatibility" name="Browser_compatibility">ブラウザーの互換性</h3> + +<p>To fill in the browser compat data, you first need to fill in an entry for the API into our <a href="https://github.com/mdn/browser-compat-data">Browser compat data repo</a> — see our <a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables#The_new_way_The_browser_compat_data_repo_and_dynamic_tables">guide on how to do this</a>.</p> + +<p>Once that is done, you can show the compat data for the method with a \{{Compat()}} macro call.</p> +</div> + +<p>{{APIRef("GroupDataName")}}{{Draft}}{{SeeCompatTable}}{{SecureContext_header}}{{Deprecated_Header}}</p> + +<p class="summary">The summary paragraph — start by naming the method, saying what interface it is part of, and saying what it does. This should ideally be 1 or 2 short sentences. You could copy most of this from the method's summary on the corresponding API reference page.</p> + +<h2 id="Syntax" name="Syntax">構文</h2> + +<pre class="syntaxbox notranslate">Fill in a syntax box, according to the guidance in our <a href="/ja/docs/MDN/Contribute/Structures/Syntax_sections">syntax sections</a> article.</pre> + +<h3 id="Parameters" name="Parameters">引数</h3> + +<dl> + <dt>parameter1{{Optional_Inline}}</dt> + <dd>Include a brief description of the parameter and what it does here. Include one term and definition for each parameter. If the parameter is not optional, remove the \{{optional_inline}} macro call.</dd> + <dt>parameter2</dt> + <dd>etc.</dd> +</dl> + +<h3 id="Return_value" name="Return_value">返値</h3> + +<p>Include a description of the method's return value, including data type and what it represents. If the method doesn't return anything, just put "Void".</p> + +<h3 id="Exceptions" name="Exceptions">例外</h3> + +<dl> + <dt>Exception1</dt> + <dd>Include a list of all the exceptions that the method can raise, along with descriptions of how that exception is raised. Include one term and definition for each exception.</dd> + <dt>Exception2</dt> + <dd>etc.</dd> +</dl> + +<h2 id="Examples" name="Examples">例</h2> + +<p>Fill in a simple example that nicely shows a typical usage of the method, then perhaps some more complex examples (see our guide on how to add <a href="/ja/docs/MDN/Contribute/Structures/Code_examples">code examples</a> for more information).</p> + +<pre class="brush: js notranslate">my code block</pre> + +<p>And/or include a list of links to useful code samples that live elsewhere:</p> + +<ul> + <li>x</li> + <li>y</li> + <li>z</li> +</ul> + +<h2 id="Specifications" name="Specifications">仕様書</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">仕様書</th> + <th scope="col">状態</th> + <th scope="col">備考</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName("NameOfSpecificationfromSpecName", "#document-fragment-linking-directly-to-method-definition", "NameOfTheMethod")}}</td> + <td>{{Spec2("NameOfSpecificationFromSpec2")}}</td> + <td>初回定義</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility_2" name="Browser_compatibility_2">ブラウザーの互換性</h2> + +<div class="hidden">このページの互換性一覧表は構造化データから生成されています。データに協力していただけるのであれば、 <a class="external" href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> をチェックアウトしてプルリクエストを送信してください。</div> + +<p>{{Compat("path.to.feature.NameOfTheMethod")}}</p> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li>Include list of</li> + <li>other links related to</li> + <li>this API that might</li> + <li>be useful</li> +</ul> diff --git a/files/ja/mdn/structures/page_types/api_property_subpage_template/index.html b/files/ja/mdn/structures/page_types/api_property_subpage_template/index.html new file mode 100644 index 0000000000..f24015fa8e --- /dev/null +++ b/files/ja/mdn/structures/page_types/api_property_subpage_template/index.html @@ -0,0 +1,107 @@ +--- +title: API property subpage template +slug: MDN/Structures/Page_types/API_property_subpage_template +tags: + - API + - Property + - Template + - property subpage + - reference page + - テンプレート +translation_of: MDN/Structures/Page_types/API_property_subpage_template +--- +<p>{{MDNSidebar}}</p> + +<div class="note"> +<h2 id="Remove_before_publishing" name="Remove_before_publishing">公開前に削除してください</h2> + +<h3 id="Title_and_slug" name="Title_and_slug">タイトルとスラッグ</h3> + +<p>API プロパティサブページの<em>タイトル</em>は、<em>インターフェイス名</em> + "." + <em>プロパティ名</em>としてください。例えば、 <a href="/ja/docs/Web/API/VRDisplay">VRDisplay</a> インターフェイスの <a href="/ja/docs/Web/API/VRDisplay/capabilities">capabilities</a> プロパティの<em>タイトル</em> は <em>VRDisplay.capabilities</em> です。</p> + +<p><em>スラッグ</em> (URL の最後の部分) は、<em>プロパティ名</em>を記述してください。ですから <code>capabilities</code> のスラッグは <em>capabilities</em> です。</p> + +<h3 id="Top_macros" name="Top_macros">先頭で使用するマクロ</h3> + +<p>既定では、テンプレートの先頭に5つのマクロ呼び出しがあります。以下のアドバイスに従って、更新や削除をしてください。</p> + +<ul> + <li>\{{APIRef("<em>グループデータ名</em>")}} — これは左端にあるサイドバーを生成し、現在のページに関連するクイックリファレンスのリンクを表示します。例えば、 <a href="/ja/docs/Web/API/WebVR_API">WebVR API</a> の中の各ページは同じサイドバーを持ち、この API 内の他のページを指します。 API で正しいサイドバーを生成するには、 KumaScript の GitHub リポジトリにグループデータの項目を追加し、マクロ呼び出しの中で<em>グループデータ名</em>のところに項目名を入れる必要があります。これを行う方法についてのガイドは <a href="/ja/docs/MDN/Contribute/Structures/API_references/API_reference_sidebars">API リファレンスサイドバー</a>を参照してください。</li> + <li>\{{Draft}} — this generates a <strong>Draft</strong> banner that indicates that the page is not yet complete, and should only be removed when the first draft of the page is completely finished. After it is ready to be published, you can remove this.</li> + <li>\{{SeeCompatTable}} — this generates a <strong>This is an experimental technology</strong> banner that indicates the technology is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">experimental</a>). If the technology you are documenting is not experimental, you can remove this. If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the <a href="/ja/docs/Mozilla/Firefox/Experimental_features">Experimental features in Firefox</a> page.</li> + <li>\{{SecureContext_Header}} — this generates a <strong>Secure context</strong> banner that indicates the technology is only available in a <a href="/ja/docs/Web/Security/Secure_Contexts">secure context</a>. If it isn't, then you can remove the macro call. If it is, then you should also fill in an entry for it in the <a href="/ja/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts">Features restricted to secure contexts</a> page.</li> + <li>\{{Deprecated_Header}} — this generates a <strong>Deprecated</strong> banner that indicates the technology is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">deprecated</a>. If it isn't, then you can remove the macro call.</li> +</ul> + +<h3 id="Tags" name="Tags">タグ</h3> + +<p>In an API method subpage, you need to include the following tags (see the <em>Tags</em> section at the bottom of the editor UI): <strong>API</strong>, <strong>Reference</strong>, <strong>Property</strong>, <em>the name of the API</em> (e.g. <strong>WebVR</strong>), the name of the parent interface (e.g. <strong>VRDisplay</strong>), the name of the method (e.g. <strong>capabilities</strong>), <strong>Experimental</strong> (if the technology is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">experimental</a>), <strong>Secure context</strong> (if it is available in a secure context only), and <strong>Deprecated</strong> (if it is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">deprecated</a>).</p> + +<p>Optionally, you can elect to include some other tags that effective represent terms people might search for when looking for information on that technology. For example on WebVR interface pages we include <strong>VR</strong> and <strong>Virtual reality</strong>.</p> + +<h3 id="Browser_compatibility" name="Browser_compatibility">ブラウザーの互換性</h3> + +<p>To fill in the browser compat data, you first need to fill in an entry for the API into our <a href="https://github.com/mdn/browser-compat-data">Browser compat data repo</a> — see our <a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables#The_new_way_The_browser_compat_data_repo_and_dynamic_tables">guide on how to do this</a>.</p> + +<p>Once that is done, you can show the compat data for the method with a \{{Compat()}} macro call.</p> +</div> + +<p>{{APIRef("GroupDataName")}}{{Draft}}{{SeeCompatTable}}{{SecureContext_Header}}{{Deprecated_Header}}</p> + +<p class="summary">The summary paragraph — start by naming the property, saying what interface it is part of, and saying what it does. This should ideally be 1 or 2 short sentences. You could copy most of this from the property's summary on the corresponding API reference page. Include whether it is read-only or not.</p> + +<h2 id="Syntax" name="Syntax">構文</h2> + +<pre class="syntaxbox notranslate">Fill in a syntax box, according to the guidance in our <a href="/ja/docs/MDN/Contribute/Structures/Syntax_sections">syntax sections</a> article.</pre> + +<h3 id="Value" name="Value">値</h3> + +<p>Include a description of the property's value, including data type and what it represents.</p> + +<h2 id="Examples" name="Examples">例</h2> + +<p>Fill in a simple example that nicely shows a typical usage of the property, then perhaps some more complex examples (see our guide on how to add <a href="/ja/docs/MDN/Contribute/Structures/Code_examples">code examples</a> for more information).</p> + +<pre class="brush: js; notranslate">my code block</pre> + +<p>And/or include a list of links to useful code samples that live elsewhere:</p> + +<ul> + <li>x</li> + <li>y</li> + <li>z</li> +</ul> + +<h2 id="Specifications" name="Specifications">仕様書</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">仕様書</th> + <th scope="col">状態</th> + <th scope="col">備考</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName("NameOfSpecification", "#document-fragment-linking-directly-to-property-definition", "NameOfTheProperty")}}</td> + <td>{{Spec2("NameOfSpecification")}}</td> + <td>初回定義</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility_2" name="Browser_compatibility_2">ブラウザーの互換性</h2> + +<div class="hidden">このページの互換性一覧表は構造化データから生成されています。データに協力していただけるのであれば、 <a class="external" href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> をチェックアウトしてプルリクエストを送信してください。</div> + +<p>{{Compat("path.to.feature.NameOfTheProperty")}}</p> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li>Include list of</li> + <li>other links related to</li> + <li>this API that might</li> + <li>be useful</li> +</ul> diff --git a/files/ja/mdn/structures/page_types/api_reference_page_template/index.html b/files/ja/mdn/structures/page_types/api_reference_page_template/index.html new file mode 100644 index 0000000000..e59690ef30 --- /dev/null +++ b/files/ja/mdn/structures/page_types/api_reference_page_template/index.html @@ -0,0 +1,148 @@ +--- +title: API reference page template +slug: MDN/Structures/Page_types/API_reference_page_template +tags: + - API + - Template + - reference page + - テンプレート +translation_of: MDN/Structures/Page_types/API_reference_page_template +--- +<p>{{MDNSidebar}}</p> + +<div class="blockIndicator note"> +<h2 id="Remove_before_publishing" name="Remove_before_publishing">公開前に削除してください</h2> + +<h3 id="Title_and_slug" name="Title_and_slug">タイトルとスラッグ</h3> + +<p>API リファレンスページでは、<em>そのページで説明しているインターフェイスの名前</em>を<em>タイトル</em>にしてください。例えば、 <a href="/ja/docs/Web/API/Request">Request</a> インターフェイスのページでは、<em>タイトル</em> を <em>Request</em> にしてください。</p> + +<p><em>スラッグ</em> (URL の最後の部分) も、<em>そのページで説明しているインターフェイスの名前</em>にしてください。したがって、 <code>Request</code> のスラッグは <em>Request</em> です。これはふつう、自動的に設定されます。</p> + +<h3 id="Top_macros" name="Top_macros">先頭で使用するマクロ</h3> + +<p>既定では、テンプレートの先頭に5つのマクロ呼び出しがあります。以下のアドバイスに従って、更新や削除をしてください。</p> + +<ul> + <li>\{{APIRef("<em>グループデータ名</em>")}} — これは左端にあるサイドバーを生成し、現在のページに関連するクイックリファレンスのリンクを表示します。例えば、 <a href="/ja/docs/Web/API/WebVR_API">WebVR API</a> の中の各ページは同じサイドバーを持ち、この API 内の他のページを指します。 API で正しいサイドバーを生成するには、 KumaScript の GitHub リポジトリにグループデータの項目を追加し、マクロ呼び出しの中で<em>グループデータ名</em>のところに項目名を入れる必要があります。これを行う方法についてのガイドは <a href="/ja/docs/MDN/Contribute/Structures/API_references/API_reference_sidebars">API リファレンスサイドバー</a>を参照してください。</li> + <li>\{{Draft}} — this generates a <strong>Draft</strong> banner that indicates that the page is not yet complete, and should only be removed when the first draft of the page is completely finished. After it is ready to be published, you can remove this.</li> + <li>\{{SeeCompatTable}} — this generates a <strong>This is an experimental technology</strong> banner that indicates the technology is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">experimental</a>). If the technology you are documenting is not experimental, you can remove this. If it is experimental, and the technology is hidden behind a pref in Firefox, you should also fill in an entry for it in the <a href="/ja/docs/Mozilla/Firefox/Experimental_features">Experimental features in Firefox</a> page.</li> + <li>\{{SecureContext_Header}} — this generates a <strong>Secure context</strong> banner that indicates the technology is only available in a <a href="/ja/docs/Web/Security/Secure_Contexts">secure context</a>. If it isn't, then you can remove the macro call. If it is, then you should also fill in an entry for it in the <a href="/ja/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts">Features restricted to secure contexts</a> page.</li> + <li>\{{Deprecated_Header}} — this generates a <strong>Deprecated</strong> banner that indicates the technology is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">deprecated</a>. If it isn't, then you can remove the macro call.</li> + <li>\{{Interface_Overview("<em>GroupDataName</em>")}} {{Experimental_Inline}} — this generates the main body of the page (Constructor, Properties, Methods and Evenets)</li> +</ul> + +<h3 id="Tags" name="Tags">タグ</h3> + +<p>In an API reference page, you need to include the following tags (see the <em>Tags</em> section at the bottom of the editor UI): <strong>API</strong>, <strong>Reference</strong>, <strong>Interface</strong>, <em>the name of the API</em> (e.g. <strong>WebVR</strong>), the name of the interface (e.g. <strong>Request</strong>), <strong>Experimental</strong> (if the technology is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">experimental</a>), <strong>Secure context</strong> (if it is available in a secure context only), and <strong>Deprecated</strong> (if it is <a href="/ja/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">deprecated</a>).</p> + +<p>Optionally, you can elect to include some other tags that effective represent terms people might search for when looking for information on that technology. For example on WebVR interface pages we include <strong>VR</strong> and <strong>Virtual reality</strong>.</p> + +<h3 id="Browser_compatibility" name="Browser_compatibility">ブラウザーの互換性</h3> + +<p>To fill in the browser compat data, you first need to fill in an entry for the API into our <a href="https://github.com/mdn/browser-compat-data">Browser compat data repo</a> — see our <a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables#The_new_way_The_browser_compat_data_repo_and_dynamic_tables">guide on how to do this</a>.</p> + +<p>Once that is done, you can show the compat data for the interface with a \{{Compat(…)}} macro call.</p> +</div> + +<p>{{APIRef("GroupDataName")}}{{Draft}}{{SeeCompatTable}}{{SecureContext_Header}}{{Deprecated_Header}}</p> + +<p class="summary">The summary paragraph — start by naming the interface, saying what API it is part of, and saying what it does. This should ideally be 1 or 2 short sentences. You could copy most of this from the Interface's summary on the corresponding API landing page.</p> + +<p>{{InheritanceDiagram}}</p> + +<h2 id="Constructor" name="Constructor">コンストラクター</h2> + +<dl> + <dt>{{DOMxRef("NameOfTheInterface.NameOfTheInterface")}}</dt> + <dd>Creates a new instance of the {{DOMxRef("NameOfTheInterface")}} object.</dd> +</dl> + +<h2 id="Properties" name="Properties">プロパティ</h2> + +<p><em>Also inherits properties from its parent interface, {{DOMxRef("NameOfParentInterface")}}.</em> (Note: If the interface doesn't inherit from another interface, remove this whole line.)</p> + +<dl> + <dt>{{DOMxRef("NameOfTheInterface.property1")}}{{ReadOnlyInline}} {{Deprecated_Inline}}</dt> + <dd>Include a brief description of the property and what it does here. Include one term and definition for each property. If the property is not readonly/experimental/deprecated, remove the relevant macro calls.</dd> + <dt>{{DOMxRef("NameOfTheInterface.property2")}}</dt> + <dd>etc.</dd> +</dl> + +<h2 id="Methods" name="Methods">メソッド</h2> + +<p><em>Also inherits methods from its parent interface, {{DOMxRef("NameOfParentInterface")}}.</em> (Note: If the interface doesn't inherit from another interface, remove this whole line.)</p> + +<dl> + <dt>{{DOMxRef("NameOfTheInterface.method1()")}} {{Experimental_Inline}} {{Deprecated_Inline}}</dt> + <dd>Include a brief description of the method and what it does here. Include one term and definition for each method. If the method is not experimental/deprecated, remove the relevant macro calls.</dd> + <dt>{{DOMxRef("NameOfTheInterface.method2()")}}</dt> + <dd>etc.</dd> +</dl> + +<h2 id="Events" name="Events">イベント</h2> + +<p>Listen to these events using <code><a href="/ja/docs/Web/API/EventTarget/addEventListener">addEventListener()</a></code> or by assigning an event listener to the <code>on<em>eventname</em></code> property of this interface.</p> + +<dl> + <dt><code><a href="#">eventname1</a></code></dt> + <dd>Fired when ... include description of when event fires<br> + Also available via the <code><a href="#">oneventname1</a></code> property.</dd> + <dt><code><a href="#">eventname2</a></code></dt> + <dd>Fired when ... include description of when event fires<br> + Also available via the <code><a href="#">oneventname2</a></code> property.</dd> + <dt>etc.</dt> +</dl> + +<h2 id="Examples" name="Examples">例</h2> + +<p>Fill in a simple example that nicely shows a typical usage of the interfaces, then perhaps some more complex examples (see our guide on how to add <a href="/ja/docs/MDN/Contribute/Structures/Code_examples">code examples</a> for more information).</p> + +<pre class="brush: js notranslate">my code block</pre> + +<p>And/or include a list of links to useful code samples that live elsewhere:</p> + +<ul> + <li>x</li> + <li>y</li> + <li>z</li> +</ul> + +<h2 id="Specifications" name="Specifications">仕様書</h2> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">仕様書</th> + <th scope="col">状態</th> + <th scope="col">備考</th> + </tr> + </thead> + <tbody> + <tr> + <td>{{SpecName("NameOfOtherSpecification", "#document-fragment-linking-directly-to-feature-definition", "NameOfTheFeature")}}</td> + <td>{{Spec2("NameOfOtherSpecification")}}</td> + <td>Defines blah blah feature. If no other specs define specific subfeatures of this interface, you can delete this table row.</td> + </tr> + <tr> + <td>{{SpecName("NameOfSpecification", "#document-fragment-linking-directly-to-interface-definition", "NameOfTheInterface")}}</td> + <td>{{Spec2("NameOfSpecification")}}</td> + <td>初回定義</td> + </tr> + </tbody> +</table> + +<h2 id="Browser_compatibility_2" name="Browser_compatibility_2">ブラウザーの互換性</h2> + +<div class="hidden">このページの互換性一覧表は構造化データから生成されています。データに協力していただけるのであれば、 <a class="external" href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> をチェックアウトしてプルリクエストを送信してください。</div> + +<p>{{Compat("path.to.feature.NameOfTheInterface")}}</p> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li>Include list of</li> + <li>other links related to</li> + <li>this API that might</li> + <li>be useful</li> +</ul> diff --git a/files/ja/mdn/structures/page_types/index.html b/files/ja/mdn/structures/page_types/index.html new file mode 100644 index 0000000000..818c365cf7 --- /dev/null +++ b/files/ja/mdn/structures/page_types/index.html @@ -0,0 +1,239 @@ +--- +title: ページの種類 +slug: MDN/Structures/Page_types +tags: + - MDN Meta + - ガイド + - ドキュメンテーション + - 構造 +translation_of: MDN/Structures/Page_types +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p class="summary">MDN に繰り返し使用されるいくつかの種類のページがあります。この記事では、これらのページの種類とその目的、および新しいページを作成するときに使用するそれぞれのテンプレートの例と使用方法について説明します。</p> + +<p>MDN には大きく分けて3種類のページがありますが、いくつかの種類のページはは複数のカテゴリに分類されます。</p> + +<ul> + <li><strong>リファレンス</strong>ページは何かの詳細を記述し、記述されているものの構造に従って編成されています</li> + <li><strong>ガイド</strong>ページには、何かを行う方法や使う方法が書かれており、読者の目標に基づいて編成されています</li> + <li><strong>ナビゲーションページ</strong>は、主に関連するトピックに関する他のページへのリンクを提供するために存在します</li> +</ul> + +<h2 id="Creating_a_new_page" name="Creating_a_new_page">新しいページの作成</h2> + +<p>MDN に新しいページを作成するには、まず「ページ作成者」のアクセス許可が必要です。これを持っていない場合は、MDN 管理チームのメンバーからリクエストできます (<a href="/ja/docs/MDN/Contribute/Structures/mdn-admins@mozilla.org">mdn-admins メーリングリスト</a>を使用してください)。これを取得したら、いくつかの方法で新しいページを作成することができます：</p> + +<ul> + <li>いずれのページでも、ギアメニューの [新しいサブ記事] オプションを使用して新しいサブページを作成できます。<img alt="options or gear menu on mdn, which includes the new sub-article option " src="https://mdn.mozillademos.org/files/15912/171EA6E3-FEA6-4B2D-AFF7-31E52A1FEA09.png" style="border-style: solid; border-width: 1px; display: block; height: 300px; margin: 0px auto; width: 233px;"></li> + <li>また、マクロ呼び出しで作成された赤いリンク (まだ存在しないページへのリンク。例えば a \{{domxref()}}) をたどって新しいページを作成することもできます</li> +</ul> + +<p>これは新しいページの UI で、そこで新しいページへのコンテンツの入力を開始できます。</p> + +<h2 id="How_to_use_the_templates" name="How_to_use_the_templates">テンプレートの使い方</h2> + +<p>When creating a new page you can ensure that you've used the right page structure/contents by using one of our page templates (see the sections below).</p> + +<p>These page templates don't make much sense as published pages, but if you view them in edit view you'll see that they contain a lot of helpful comments, placeholders, and hints detailing how to fill in the missing information and create your page.</p> + +<p>At the top of each template you'll find a section entitled <em>Remove before publishing</em> — this contains information on how to fill in the page title, slug, sidebar menu, and tags (e.g. information that doesn't actually appear in the body of the article). You need to delete this section after you've followed the instructions in it, before the page can be considered finished.</p> + +<p>To use a template, currently you just have to copy the source of the template out of its edit view and paste the contents into the <em>New document</em> page you are creating your new article in. In the future, we hope to update the editor UI to allow you to choose templates directly from there.</p> + +<h2 id="Old-style_page_layouts" name="Old-style_page_layouts">古い形式のページレイアウト</h2> + +<p>Sometimes you will come across old-style reference pages that look markedly different from the templates presented here. For example, old-style interface pages had all the interfaces' member details on a single page, and individual method/property/constructor/event listener pages didn't exist.</p> + +<p>If you come across an old-style set of pages, we'd love for you to update them to the new style! However, we do appreciate that this could be a large amount of work. If the information to update is not too large, and you have some free time, by all means try updating it to the new style.</p> + +<p>If the work is more significant, then you should consider a few factors when prioritising the work:</p> + +<ul> + <li>How out-of-date is the information?</li> + <li>How low quality is the information?</li> + <li>How popular is the feature? How sought after is the information?</li> +</ul> + +<p>If you want to get a team together to work on an update, or you just want to report or discuss some content needing an update, <a href="https://discourse.mozilla.org/c/mdn">send us a message on discourse</a>.</p> + +<h2 id="API_landing_page" name="API_landing_page">API ランディングページ</h2> + +<p>An <strong>{{Glossary("API")}} landing page</strong> provides an overview of what a particular API does, as well as links to the documentation for each of the interfaces, globals, functions, etc. offered by the API. It does not link directly to specific methods or properties within the API's classes, except in the context of the overview text. It is primarily a <em>navigation</em> page, but also functions as an at-a-glance <em>reference</em> page for the API.</p> + +<p>There are some instances where multiple APIs exist that are distinct, and are defined in their own specifications, but they closely related and therefore would make sense to cover with a single API landing page. For example, the <a href="https://www.w3.org/TR/generic-sensor/">Generic Sensor API</a> cover general sensor concerns, but more specific concerns are covered in other APIs such as <a href="https://www.w3.org/TR/ambient-light/">Ambient Light Sensor</a>, <a href="https://www.w3.org/TR/motion-sensors/">Motion Sensor</a>, etc. In such cases, many of the high level concepts are the same, so it makes no sense to repeat those over multiple landing pages. In such a case, it would make more sense in terms of repetition and findability to cover them all under a single "Web sensors" landing page.</p> + +<h3 id="Example" name="Example">例</h3> + +<ul> + <li><a href="/ja/docs/Web/API/WebVR_API">WebVR API</a></li> +</ul> + +<h3 id="Templates" name="Templates">テンプレート</h3> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types/API_landing_page_template">API landing page template</a></li> +</ul> + +<h2 id="API_reference_page" name="API_reference_page">API リファレンスページ</h2> + +<div class="note"> +<p><strong>メモ:</strong> Also known as an <em>Interface landing page.</em></p> +</div> + +<p>An <strong>API reference page</strong> lists all the methods, properties, events, and so forth that are members of a particular interface or class. It provides an overview of what the class or interface does or is used for, and gives links to the documentation for each of these members. It is more granular than an API landing page, which typically links to multiple API reference pages.</p> + +<h3 id="Example_2" name="Example_2">例</h3> + +<ul> + <li><a href="/ja/docs/Web/API/Request">Request interface</a> of the <a href="/ja/docs/Web/API/Fetch_API">Fetch API</a>.</li> +</ul> + +<h3 id="Templates_2" name="Templates_2">テンプレート</h3> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types/API_reference_page_template">API reference page template</a></li> +</ul> + +<h2 id="API_reference_subpage" name="API_reference_subpage">API リファレンスサブページ</h2> + +<p>An <strong>API reference subpage</strong> is a child of an API reference page. It documents a single interface member in detail.</p> + +<h3 id="Examples" name="Examples">例</h3> + +<ul> + <li><a href="/ja/docs/Web/API/IDBIndex/count"><code>count()</code> method</a> of the <a href="/ja/docs/Web/API/IDBIndex">IDBIndex</a> interface (part of the <a href="/ja/docs/Web/API/IndexedDB_API">IndexedDB API</a>)</li> + <li><a href="/ja/docs/Web/API/VRDisplay/capabilities">capabilities property</a> of the <a href="/ja/docs/Web/API/VRDisplay">VRDisplay</a> interface (part of the <a href="/ja/docs/Web/API/WebVR_API">WebVR API</a>)</li> + <li><a href="/ja/docs/Web/API/Request/Request">Request() constructor</a> of the <a href="/ja/docs/Web/API/Request">Request</a> interface (part of the <a href="/ja/docs/Web/API/Fetch_API">Fetch API</a>)</li> + <li><a href="/ja/docs/Web/API/Window/onvrdisplaypresentchange">onvrdisplaypresentchange event handler</a> (part of the <a href="/ja/docs/Web/API/WebVR_API">WebVR API</a>, which hangs off the <a href="/ja/docs/Web/API/Window">Window</a>) interface</li> +</ul> + +<h3 id="Templates_3" name="Templates_3">テンプレート</h3> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types/API_method_subpage_template">API method subpage template</a></li> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types/API_property_subpage_template">API property subpage template</a></li> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types/API_constructor_subpage_template">API constructor subpage template</a></li> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types/API_event_subpage_template">API event subpage template</a></li> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types/API_event_handler_subpage_template">API event handler subpage template</a></li> +</ul> + +<h2 id="HTML_element_reference_page" name="HTML_element_reference_page">HTML 要素リファレンスページ</h2> + +<p>An <strong>HTML reference page</strong> lists all the attributes that are available on an HTML element, explains the element's purpose and usage, and provides examples, browser compatibility information, and other important data.</p> + +<h3 id="Example_3" name="Example_3">例</h3> + +<ul> + <li><a href="/ja/docs/Web/HTML/Element/ol"><code><ol></code> element</a></li> +</ul> + +<h3 id="Templates_4" name="Templates_4">テンプレート</h3> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types/HTML_element_page_template">HTML element page template</a></li> +</ul> + +<h2 id="SVG_element_reference_page" name="SVG_element_reference_page">SVG 要素リファレンスページ</h2> + +<p>An <strong>SVG reference page</strong> lists all the attributes that are available on an SVG element, explains the element's purpose and usage, and provides examples, browser compatibility information, and other important data.</p> + +<h3 id="Example_4" name="Example_4">例</h3> + +<ul> + <li><a href="/ja/docs/Web/SVG/Element/g"><g> element</a></li> +</ul> + +<h3 id="Templates_5" name="Templates_5">テンプレート</h3> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types/SVG_element_page_template">SVG element page template</a></li> +</ul> + +<h2 id="CSS_feature_reference_page" name="CSS_feature_reference_page">CSS 特性リファレンスページ</h2> + +<p>A <strong>CSS reference page</strong> lists all the available syntax for a CSS feature such as a selector or property, and explains the feature's purpose and usage. It also provides examples, browser compatibility information, and other important data.</p> + +<h3 id="Examples_2" name="Examples_2">例</h3> + +<ul> + <li><a href="/ja/docs/Web/CSS/background-color">background-color property</a></li> + <li><a href="/ja/docs/Web/CSS/:hover">:hover pseudo-class</a></li> + <li><a href="/ja/docs/Web/CSS/@media">@media at-rule</a></li> +</ul> + +<h3 id="Templates_6" name="Templates_6">テンプレート</h3> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types/CSS_property_page_template">CSS property page template</a></li> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types/CSS_selector_page_template">CSS selector page template</a></li> +</ul> + +<h2 id="HTTP_header_reference_page" name="HTTP_header_reference_page">HTTP ヘッダーリファレンスページ</h2> + +<p>An <strong>HTTP header reference page</strong> lists all the available directives that an HTTP header can contain, and explains the header's purpose and usage. It also provides examples, browser compatibility information, and other important expl.</p> + +<h3 id="Example_5" name="Example_5">例</h3> + +<ul> + <li><a href="/ja/docs/Web/HTTP/Headers/Cache-Control">Cache-Control header</a></li> +</ul> + +<h3 id="Templates_7" name="Templates_7">テンプレート</h3> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types/HTTP_header_page_template">HTTP header page template</a></li> +</ul> + +<h2 id="Conceptual_page" name="Conceptual_page">概念のページ</h2> + +<p>A <strong>conceptual page</strong> is a <em>guide</em> page that explains or teaches something. Generally, if a page contains primarily prose, and doesn't fall into another page type, it's probably a conceptual page. An extended discussion of a topic might be spread across multiple conceptual pages, and linked using <a href="https://github.com/mdn/kumascript/blob/master/macros/Next.ejs">Next</a> and <a href="https://github.com/mdn/kumascript/blob/master/macros/Previous.ejs">Previous</a> macros.</p> + +<h3 id="Examples_3" name="Examples_3">例</h3> + +<ul> + <li><a href="/ja/docs/Web/API/WebVR_API">Using the WebVR API</a></li> + <li><a href="/ja/docs/Web/API/Web_Audio_API">Creating visualizations with the Web Audio API</a></li> + <li><a href="/ja/docs/Learn/CSS/Introduction_to_CSS/Cascade_and_inheritance">Cascade and inheritance in CSS</a></li> +</ul> + +<h2 id="Glossary_page" name="Glossary_page">用語集のページ</h2> + +<p>A <strong>glossary page</strong> contains a brief explanation of a term, topic, or concept. The first paragraph should be a simple, self-contained description of the term, no more than a couple sentences. This can be followed by links to further information in the <strong>Learn more</strong> section. If the page grows to more than a screenful or so, it's too long and should be converted to a conceptual page. See <a href="/ja/docs/MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary">How to write and reference an entry in the glossary</a> for more details.</p> + +<h3 id="Examples_4" name="Examples_4">例</h3> + +<ul> + <li><a href="/ja/docs/Glossary/DOM">DOM</a></li> + <li><a href="/ja/docs/Glossary/Exception">Exception</a></li> + <li><a href="/ja/docs/Glossary/Hyperlink">Hyperlink</a></li> +</ul> + +<h3 id="Templates_8" name="Templates_8">テンプレート</h3> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Structures/Page_types/Glossary_page_template">Glossary page template</a></li> +</ul> + +<h2 id="Landing_page" name="Landing_page">ランディングページ</h2> + +<p>A <strong>landing page</strong> serves as a menu, of sorts, for its subpages, and is therefore primarily a <em>navigation</em> page. A landing page layout is typically used for the root page of a tree of pages about a particular topic. It opens with a brief summary of the topic, then presents a structured list of links to its subpages, and optionally, additional material that be useful to the reader.</p> + +<p>The list of subpages can be generated automatically using the templates {{TemplateLink("SubpagesWithSummaries")}}, {{TemplateLink("SubpageMenuByCategories")}}, and {{TemplateLink("LandingPageListSubpages")}}. However, in more complex cases, the list may need to be created (and maintained!) by hand.</p> + +<p>If you use one of the page list macros, it may be worthwhile to edit the page properties and set a non-zero value for "Rendering max age." This value is the maximum amount of time that MDN will let elapse between fully re-rendering the page, including re-running all macros. By setting an appropriate, reasonable time you can help ensure that the landing page is never out of date for more than a short time.</p> + +<p>Choose an interval that makes sense based on the likelihood of the content to change. For an area which is under constant work, such as a new API in the process of being documented, a low value such as 2 hours could make sense. The value should be higher if the content won't change often; 3 days, for example.</p> + +<p>Try to remember to reset the interval to 0 hours, 0 minutes, and 0 seconds once the content reaches a relatively stable state, to let MDN cache the pages over a longer period of time.</p> + +<h3 id="Examples_5" name="Examples_5">例</h3> + +<ul> + <li><a href="/ja/docs/Web/HTML">HTML</a></li> + <li><a href="/ja/docs/Web/CSS">CSS</a></li> + <li><a href="/ja/docs/Web/API">Web APIs</a></li> + <li><a href="/ja/docs/Web/JavaScript">JavaScript</a></li> + <li><a href="/ja/docs/Learn">Learning area</a></li> + <li><a href="/ja/docs/MDN/Contribute">Contributing to MDN</a></li> +</ul> diff --git a/files/ja/mdn/structures/quicklinks/index.html b/files/ja/mdn/structures/quicklinks/index.html new file mode 100644 index 0000000000..b5c001a827 --- /dev/null +++ b/files/ja/mdn/structures/quicklinks/index.html @@ -0,0 +1,68 @@ +--- +title: クイックリンク +slug: MDN/Structures/Quicklinks +tags: + - Guide + - MDN Meta + - Structures + - ガイド + - 構造 +translation_of: MDN/Structures/Quicklinks +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">MDN はページへのクイックリンクの追加に対応しています。これらのボックスは、 MDN 上の他のページやサイト外のページへの階層的なリストを含むことができます。この記事では、クイックリンクボックスの生成方法を解説します。</span></p> + +<p>ページには、左側のサイドバーに表示されるクイックリンクボックスが1つしかない場合があります。このサイドバーは、任意で、ユーザーがサイドバーの上部にある「このサイドバーを隠す」リンクをクリックすることで非表示にすることができます。</p> + +<h2 id="Quicklinks_syntax" name="Quicklinks_syntax">クイックリンクの構文</h2> + +<p>ページのクイックリンクは、 "Quick_Links" という ID を持つ {{HTMLElement("section")}} ブロックを作成することによって提供されます。次に、セクション内のクイックリンクボックスに入るコンテンツを配置します。これらは {{HTMLElement("ol")}} 順序付きリスト (ネストも可) として整形する必要があります。これは、エディターツールバーの番号付きリストボタンを使用して行うことができます。たとえば、このページにはいくつかの便利なページにつながるクイックリンクボックスがあります。その HTML は次のようになります。</p> + +<pre class="brush: html notranslate"><section id="Quick_Links"> + <ol> + <li><a href="http://docs.ckeditor.com/">CKEditor documentation site</a></li> + <li><a href="http://mxr.mozilla.org/">MXR: Mozilla source cross-reference</a></li> + <li class="toggle"> + <details><summary>Style guides</summary> + <ol> + <li><a href="http://www.economist.com/research/StyleGuide/">The Economist style guide</a></li> + <li><a href="http://www.amazon.com/gp/product/0226104036/">The Chicago manual of style</a></li> + <li><a href="http://www.answers.com/library/Dictionary">Answers.com dictionary</a></li> + <li><a href="http://www.wsu.edu/~brians/errors/">Common Errors in English</a></li> + </ol> + </details> + </li> + </ol> +</section> +</pre> + +<p>注意すべき重要事項:</p> + +<ul> + <li>リストは順序付きリストである<strong>べき</strong>です。</li> + <li>別な順序付きリストを含んだ {{HTMLElement("details")}} を同じ {{HTMLElement("li")}} ブロックの<strong>中</strong>で使用すると、階層構造のリストを持つことができます。</li> +</ul> + +<h2 id="Using_macros_to_create_quicklinks" name="Using_macros_to_create_quicklinks">クイックリンクを生成するマクロの使用</h2> + +<p class="mainArticle" style=""><em>メイン記事: <a href="/ja/docs/MDN/Contribute/Howto/Use_navigation_sidebars">ナビゲーションサイドバーを使うには</a></em></p> + +<p>言うまでもなく、マクロを使用してクイックリンクを生成することができます (また、しばしば<strong>するべき</strong>です)。複数のページで同じクイックリンクを使用する必要がある場合は、マクロにするべきです。たとえば、このページでは {{TemplateLink("MDNSidebar")}} マクロを使用してクイックリンクボックスを生成しています。 <a href="/ja/docs/Project:MDN/Contributing/Editor_guide">MDN エディターガイド</a>の他の各ページも同様です。</p> + +<p>マクロは、必要に応じて単純なものでも複雑なものでもかまいません。上記の{{anch("Quicklinks_syntax", "クイックリンクの構文")}}と同様の HTML を出力するだけです。</p> + +<h3 id="Standard_quicklinks_macros" name="Standard_quicklinks_macros">標準のクイックリンクマクロ</h3> + +<p>私たちのクイックリンクを生成する標準マクロの一覧です。</p> + +<dl> + <dt>{{TemplateLink("CSSRef")}}</dt> + <dd>CSS リファレンスページの標準クイックリンクを作成します。</dd> + <dt>{{TemplateLink("HTMLRef")}}</dt> + <dd>HTML リファレンスページの標準クイックリンクを作成します。</dd> + <dt>{{TemplateLink("MakeSimpleQuicklinks")}}</dt> + <dd>MDN 上のページのリストが与えられた場合、このマクロは、ページのタイトルをリンクテキストとして使用し、その概要をツールチップとして使用するクイックリンクボックスを作成します。これは階層リストを作成しません。</dd> + <dt>{{TemplateLink("QuickLinksWithSubpages")}}</dt> + <dd>現在のページ (または指定したページ) の子を宛先として使用して、クイックリンクのセットを作成します。これにより、最大2レベルの階層リストが作成されます。ページのタイトルをリンクテキストとして使用し、その概要をツールチップとして表示します。</dd> +</dl> diff --git a/files/ja/mdn/structures/specification_tables/index.html b/files/ja/mdn/structures/specification_tables/index.html new file mode 100644 index 0000000000..924d8e10dd --- /dev/null +++ b/files/ja/mdn/structures/specification_tables/index.html @@ -0,0 +1,82 @@ +--- +title: 仕様書表 +slug: MDN/Structures/Specification_tables +tags: + - Guide + - MDN Meta + - Structures +translation_of: MDN/Structures/Specification_tables +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p>MDN 上のすべてのリファレンスページでは、 API または技術が定義されている仕様書に関する情報を提供するようにしてください。この記事ではこれらの表の外見を示し、構築方法を説明します。</p> + +<p>このような表は、少し<a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables">互換性一覧表</a> (こちらも仕様書表があるすべてのページで示すようにしてください) と似ています。</p> + +<h2 id="Format" name="Format">書式</h2> + +<p>仕様書表は、従来から3つの列で構成されています。</p> + +<dl> + <dt>仕様書</dt> + <dd>その技術が定義されている仕様書の名前やリンクです。</dd> + <dt>状態</dt> + <dd>仕様書の状態です (例えば、編集者草稿であるか勧告候補であるかなど)。</dd> + <dt>備考</dt> + <dd>関連する何らかの追加情報です。これは特に、 API が複数の仕様書にまたがって定義された場合に有用で、それぞれの仕様書が API のどの部分のもとになっているのかを短く説明することができます。</dd> +</dl> + +<p>MDN で見られる大部分の表は上記の列から構成されていますが、構造を更新する進行中の計画があり、あちこちで異なる構造のものを見かけることがあるかもしれませんが、最終的な目標は<a href="https://github.com/mdn/browser-compat-data">ブラウザー互換データリポジトリ</a>に仕様書の定義のリンクを格納して、そこから表を自動生成させることです。公開議論の文書は <a href="https://docs.google.com/document/d/1eL8YtslVZAnIAGb7rcZGbvXndkcR7lb9rhDpvGpGaWs/edit#">Improving MDN Specification tables</a> にあります。</p> + +<h2 id="Which_specs_should_be_included" name="Which_specs_should_be_included">どの仕様書を含めるべきか</h2> + +<p>表の中では1行あたり1件の API または技術が基づく仕様書が記述されます。</p> + +<p>それぞれの表にどの仕様書を含めるかは、どの機能が当該リファレンスページで記述されているかによります。</p> + +<ul> + <li>ある仕様書の単一機能についての記述である場合、普通、その機能を定義している最新の仕様書を記述した1行を含めることだけが必要です。例えば <a href="/ja/docs/Web/API/AudioContext/close#Specifications"><code>AudioContext.close()</code> の仕様書</a>のような書き方です。</li> + <li>複数の仕様書で定義された複数の部分 API のランディングページ (拡張機能など) である場合、参照している複数の仕様書を複数行にわたって記述する必要があります。簡潔で明確な例としては <a href="/ja/docs/Web/API/Gamepad_API#Specifications">Gamepad API の仕様書</a>を参照して下さい。</li> +</ul> + +<h3 id="Different_types_of_specs" name="Different_types_of_specs">様々な種類の仕様書表</h3> + +<p>「ライブ仕様書」で定義された技術 (例えば、<a href="https://html.spec.whatwg.org/multipage/">HTML</a> や <a href="https://dom.spec.whatwg.org/">DOM</a>) の場合、おそらくリンクする必要があるのは単一の仕様書だけであり、その技術が定義されている正式な単一の場所としてのものです。</p> + +<p>他の仕様書表 (通常は WebAPI 仕様書) では、常に最新の編集者草稿を指す単一の URL を、仕様書ごとに (同じ仕様書とは限らないが) 入れる必要があるのが普通でしょう。このような場合、普通は最新の編集者草稿にリンクしたほうが、仕様書が変更された時にリンクが正しくあり続けます。 — 最新の編集者草稿は、最新の機能がすべて定義されており、ブラウザーベンダーがよりどころとしているものです。したがって、これはリンクするのに最も興味深い場所であり、多くの場合は最新情報です。この例としては、 <a href="https://w3c.github.io/IndexedDB/">IndexedDB draft</a>, <a href="https://webaudio.github.io/web-audio-api/">Web Audio API draft</a>, 等があります。最新の草稿へのリンクが、仕様書表の一番上に見られます。</p> + +<p>他の仕様書表には、一つの仕様書で定義された中心機能がありますが、機能が拡張されることがあり、例えば、 Credential Management 仕様書は Web Authentication 仕様書によって拡張されています (<a href="/ja/docs/Web/API/Credential_Management_API#Specifications">仕様書表を見る</a>)。</p> + +<p>CSS の仕様書表については、そのように単純ではありません。 — CSS の仕様書はふつう、新しい機能を導入する複数のレベルに分割されています。 — 例えば、 <a href="https://drafts.csswg.org/mediaqueries-4/">Media Queries Level 4</a> と <a href="https://drafts.csswg.org/mediaqueries-5/">Media Queries Level 5</a> といった具合です。多くの場合、複数の仕様書にリンクして、機能の動作が定義されているすべての場所を示す必要があります。</p> + +<p>MDN に仕様書表を追加するとき (方法は以下参照)、上記の考えを意識しておいてください。ライブの仕様書を表現するには技術の名前のみです (例えば "HTML")。最新の仕様書の草稿は <em>WebAPI 名</em>草稿とします (例えば "IndexedDB 草稿")。複数の仕様書が必要な場合は、仕様書の正確な名前を使用してください。</p> + +<h3 id="What_not_to_include" name="What_not_to_include">含めるべきではないもの</h3> + +<p>MDN の多くの仕様書表が、ある機能を定義したすべての仕様書を過去にさかのぼって含めています。例えば、 <a href="/ja/docs/Web/CSS/color#Specifications">CSS の color プロパティの仕様書表</a>のようにです。これは CSS レベル1まですべてをさかのぼっていますが、おそらく表の下3行は必要ないでしょう。色がアニメーション可能であることについての部分を除いて、レベル4ですべてが定義されています。</p> + +<p>特に、廃止とされた仕様書を参照する必要はありません。これは役に立ちません。</p> + +<p>また、 <a href="https://www.w3.org/2019/04/WHATWG-W3C-MOU.html#transition">W3C が WHATWG Living Standard で扱っている技術仕様書のスナップショットの発行をやめることに合意しました</a>。 — 両方で扱っていた技術については、 WHATWG の仕様書を並べるだけでよくなります。</p> + +<h2 id="Macros" name="Macros">マクロ</h2> + +<p>これらの表を、適切な書式で標準の書式で構築しやすくするために、 KumaScript マクロを使用しています。使い方を知っておく必要がある物は2つあります。</p> + +<h3 id="SpecName" name="SpecName"><code>\{{SpecName}}</code></h3> + +<p>{{TemplateLink("SpecName")}} マクロは、「仕様書」列の内容を生成するために使います。3つの引数を受け付けます。</p> + +<ol> + <li>仕様書の名前。</li> + <li>任意で、リンクされた仕様書内のアンカー。これは、例えば複数のオブジェクトやインターフェイスを定義している仕様書の中で、特定の章にリンクできるようになります。なお、この引数は任意ですが、強く推奨します。読み手は生成されたリンクをクリックしたとき、仕様書のその概念が定義されている詳細な位置に届くことを期待するからです。</li> + <li>ツールチップ内で使用するプロパティまたはエンティティの名前です。これは、仕様書内で特定のインターフェイスにリンクする時にも使用されます。この引数も任意ですが、追加して概念の名前を設定することを強く推奨します。</li> +</ol> + +<p>仕様書に指定する名前は、マクロ内の <code>specList</code> オブジェクトで見られます。リンクしたい仕様書にマクロが対応していない場合、 <a href="https://github.com/mdn/kumascript/blob/master/macros/SpecData.json">SpecData</a> ファイルを更新するプルリクエストを提案してください。</p> + +<h3 id="Spec2" name="Spec2"><code>\{{Spec2}}</code></h3> + +<p>{{TemplateLink("spec2")}} マクロは、指定されれた仕様書の名前から、「状態」列で仕様書の状態を示すウィジェットを生成し挿入します。こちらも <a href="https://github.com/mdn/kumascript/blob/master/macros/SpecData.json">SpecData</a> ファイルからデータを取得します。こちらも、リンクしたい仕様書にマクロが対応していない場合は、プルリクエストを提案してください。</p> diff --git a/files/ja/mdn/structures/syntax_sections/index.html b/files/ja/mdn/structures/syntax_sections/index.html new file mode 100644 index 0000000000..19b5bf3ee1 --- /dev/null +++ b/files/ja/mdn/structures/syntax_sections/index.html @@ -0,0 +1,250 @@ +--- +title: 構文の節 +slug: MDN/Structures/Syntax_sections +tags: + - API + - CSS + - HTML + - MDN Meta + - Structure + - Syntax + - onboarding + - 進行中 +translation_of: MDN/Structures/Syntax_sections +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">MDN リファレンスページの構文の節には、機能が持つ正確な構文を定義する構文ボックスがあります (例えば、どのような引数が受け入れられるか、どれがオプションかなど)。この記事では、リファレンス記事の構文ボックスの書き方を説明します。</p> + +<h2 id="API_reference_syntax" name="API_reference_syntax">API リファレンスの構文</h2> + +<p>API リファレンスページの構文の節は手作業で書かれ、設置するページの種類によって異なります。しかし、共通事項もあります。いずれも節には「構文」という題名を付け、リファレンスページの最上部、導入部分のすぐ下に設置します。</p> + +<p>加えて、それぞれの構文の節はその機能の正確な構文を紹介する「構文」ブロックを、 "Syntax Box" ブロックスタイルを使用してスタイル付けしたもので始める必要があります。</p> + +<pre class="syntaxbox notranslate">A syntax block example</pre> + +<h3 id="General_style_rules" name="General_style_rules">全般的なスタイル規則</h3> + +<p>構文ブロック内をマークアップするために従うべき規則がいくつかあります。</p> + +<ul> + <li>構文ブロック内では (MDN のコード例の中でも) {{HTMLElement("code")}} を使用<em>しない</em>でください。これは一般的に意味がないだけでなく、これを含めると望み通りの表示が行われないので、マークアップしてほしくありません。</li> + <li> + <p>構文ブロック内でプログラマーに依存する部分は、 {{HTMLElement("em")}} を使用してイタリック体にしてください (エディターのツールバーの「斜体」ボタン)。</p> + + <pre class="syntaxbox notranslate"><em>responseStr</em> = <em>element</em>.querySelector(<em>selector</em>);</pre> + + <p>ここで、 <code>responseStr</code> は返値 (開発者が付ける変数名) であり、 <code>element</code> は {{DOMxRef("Element")}} オブジェクトを参照する変数のプレイスホルダーであり、 <code>selector</code> はメソッドの入力引数のプレイスホルダーです。</p> + + <p>ページによっては <code><var></code> が <code><em></code> の代わりに使用されているのを見かけるかもしれません。これでも良いのですが、一般に <code><em></code> を推奨します。</p> + </li> +</ul> + +<h3 id="Constructors_and_methods" name="Constructors_and_methods">コンストラクターやメソッドの場合</h3> + +<h4 id="Syntax_block" name="Syntax_block">構文ブロック</h4> + +<p>構文ブロックは、次のように始めてください ({{DOMxRef("IntersectionObserver.IntersectionObserver", "IntersectionObserver constructor")}} ページを参照)。</p> + +<pre class="syntaxbox notranslate">var <em>observer</em> = new IntersectionObserver(<em>callback</em>, <em>options</em>);</pre> + +<p>または、次のようにします ({{DOMxRef("WindowOrWorkerGlobalScope.fetch")}} を参照)。</p> + +<pre class="syntaxbox notranslate"><em>promiseResponse</em> = fetch(<em>input</em>, <em>init</em>);</pre> + +<p>構文は形式文法の表記を使用して書かれることもあります。例えば以下の {{jsxref("Array.prototype.slice()")}} を参照してください。</p> + +<pre class="syntaxbox notranslate">arr.slice([begin[, end]])</pre> + +<p>角括弧は内部の引数が省略可能であることを表します。これは読者の多くを混乱させるため、推奨しません。代わりに角括弧を外して、構文ブロックの下にある<em>引数</em>の節で、これらの引数が省略可能であることを説明したほうがいいでしょう。</p> + +<h5 id="Multiple_lines" name="Multiple_lines">複数行での表記</h5> + +<p>メソッドが複数の形式で使用されることがあるため、複数の行で記述したい場合があるでしょう。例えば、この ({{DOMxRef("CanvasRenderingContext2D.drawImage")}}) の例をご覧ください。</p> + +<pre class="syntaxbox notranslate">void <em>ctx</em>.drawImage(<em>image</em>, <em>dx</em>, <em>dy</em>); +void <em>ctx</em>.drawImage(<em>image</em>, <em>dx</em>, <em>dy</em>, <em>dWidth</em>, <em>dHeight</em>); +void <em>ctx</em>.drawImage(<em>image</em>, <em>sx</em>, <em>sy</em>, <em>sWidth</em>, <em>sHeight</em>, <em>dx</em>, <em>dy</em>, <em>dWidth</em>, <em>dHeight</em>);</pre> + +<p><code>slice()</code> の構文の例も、すべての変化形を表示し理解しやすくするために、次のように書き直すことができます。</p> + +<pre class="syntaxbox notranslate"><var>arr</var>.slice()<var> +arr</var>.slice(<var>begin</var>) +<var>arr</var>.slice(<var>begin</var>, <var>end</var>)</pre> + +<p>他の複数行の例として、 {{jsxref("Date")}} コンストラクターのページでは、取りうる引数の組み合わせが全く異なる形でたくさんあることを示しています。</p> + +<pre class="syntaxbox notranslate">new Date(); +new Date(<var>value</var>); +new Date(<var>dateString</var>); +new Date(<var>year</var>, <var>monthIndex</var> [, <var>day</var> [, <var>hours</var> [, <var>minutes</var> [, <var>seconds</var> [, <var>milliseconds</var>]]]]]); +</pre> + +<p>ただし前述の通り、角括弧を外し、<em>引数</em>の節で引数が省略可能であることを明確にするべきでしょう。</p> + +<h5 id="Concise_syntax_blocks" name="Concise_syntax_blocks">構文ブロックは簡潔に</h5> + +<p>構文ブロックを簡潔にし、その機能の構文の定義の曖昧さをなくすために — 無関係な構文を含めないでください。例えば、このサイトの多くの場所で、 Promise を説明するために次のような形をよく見かけます。</p> + +<pre class="syntaxbox notranslate"><em>caches</em>.match(<em>request</em>, <em>options</em>).then(function(<em>response</em>) { + // Do something with the response +});</pre> + +<p>しかし、次のものははるかに簡潔で、余計な {{JSxRef("Promise.prototype.then()")}} メソッド呼び出しを含んでいません。</p> + +<pre class="syntaxbox notranslate"><em>promiseResponse</em> = <em>caches</em>.match(<em>request</em>, <em>options</em>);</pre> + +<h4 id="Parameters_section" name="Parameters_section">引数の項</h4> + +<p>次に、「引数」の項を設置して、それぞれの引数が何であるべきかを説明リストの形で説明してください。複数のメンバーを含むことができるオブジェクトの引数は、入れ子の説明リストで記述し、その中にそれぞれのメンバーが何であるべきかを記述してください。省略可能な引数は、説明する用語の名前の隣に \{{optional_inline}} マクロでマークしてください。</p> + +<p>リスト内の各引数の名前は {{HTMLElement("code")}} ブロックの中に含めてください。</p> + +<div class="note"> +<p><strong>メモ</strong>: その機能が何も引数を取らない場合は、「引数」の項を設置する必要はありませんが、中身を「なし」として設置しても構いません。</p> +</div> + +<h4 id="Return_value_section" name="Return_value_section">返値の項</h4> + +<p>その次に、「返値」の項を設置して、コンストラクターやメソッドの返値が何であるかを説明してください。 <code>undefined</code> の場合にも記述します。例については前述のリンクを参照して下さい。</p> + +<h4 id="Exceptions_section" name="Exceptions_section">例外の項</h4> + +<p>最後に、「例外」の項を設置して、コンストラクターやメソッドの呼び出し時に問題が発生した場合にどの例外が発生するかを説明してください。発生する原因としては、引数名の綴りが間違っていたり、間違ったデータ型の値が与えられたり、呼び出された環境に問題があったり (例えば、安全なコンテキストで実行する機能を安全でないコンテキストで実行しようとした場合など)、その他の理由であったりする場合などです。</p> + +<p>メソッドで発生する例外を特定するには、仕様を十分に精査する必要があります。機能がどのように動作するかについて、仕様書の1つ1つの説明を調べると、一般に例外とそれが発生する状況の確実な一覧を得ることができます。</p> + +<p>例外の名前と説明を説明リストに記述してください。</p> + +<div class="note"> +<p><strong>メモ</strong>: その機能で発生する例外がない場合は「例外」の項を設置する必要はありませんが、中身を「なし」として設置しても構いません。</p> +</div> + +<h3 id="Properties" name="Properties">プロパティの場合</h3> + +<h4 id="Syntax_block_2" name="Syntax_block_2">構文ブロック</h4> + +<p>次のように構文ブロックで始めてください ({{DOMxRef("IntersectionObserver.root")}} を参照)。</p> + +<pre class="syntaxbox notranslate"><var>var <em>root</em> = IntersectionObserver</var>.root;</pre> + +<p>読み取り専用のプロパティではない場合は、二行を使ってプロパティの取得と設定の両方を示すのもいいでしょう ({{DOMxRef("AudioParam.value")}} を参照)。</p> + +<pre class="syntaxbox notranslate"><em>gain</em> = <em>gainNode</em>.gain.value; +<em>gainNode</em>.gain.value = 0;</pre> + +<h4 id="Value_section" name="Value_section">値の項</h4> + +<p>構文ブロックの下に「値」の項を設置する必要があり、そこでプロパティの値を — データ型とその用途について — 説明してください。</p> + +<h4 id="Exceptions_section_2" name="Exceptions_section_2">例外の項</h4> + +<p>プロパティにアクセスする際に例外が発生する可能性がある場合、「例外」の項を設置してそれぞれの例外を説明してください。これは前述のメソッドやコンストラクターの説明と同様のことをしてください。</p> + +<h3 id="Event_handlers" name="Event_handlers">イベントハンドラーの場合</h3> + +<p>イベントハンドラープロパティは確かにプロパティですが、構文の節の中ではいくらかの違いがあります。</p> + +<h4 id="Syntax_block_3" name="Syntax_block_3">構文ブロック</h4> + +<p>次のように構文ブロックで始めてください ({{DOMxRef("Window.onvrdisplaypresentchange")}} を参照)。</p> + +<pre class="syntaxbox notranslate"><em>window</em>.onvrdisplaypresentchange = <em>functionRef</em>;</pre> + +<p>以上で十分です。 — イベントハンドラープロパティは常に設定可能で、常に関数が設定されるため、これ以上の情報は不要です。</p> + +<h2 id="JavaScript_reference_syntax" name="JavaScript_reference_syntax">JavaScript リファレンスの構文</h2> + +<p>JavaScript 組込みオブジェクトのリファレンスページは、 API リファレンスページと同様の基本規則に従います。例えばメソッドやプロパティについてです。多少の違いが見られることがあります。</p> + +<ul> + <li>組込みオブジェクトで単一のコンストラクターを持つものは、コンストラクターの構文がオブジェクトのランディングページに含まれていることが良くあります。例えば {{JSxRef("Date")}} を参照してください。 (<code>Date</code> オブジェクト自身が持つ) 静的メソッドは、「メソッド」の下の「Date.prototype メソッド」で記述されていることが分かるでしょう。</li> + <li>また、引数も例外もないメソッドは、 JavaScript リファレンスページにこれらの節が全く含まれていないことに気が付くでしょう。例えば {{JSxRef("Date.getDate()")}} や {{JSxRef("Date.now()")}} を参照してください</li> +</ul> + +<h2 id="CSS_reference_syntax" name="CSS_reference_syntax">CSS リファレンスの構文</h2> + +<h3 id="Properties_2" name="Properties_2">プロパティ</h3> + +<p>CSS プロパティページには「構文」の節があり、ふつうはページの先頭にありますが、次第に、機能の典型的な使用方法を示すブロックを含む節や、その機能が何を行うかを説明するライブデモ (例えば {{CSSxRef("animation")}} を参照) の下に見られるようになっています。</p> + +<div class="note"> +<p><strong>メモ</strong>: このようにしているのは、 CSS の形式文法が複雑であり、 MDN の読者の多くが必要としておらず、初心者にとってとっつきにくいからです。実際の構文と例が多くの人にとってより有用です。</p> +</div> + +<p>構文の節の中には、次のような内容が見られるでしょう。</p> + +<h4 id="Optional_explanation_text" name="Optional_explanation_text">説明文は任意</h4> + +<p>CSS プロパティによってはそれ自体が説明的であり、それ以上の説明が本当に必要ない場合があります (例えば {{CSSxRef("color")}})。一方、より複雑で、複数の値などを含む構文の順序の説明が必要なものもあります ({{CSSxRef("animation")}} を参照)。そのような場合、項が始まる前に追加の説明を加えることができます。</p> + +<h4 id="Values_section" name="Values_section">値の項</h4> + +<p>次に、「値」の項を入れてください。 — これには説明リストが入り、プロパティの値を構成する値の型を説明します。値の型はそれぞれ山括弧で囲み、その値の型を説明する MDN のリファレンスページがあれば、そこへリンクしてください。例えば、 {{CSSxRef("border")}} プロパティのリファレンスを参照してください。 — これは3つの値の型を参照しており、そのうちの一つ ({{CSSxRef("<color>")}}) だけがリンクになっています。</p> + +<h4 id="Formal_syntax" name="Formal_syntax">形式文法</h4> + +<p>最後の項、「形式文法」は <a href="https://github.com/mdn/data">MDN data リポジトリ</a>の CSS ディレクトリにあるデータから自動的に生成されます。タイトルの下で {{TemplateLink("CSSSyntax")}} マクロ呼び出しを記述するだけで、残りのことはマクロがやってくれます。</p> + +<p>唯一の問題は、必要なデータが存在することを確認することです。 <a href="https://github.com/mdn/data/blob/master/css/properties.json">properties.json</a> ファイルに、文書化しているプロパティの項目が含まれている必要があり、 <a href="https://github.com/mdn/data/blob/master/css/types.json">types.json</a> ファイルには、プロパティの値で使用されるすべての値の型の項目が含まれている必要があります。</p> + +<p>これを行うには、 <a href="https://github.com/mdn/data">MDN data リポジトリ</a>をフォークし、フォークをローカルにクローンし、新しいブランチに変更を行い、上流のリポジトリに向けてプルリクエストを送信してください。 <a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables#Preparing_to_add_the_data">Git の使用についての詳細はこちらにあります</a>。</p> + +<h3 id="Selectors" name="Selectors">セレクター</h3> + +<p>セレクターのリファレンスページの「構文」の節は、プロパティページよりもずっと簡潔です。ここには "Syntax Box" を使用してスタイル付けされたブロックが1つ入り、ここでセレクターの基本的な構文を、単純なキーワードだけ (例えば {{CSSxRef(":hover")}}) または引数を取るより複雑な関数値 (例えば {{CSSxRef(":not", ":not()")}}) のどちらかで示します。引数を構文ブロックの中の別な項目で説明している場合もあります (例えば {{CSSxRef(":nth-last-of-type", ":nth-last-of-type()")}} を参照してください)。</p> + +<p>このブロックは、 <a href="https://github.com/mdn/data">MDN data リポジトリ</a>の CSS ディレクトリにあるデータから自動的に生成されます。題名の下で {{TemplateLink("CSSSyntax")}} マクロ呼び出しを追加するだけで、残りのことはマクロがやってくれます。</p> + +<p>唯一の問題は、必要なデータが存在することを確認することです。 <a href="https://github.com/mdn/data/blob/master/css/selectors.json">selectors.json</a> ファイルに、文書化しているセレクターの項目が含まれている必要があります。</p> + +<p>これを行うには、 <a href="https://github.com/mdn/data">MDN data リポジトリ</a>をフォークし、フォークをローカルにクローンし、新しいブランチに変更を行い、上流のリポジトリに向けてプルリクエストを送信してください。 <a href="/ja/docs/MDN/Contribute/Structures/Compatibility_tables#Preparing_to_add_the_data">Git の使用についての詳細はこちらにあります</a>。</p> + +<h2 id="HTML_reference_syntax" name="HTML_reference_syntax">HTML リファレンスの構文</h2> + +<p>HTML リファレンスページには「構文」の節がありません。 — 構文は常に要素名を山括弧で囲んだものであるため、必要ないからです。 HTML 要素について主に知っておかなければならないことは、どのような属性を取りうるか、その値は何になるかであり、これは別の「属性」の節で扱います。例としては、 {{htmlelement("ol")}} や {{htmlelement("video")}} をご覧ください。</p> + +<h2 id="HTTP_reference_syntax" name="HTTP_reference_syntax">HTTP リファレンスの構文</h2> + +<p>HTTP リファレンスの構文はすべて手作業で作成され、文書化する HTTP の機能によって異なります。</p> + +<h3 id="HTTP_headersContent-Security-Policy" name="HTTP_headersContent-Security-Policy">HTTP ヘッダー/Content-Security-Policy</h3> + +<p>HTTP ヘッダーの構文 (および Content-Security-Policy) ページ上で二つの節に分けて記述します。 — 「構文」と「ディレクティブ」です。</p> + +<h4 id="Syntax_section" name="Syntax_section">構文の節</h4> + +<p>「構文」の節は、ヘッダーの構文がどのようなものかを、 "Syntax Box" スタイルを使用してスタイル付けされた構文ブロックを用いて、値にどのディレクティブが含まれるか、どのような順番かなどの形式文法を含めて示します。例えば、 {{HTTPHeader("If-None-Match")}} ヘッダーの構文ブロックは次のようになります。</p> + +<pre class="syntaxbox notranslate">If-None-Match: <etag_value> +If-None-Match: <etag_value>, <etag_value>, … +If-None-Match: *</pre> + +<p>ヘッダーによっては個別にリクエストディレクティブ、レスポンスディレクティブ、拡張構文があることがあります。存在する場合、それぞれの項の下にある個別の構文ブロックの中に設置する必要があります。例としては {{HTTPHeader("Cache-Control")}} をご覧ください。</p> + +<h4 id="Directive_section" name="Directive_section">ディレクティブの節</h4> + +<p>「ディレクティブ」の節には、構文に現れる可能性があるすべてのディレクティブの名前と解説を記述した説明リストを設定します。</p> + +<h3 id="HTTP_request_methods" name="HTTP_request_methods">HTTP リクエストメソッド</h3> + +<p>リクエストメソッドの構文は実に単純で、構文ブロックを設置し、 "Syntax Box" スタイルを用いてスタイル付けし、どのようにメソッドの構文を構成するかを示すだけです。 <a href="/ja/docs/Web/HTTP/Methods/GET">GET メソッド</a>の構文は次のようになります。</p> + +<pre class="syntaxbox notranslate">GET /index.html</pre> + +<h3 id="HTTP_response_status_codes" name="HTTP_response_status_codes">HTTP レスポンスステータスコード</h3> + +<p>HTTP レスポンスステータスコードの構文も、実に単純です。 — コードと名前を含む構文ブロックです。例えば次のようになります。</p> + +<pre class="syntaxbox notranslate">404 Not Found</pre> + +<h2 id="SVG_reference_syntax" name="SVG_reference_syntax">SVG リファレンスの構文</h2> + +<h3 id="SVG_elements" name="SVG_elements">SVG 要素</h3> + +<p>SVG 要素に構文の節は存在しません。 — HTML 要素の構文の節と同様です。それぞれの SVG 要素のリファレンスページは、その要素に適用することができる属性の一覧を含みます。例えば {{SVGElement("feTile")}} を参照してください。</p> + +<h3 id="SVG_attributes" name="SVG_attributes">SVG 属性</h3> + +<p>SVG 属性のリファレンスページにも、構文の節はありません。</p> diff --git a/files/ja/mdn/tools/add-ons_and_plug-ins/index.html b/files/ja/mdn/tools/add-ons_and_plug-ins/index.html new file mode 100644 index 0000000000..d89e8efbdb --- /dev/null +++ b/files/ja/mdn/tools/add-ons_and_plug-ins/index.html @@ -0,0 +1,33 @@ +--- +title: MDN に関連するアドオンとプラグイン +slug: MDN/Tools/Add-ons_and_plug-ins +tags: + - Landing + - MDN Meta + - Site-wide + - Tools +translation_of: MDN/Tools/Add-ons_and_plug-ins +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary">MDN コミュニティのメンバーは多くの楽しく、便利なプロジェクトを立ち上げています。 MDN の利用や、内容への貢献を簡単にする、ツール、アドオン、ユーテリティを作成するものがあります。</span></p> + +<p>こうした数々のプロジェクトのリンクがここにあります。これらの多くは完成まで手助けも要るため、あなたが助けるものを探しているコーダーである場合、ここに機会が見つかるかもしれません!</p> + +<div class="twocolumns"> +<dl> + <dt><a href="https://github.com/mdn/doc-linter-webextension">MDN doc tests add-on</a></dt> + <dd>MDNの編集中に表示されるサイドバーを作成する Firefox アドオンで、コンテンツのテストと妥当性チェックを提供します。これは作業途中なので、より多くのテストを歓迎します!</dd> + <dt><a href="https://github.com/npny/mdn-automatic-translation">MDN automatic translation</a></dt> + <dd>{{Glossary("Regular_expression", "正規表現")}}ベースのルールを使って、自動的によくある用語を翻訳された形に置き換える。</dd> + <dt><a href="https://addons.mozilla.org/en-US/firefox/addon/mdn-search/">MDN Search</a></dt> + <dd>URLバーで <code>"mdn <searchterm>"</code> とタイプすることですばやくMDN のリファレンス素材を検索することができる <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions">WebExtension</a>。 組み込みのMDN 検索をベースにしているが、より良い結果を出すようにロジックが追加されている。JavaScript と CSS リファレンスを探すのに最適化されている。</dd> + <dt><a href="https://addons.mozilla.org/en-US/firefox/addon/mdn-interface-documentation-ge/">MDN Interface Documentation Generator</a></dt> + <dd>この Firefox アドオンは、XPCOM インターフェイス用に、適切にフォーマットされたスケルトン生成に役立ちます。しばらく更新されてないので、バージョン互換性の情報を正しく表示しませんが、いろいろと便利です。いくつか更新されたら、またかけがえないものに戻るでしょう。</dd> + <dt> </dt> + <dt><a href="https://github.com/a2sheppy/mdn-save-with-comment">Save with comment hotkey addon</a></dt> + <dd>MDNエディタのリビジョンコメント欄にすぐにスクロールさせる Firefox アドオン。つまりこれによって、あなたが編集したことに対する、小さな情報を簡単に追加できます。</dd> + <dt><a href="https://github.com/Elchi3/sublime-mdn">Sublime Text MDN search plug-in</a></dt> + <dd>コーディング中にドキュメントを得るのに、MDNをすぐに検索できる Sublime Text のプラグイン。</dd> + <dt><a href="https://addons.mozilla.org/en-US/firefox/addon/lazarus-form-recovery/?src=mdn">Lazarus</a></dt> + <dd>定期的にフォームデータをlocal storageに自動保存する Firefox 拡張機能で、すべてのデータをクラッシュやエラーから保護します。これは MDN で作業する時に便利で、なぜなら MDN エディターのコンテンツも保存し、成果を保存する前に何か失敗した場合に戻すことができるためです。</dd> +</dl> +</div> diff --git a/files/ja/mdn/tools/content_kits/index.html b/files/ja/mdn/tools/content_kits/index.html new file mode 100644 index 0000000000..b10f0bb06d --- /dev/null +++ b/files/ja/mdn/tools/content_kits/index.html @@ -0,0 +1,67 @@ +--- +title: コンテンツキット +slug: MDN/Tools/Content_kits +translation_of: Archive/MDN/Content_kits +--- +<div>{{MDNSidebar}}</div><div class="summary"> +<p><span class="seoSummary">MDN コンテンツキットはある題材について技術リソースを集めたもので、 地域の技術者の会合を開いたり、 イベント、会議、ワークショップなどで技術的なプレゼンテーションを行う時に役に立ちます。</span></p> +</div> + +<p>Each MDN Content Kit offers relevant, up-to-date technical information for presenters and teachers on a particular topic related to web development or web app development, such as Web APIs, useful libraries, or developer tools. Content Kits may also be focused on Mozilla products, tools, or technologies such as Firefox Developer Tools or <a href="https://www.mozilla.org/en-US/research/">Mozilla Research</a> projects. Resources may include slides, demos, code samples, screencasts, video, exercises, etc.</p> + +<p>By providing MDN Content Kits, MDN aims to grow developer engagement with Mozilla in regional communities, and increase standards-based web development globally.</p> + +<h2 id="MDN_コンテンツキットを作成する_または_寄贈する">MDN コンテンツキットを作成する または 寄贈する</h2> + +<p>Kits can be built by anyone, and we encourage people to suggest and build kits! Individuals may also contribute to existing content kits by submitting a pull request on Github. Get started with the <a href="https://github.com/mdn/content-kit-template">MDN Content Kit Template</a> on Github or read about the project on the <a href="https://wiki.mozilla.org/MDN/Projects/Content/MDN_Content_Kits">MDN wiki</a>.</p> + +<div class="note"> +<p><strong>Note</strong>: There is also a <a href="http://chrisdavidmills.github.io/content-kit-guide/">Content Kit Guide</a> available, to give you more guidance in creating content kits.</p> +</div> + +<h2 id="現在のコンテンツキット">現在のコンテンツキット</h2> + +<ul> + <li><a href="http://mdn.github.io/beginning-programming-content-kit/">Beginners Programming</a>. This kit contains resources you can use to learn and teach general programming principles and the JavaScript language. The teacher will need to know HTML and JavaScript. The students will not need any previous web development knowledge but knowing how the web works and what web pages are will help. The Beginners Programming kit has 8 sections, each of which takes 1-1.5 hours to teach.</li> + <li><a href="http://end3r.github.io/Gamedev-Canvas-Content-Kit/">Beginners Game development with HTML5 Canvas</a>. In this kit you can learn the basics of game development using <a href="/en-US/docs/Web/JavaScript">JavaScript</a> and <a href="/en-US/docs/Web/API/Canvas_API">HTML5 Canvas</a>. All you need is a little prior experience with JavaScript basics.</li> + <li><a href="http://end3r.github.io/Gamedev-Phaser-Content-Kit/">Beginners Game development with Phaser</a>. In this kit you can learn the basics of game development using Phaser, a popular HTML5 game development framework. This differs from the above kit because it doesn't teach you any pure JavaScript, instead giving you expeience of working with a framework. All you need is a little prior experience with JavaScript basics.</li> + <li><a href="https://gist.github.com/callahad/1d0885dd70b157c3978e#file-valence-content-kit-md">Valence</a>. Valence is the public-facing name for the Firefox Developer Tools Adapters, which extend the Firefox WebIDE to allow for remotely debugging pages in Chrome or Safari from within the Firefox Developer Tools. Valence is still in development and is experimental. Valence is distributed as an add-on, which is automatically downloaded and installed by Firefox Developer Edition, though the raw .xpi file is available on <a href="http://archive.mozilla.org/pub/labs/valence/">archive.mozilla.org</a> and its source code is on GitHub. The Valance Content Kit is for an experienced web developer to give a presentation to a group of experienced web developers.</li> + <li><a href="https://github.com/sole/ck-node-firefox">node-firefox</a>. Node-firefox is a series of node.js modules for interacting with Firefox runtimes via the Developer Tools remote debugging protocol. The node-firefox Content Kit is for an experienced web developer to give a presentation to a group of experienced web developers.</li> + <li><a href="https://github.com/chrisdavidmills/html5-captions-and-subtitles-content-kit">Working with HTML5 Video: Adding captions and subtitles</a>. This kit contains everything you might need to present a one hour presentation on HTML5 video captions and subtitles. This includes using the {{htmlelement("track")}} element, WebVTT syntax, CSS extensions, and the difference between captions and subtitles.</li> + <li><a href="http://codingfree.github.io/l10n-content-kit">l10n.js</a>. JavaScript library that enables localization through the native JavaScript method intended for it. There is already a placeholder method for all API calls as specified in the ECMAScript specification and is present in all JavaScript engines.</li> + <li><a href="https://github.com/TatumCreative/mdn-matrix-math">Matrix Math for the Web</a>. This content kit is brief overview of manipulating 3d objects with matrices (a concept from linear algebra.) Matrix math is used heavily in WebGL, but web developers are more familiar with DOM manipulations. This intro divorces the explanation of matrices from the WebGL APIs by using the CSS3 matrix3d transform. It demonstrates translation, scale, and rotation transformations, as well as exploring how to compose a single matrix transform from multiple transforms through matrix multiplication.</li> + <li><a href="https://github.com/TatumCreative/mdn-model-view-projection">WebGL Model View Projection</a>. This content kit explores how to take data within a WebGL project, and project it into the proper spaces to display it on the screen. It assumes a knowledge of basic matrix math using translation, scale, and rotation matrices. It explains the three core matrices that are typically used to represent a 3d object: the model, view and projection matrices.</li> + <li><a href="https://github.com/TatumCreative/mdn-lighting-models">WebGL Lighting Models</a>. Getting a model projected onto the screen using WebGL is only the first step for working in 3d. The next is applying a shading or lighting model to it. This content kit walks through the steps on how to build the classic Lambertian lighting model and the Blinn Phong lighting model.</li> +</ul> + +<h2 id="MDN_コンテンツキットを利用する">MDN コンテンツキットを利用する</h2> + +<p>Hints on using Content Kits before, during, and after a meetup. Note that these points are representative of a general Content Kit — not all points will necessarily apply to all kits.</p> + +<h3 id="会合の前に"><span class="mw-headline" id="Prior_to_a_meetup">会合の前に</span></h3> + +<ol> + <li>Review the content kit and all supporting materials, including relevant MDN articles.</li> + <li>Download the demo project and play with it until you feel comfortable demoing it.</li> + <li>Download the video, so you can play it locally if all else fails.</li> +</ol> + +<h3 id="会合の中で"><span class="mw-headline" id="During_the_meetup">会合の中で</span></h3> + +<ol> + <li>Present the topic, including a live demo (or recorded, if necessary.)</li> + <li>Lead the group in a discussion of the topic, or an activity with the demo project.</li> +</ol> + +<h3 id="会合の後で"><span class="mw-headline" id="After_the_meetup">会合の後で</span></h3> + +<ol> + <li>Submit issues for any problems you encountered with the kit.</li> + <li>Submit pull requests for any changes you made to the kit.</li> +</ol> + +<h2 id="新しい_MDN_コンテンツキットを提案する">新しい MDN コンテンツキットを提案する</h2> + +<p>If you would like to propose a new topic for an MDN Content Kit, please add your topic to <a href="https://devengage.etherpad.mozilla.org/DevMeetupTopics">this etherpad</a> as well as on the <a href="https://lists.mozilla.org/listinfo/mdn">MDN mailing list</a>.</p> + +<p>If you propose a new Content Kit topic, please let us know how you will use the new MDN Content Kit and whether you will provide us feedback. We are looking for proposals for topics that will be used by groups that can provide us with feedback so that we can continue to improve and grow the collection of MDN Content Kits.</p> diff --git a/files/ja/mdn/tools/document_parameters/index.html b/files/ja/mdn/tools/document_parameters/index.html new file mode 100644 index 0000000000..6198f8ea7b --- /dev/null +++ b/files/ja/mdn/tools/document_parameters/index.html @@ -0,0 +1,95 @@ +--- +title: URL 引数と文書メタデータ +slug: MDN/Tools/Document_parameters +tags: + - Documentation + - Kuma + - MDN Meta + - Page-level + - Reference + - Tools +translation_of: MDN/Tools/Document_parameters +--- +<div>{{MDNSidebar}}</div> + +<section id="intro"> +<p id="Introduction"><span class="seoSummary">MDN の Kuma Wiki プラットホームには、外からアクセスする API がありません。代わりに、人間がアクセスできるリソースを機械的に扱いやすいデータに変換する手段を提供するというのが私たちのアプローチです。</span></p> +</section> + +<section id="params"> +<h2 id="URL_GET_parameters" name="URL_GET_parameters">URL の GET 引数</h2> + +<p>すべての Kuma wiki 文書の URL が HTTP GET で取得されたりブラウザーで見られる時に役立つクエリ引数オプションをサポートしています。</p> + +<p>複数のクエリ引数は最初の <kbd>?</kbd> の代わりに <kbd>&</kbd> で区切られます (マクロの例を見てください)。</p> + +<dl> + <dt><code>summary</code></dt> + <dd> + <p>Kuma にページの概要のみを返すよう指示します。 "SEO summary" クラスでマークされたコンテンツがある場合、そのコンテンツが返されます。そのようなコンテンツがない場合、 "Summary" というタイトルのあるコンテンツが返されます。そうならない場合、最初のブロックのコンテンツが返されます。</p> + + <div class="note"><strong>バグのお知らせ:</strong> 現在、 <code>summary</code> 引数は <code>raw</code> 引数も指定しないと文書全体を返すというバグがあります。なお、 <a href="#json-view"><code>$json</code> 代替ビュー</a>を使用して返される JSON から概要を取得することもできます。</div> + </dd> + <dt><code>raw</code></dt> + <dd>Kuma に、ヘッダーやフッターなどのスキン素材のない、ページの生コンテンツを返すよう指示します。これはエディターを手軽に構築するテンプレートやスクリプトを実行しません。</dd> + <dd><strong>例:</strong> <code><a href="https://developer.mozilla.org/ja/docs/Web/Guide/HTML/HTML5?raw">https://developer.mozilla.org/ja/docs/Web/Guide/HTML/HTML5?raw</a></code></dd> + <dt><code>macros</code></dt> + <dd>Kuma にページ内のすべてのテンプレートを実行するよう指示します。 <code>?raw</code> と組み合わせると、これはサイトラッパーを除くすべてをレンダリングした MDN コンテンツを提供します。既定では <code>?raw</code> なしです (つまり、通常のサイト表示です) <code>?raw</code> がある時は既定でオフです。</dd> + <dd><strong>例:</strong> <code><a href="https://developer.mozilla.org/ja/docs/Web/Guide/HTML/HTML5?raw&macros">https://developer.mozilla.org/ja/docs/Web/Guide/HTML/HTML5?raw&macros</a></code></dd> + <dt><code>nomacros</code></dt> + <dd>Kuma にページ内の KumaScript テンプレートを実行しないよう指示します。通常のサイト表示では <code>?macros</code> が既定で「オン」になっていますが、このオプションはオフにします。</dd> + <dd><strong>例:</strong> <code><a href="https://developer.mozilla.org/ja/docs/Web/Guide/HTML/HTML5?nomacros">https://developer.mozilla.org/ja/docs/Web/Guide/HTML/HTML5?nomacros</a></code></dd> + <dt><code>include</code></dt> + <dd>Kuma に <code>noinclude</code> クラスを持つブロックを除くように命じます。これは単体のページではなく、他のページに含まれた場合のような出力を得るのに便利です。よくサンプルコードなどを除きます (いつもではありませんが)。</dd> + <dd><strong>例:</strong> <code><a href="https://developer.mozilla.org/ja/docs/XUL/Attribute/align?raw&macros&include">https://developer.mozilla.org/ja/docs/XUL/Attribute/align?raw&macros&include</a></code></dd> + <dt><code>section=id</code></dt> + <dd>Kuma に指定したアンカー名を持つセクションのみのコンテンツを返すように指示します。</dd> + <dd><strong>例:</strong> + <ul> + <li><code><a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters?raw&section=params">https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters?raw&section=params</a></code><br> + (...また、もっと興味深いものは...)</li> + <li><code><a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters?raw&macros&section=params">https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters?raw&macros&section=params</a></code></li> + </ul> + + <div class="note"><strong>バグのお知らせ:</strong> 現在、 <code>section</code> 引数は <code>raw</code> 引数も使用しないと文書全体を返すというバグがあります。</div> + </dd> + <dt><code>expand</code></dt> + <dd> + <p><code>$children</code> ビューと連結して、サブページごとの詳細情報つきの JSON レスポンスを展開します。これは各サブページごとの <code>$children</code> と <code>$json</code> の連結のように動作します。この方法は、サブページのタグについて学べます。</p> + + <p><strong>例:</strong> <code><a href="https://developer.mozilla.org/ja/docs/Web/Guide/HTML/HTML5$children?expand">https://developer.mozilla.org/ja/docs/Web/Guide/HTML/HTML5$children?expand</a></code></p> + </dd> +</dl> +</section> + +<section id="metadata"> +<h2 id="Document_metadata_resources" name="Document_metadata_resources">文書のメタデータリソース</h2> + +<p>文書の URL のレスポンスを微調整するための引数と一緒に、 URL 接尾辞で指定される文書の代替ビューもいくつかあります。</p> + +<dl> + <dt><code>$toc</code></dt> + <dd>Kuma に HTML のページの目次のみを返すよう命じます。順序付きリスト (つまり {{HTMLElement("ol")}}) として返されます。</dd> + <dd><strong>例:</strong> <code><a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters$toc">https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters$toc</a></code></dd> + <dt id="json-view"><code>$json</code></dt> + <dd>Kuma に JSON オブジェクトでページを記述するよう命じます。このオブジェクトは基本的に、 KumaScript の処理 <code>wiki.getPage()</code> を使用して得られるものと同じです。</dd> + <dd><strong>例:</strong> <code><a href="https://developer.mozilla.org/ja/docs/Web/Guide/HTML/HTML5$json">https://developer.mozilla.org/ja/docs/Web/Guide/HTML/HTML5$json</a></code></dd> + <dt><code>$children</code></dt> + <dd>Kuma にページのトピックの子を JSON で列挙するよう命じます。このオブジェクトは基本的に、 KumaScript の処理 <code>pages.subpages()</code> を使用して得られるものと同じです。</dd> + <dd><strong>例:</strong> <code><a href="https://developer.mozilla.org/ja/docs/Web/Guide/HTML/HTML5$children +">https://developer.mozilla.org/ja/docs/Web/Guide/HTML/HTML5$children</a></code></dd> + <dd>(これは <code>?expand</code> 引数と共に使用して、もっと詳細のレスポンスを得ることもできます。)</dd> + <dt><code>$compare</code></dt> + <dd>必須のクエリ引数 <code>?from</code> および <code>?to</code>で指定されたリビジョン間のソーステキスト行の違いを表示します。</dd> + <dd><strong>例:</strong> <code><a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters$compare?to=911697&from=911067">https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters$compare?to=911697&from=911067</a></code></dd> + <dt><code>$edit</code></dt> + <dd>指定された文書の現在のリビジョンを、表示する代わりに編集します。</dd> + <dd><strong>例:</strong> <code><a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters$edit">https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters$edit</a></code></dd> + <dt><code>$history</code></dt> + <dd>指定された文書の内容を表示する代わりに、最新の10リビジョンのリビジョン履歴を表示します。履歴全体は、クエリ引数の値に <code>?limit=all</code> を付けることで要求できます。</dd> + <dd><strong>例:</strong> <code><a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters$history?limit=all">https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters$history?limit=all</a></code></dd> + <dt><code>$revision</code></dt> + <dd>文書の "<code>/</code>" の後に指定された番号のリビジョンを表示します。</dd> + <dd><strong>例:</strong> <code><a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters$revision/915141">https://developer.mozilla.org/ja/docs/MDN/Contribute/Tools/Document_parameters$revision/915141</a></code></dd> +</dl> +</section> diff --git a/files/ja/mdn/tools/feeds/index.html b/files/ja/mdn/tools/feeds/index.html new file mode 100644 index 0000000000..6d30d1a342 --- /dev/null +++ b/files/ja/mdn/tools/feeds/index.html @@ -0,0 +1,53 @@ +--- +title: MDN の Feeds API について +slug: MDN/Tools/Feeds +tags: + - Kuma + - MDN Meta + - Site-wide + - ツール + - リファレンス +translation_of: MDN/Tools/Feeds +--- +<div>{{MDNSidebar}}</div><p>MDN の wiki では、サイトの更新内容を追跡する為にフィード API が提供されています。この API はまだ作成中であるかもしれませんが、この情報は役立つかもしれません。</p> + +<h2 id="Accessing_the_feeds" name="Accessing_the_feeds">フィードへのアクセス</h2> + +<p>フィードは次の様な形式の ベース URL から始まります。</p> + +<pre class="syntaxbox notranslate">https://developer.mozilla.org/<strong><locale></strong>/docs/feeds/<strong><format></strong>/</pre> + +<p>ベース URL 内の各プレースホルダーはそれぞれ次の意味を持ちます。</p> + +<ul> + <li><code><locale></code> は、標準のロケール文字列の内の一つとします。英語版の内容を取得するのであれば "en-US"、日本語なら "ja" を指定します。URL に <code>?all_locales</code> オプションを追加しない限り、そのロケールの記事のエントリを含むようにフィルターリングされます。</li> + <li><code><format></code> は、フィードの形式です。「 <code>rss</code> 」、「 <code>atom</code> 」、「 <code>json</code> 」の何れかを選択可能です。</li> +</ul> + +<p><code>json</code> 形式を使用する場合、オプションとして <a href="http://en.wikipedia.org/wiki/JSONP">the JSONP convention</a> で JavaScript としてデータを読み込むための <code>?callback=<callback name></code> クエリパラメーターが指定可能です。</p> + +<h2 id="Available_Feeds" name="Available_Feeds">購読可能フィード</h2> + +<dl> + <dt><code>all</code></dt> + <dd>最近の記事の変更すべてを編集日付順で。新規に作成された記事も含む。すべての変更は各記事のフィードのエントリーに結ばれています。例えば:<a href="https://developer.mozilla.org/ja/docs/feeds/rss/all"> https://developer.mozilla.org/ja/docs/feeds/rss/all</a></dd> + <dt><code>revisions</code></dt> + <dd>特定の記事のリビジョンを編集日付順で。新規作成も含む。各リビジョンはフィードの別々のエントリーを持ちます。例えば: <a href="https://developer.mozilla.org/ja/docs/feeds/atom/revisions">https://developer.mozilla.org/ja/docs/feeds/atom/revisions</a></dd> + <dt><code>tag/<em><tagname></em></code></dt> + <dd>フィードの指定タグの付いた記事の更新情報のみを編集日付順で取得。例えば:<a href="https://developer.mozilla.org/ja/docs/feeds/json/tag/CSS?callback=loadFeed"> https://developer.mozilla.org/ja/docs/feeds/json/tag/CSS?callback=loadFeed</a></dd> + <dt><code>files</code></dt> + <dd>最近のファイルのアップロードまたは変更。例えば:<a href="https://developer.mozilla.org/ja/docs/feeds/atom/files"> https://developer.mozilla.org/ja/docs/feeds/atom/files</a></dd> + <dt><code>l10n-updates</code></dt> + <dd>翻訳ページの最終更新時以降に翻訳の元となる言語の記事が変更された記事のリスト (つまり、他の言語から翻訳された記事で、元の言語の記事が変更された場合)。例えば:<a href="https://developer.mozilla.org/fr/docs/feeds/atom/l10n-updates"> https://developer.mozilla.org/fr/docs/feeds/atom/l10n-updates</a></dd> + <dt><code>needs-review[/<em><reviewtype></em>]</code></dt> + <dd>要レビューとされた記事のリスト。<code>technical</code> 、<code>editorial</code> 、<code>kumascript</code> の何れかに絞って取得する事も可能。 + <ul> + <li><a href="https://developer.mozilla.org/ja/docs/feeds/json/needs-review">https://developer.mozilla.org/ja/docs/feeds/json/needs-review</a></li> + <li><a href="https://developer.mozilla.org/fr/docs/feeds/rss/needs-review/technical">https://developer.mozilla.org/fr/docs/feeds/rss/needs-review/technical</a></li> + <li><a href="https://developer.mozilla.org/ja/docs/feeds/atom/needs-review/editorial">https://developer.mozilla.org/ja/docs/feeds/atom/needs-review/editorial</a></li> + <li><a href="https://developer.mozilla.org/ja/docs/feeds/atom/needs-review/kumascript">https://developer.mozilla.org/ja/docs/feeds/atom/needs-review/kumascrip</a></li> + </ul> + </dd> +</dl> + +<p> </p> diff --git a/files/ja/mdn/tools/index.html b/files/ja/mdn/tools/index.html new file mode 100644 index 0000000000..19f4f4ba50 --- /dev/null +++ b/files/ja/mdn/tools/index.html @@ -0,0 +1,14 @@ +--- +title: MDN のツール +slug: MDN/Tools +tags: + - Landing + - MDN Meta + - Tools +translation_of: MDN/Tools +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p>MDN は数々の機能を提供して、進行を追跡すること、内容を管理すること、最新の変更をサイトへ反映することを容易にしようと努めています。</p> + +<p>{{LandingPageListSubpages}}</p> diff --git a/files/ja/mdn/tools/kumascript/index.html b/files/ja/mdn/tools/kumascript/index.html new file mode 100644 index 0000000000..2a2a5132d2 --- /dev/null +++ b/files/ja/mdn/tools/kumascript/index.html @@ -0,0 +1,471 @@ +--- +title: KumaScript +slug: MDN/Tools/KumaScript +tags: + - Kuma + - KumaScript + - MDN Meta + - NeedsContent + - Site-wide + - ガイド + - ツール +translation_of: MDN/Tools/KumaScript +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">MDN を構築している <a href="/ja/docs/MDN/Kuma">Kuma</a> プラットフォームにおいて、 wiki 上のコンテンツを自動化するテンプレートシステムは <a class="link-https" href="https://github.com/mdn/kumascript">KumaScript</a> と呼ばれています。 KumaScript はサーバー側 JavaScript で実行されており、 <a class="external" href="https://nodejs.org/en/">Node.js</a> を使用して実装されています。</span>この記事は、 KumaScript の使い方について基本的な情報を提供するものです。</p> + +<p>詳細な概要や KumaScript の Q&A については、 MDN 開発チームの <a href="https://vreplay.mozilla.com/replay/showRecordDetails.html?sortBy=date&viewCount=1&currentPage=1&groupBy=combo&roomFilter=&usernameFilter=&searchFilter=&usernameFullFilter=&myManager=-1&adminManager=0&webCast=0&command=&recId=1082&auxMessage=&auxMessage1=&lang=en&langChanged=&tenantFilter=&securityTab=">KumaScript Fireside Chat</a> を見ていてください (ミーティングはビデオで10分で開始します)。 KumaScript は、以前の MDN で使われていたプラットフォームであり、 MindTouch のためのテンプレート言語であった DekiScript を置き換えました。</p> + +<h3 id="What_is_KumaScript" name="What_is_KumaScript">KumaScript とは</h3> + +<ul> + <li>文書間で繰り返し現れるコンテンツの再利用やローカライズを行う手段 (互換性のラベル、セクションナビゲーション、警告バナーなど)。</li> + <li>他の文書からコンテンツを引用して文書を構築する手段。</li> + <li>他のウェブサイトやサービス (Bugzilla など) からコンテンツを取得して含める手段</li> +</ul> + +<h3 id="What_KumaScript_is_not" name="What_KumaScript_is_not">KumaScript にはないもの</h3> + +<ul> + <li>KumaScript は、フォーム送信を受け付けるような対話型スクリプトには対応していません。</li> + <li>KumaScript には、データベースやファイルにアクセスしたり、情報を永続的に格納したりする仕組みはありません。</li> + <li>KumaScript は、ログイン中のユーザー情報に基づくサイトのパーソナライズには対応していません。</li> + <li>KumaScript は、ユーザー情報にアクセスすることはできず、コンテンツとページのメタデータにのみアクセス可能です。</li> +</ul> + +<h2 id="Basics" name="Basics">基本</h2> + +<p>KumaScript は MDN で<a href="https://github.com/mde/ejs">埋め込み JavaScript テンプレート</a>に利用されています。これらのテンプレートは MDN の筆者ならば誰でも文書内で、マクロを使用して呼び出すことができます。</p> + +<p>KumaScript のスクリプトは<em>テンプレート</em>であり、それぞれのテンプレートは Github の <a href="https://github.com/mdn/kumascript/tree/master/macros">KumaScript リポジトリの macros ディレクトリ</a>に格納されているファイルです。テンプレートは以下のようなものです。</p> + +<pre class="brush: js no-line-numbers notranslate"><% for (var i = 0; i < $0; i++) { %> + Hello #<%= i %> +<% } %></pre> + +<p>テンプレートは wiki コンテンツのどこからでも<em>マクロ</em>で呼び出すことができます。マクロは次のようなものです。</p> + +<pre class="brush: none no-line-numbers notranslate">\{{hello(3)}}</pre> + +<p>マクロの出力は以下のようなものです。</p> + +<pre class="brush: html no-line-numbers notranslate">Hello #0 +Hello #1 +Hello #2</pre> + +<h3 id="Macro_syntax" name="Macro_syntax">マクロの構文</h3> + +<p>KumaScript のテンプレートは、以下のようにドキュメントのコンテンツの中でマクロとして呼び出すことができます。</p> + +<pre class="brush: none no-line-numbers notranslate">\{{templateName("arg0", "arg1", ..., "argN")}}</pre> + +<p>マクロの構文は、以下の規則に基づいて構成されます。</p> + +<ul> + <li>マクロのコードは <code>\{{</code> より始まり、 <code>\}}</code> で終わります。</li> + <li>マクロの最初の部分はテンプレートの名前です。この名前の小文字の値は、 <a href="https://github.com/mdn/kumascript/tree/master/macros">KumaScript の macros ディレクトリ</a>以下のファイル名の小文字の値に一致します。</li> + <li>テンプレートは引数を受け付けます。括弧内にコンマ区切りで複数の引数を記述する事ができます。</li> + <li>数値以外の引数は引用符で囲む必要があります。数値は囲む必要はありません。</li> +</ul> + +<h4 id="Using_JSON_as_a_macro_parameter" name="Using_JSON_as_a_macro_parameter">マクロの引数に JSON を用いる</h4> + +<p>半実験的な機能 (動作保証なし) として、以下のように引数が一つだけの場合は、引数に JSON オブジェクトを指定できます。</p> + +<pre class="brush: none no-line-numbers notranslate">\{{templateName(<code class="language-json">{ "Alpha": "one", "Beta": ["a", "b", "c"], "Foo": "https:\/\/mozilla.org\/" }</code>)}}</pre> + +<p>このマクロからのデータは、テンプレートコード内で <code class="language-javascript">$0</code> 引数のオブジェクトとして利用できます (例えば、 <code>$0.Alpha</code>, <code>$0.Beta</code>, <code>$0.Foo</code>)。これにより、引数の単純なリストで実現することが難しい又は不可能な複雑なデータ構造を、マクロ引数で表すことができます。</p> + +<p>なお、この引数の形はとても繊細です。 — 正確に <a href="http://json.org/" title="http://json.org/">JSON の構文</a>に従っていなければならず、間違いを犯しやすいエスケープ文字の要件が求められます (例えば、すべてのスラッシュをエスケープするなど)。疑わしい場合は、 <a href="http://jsonlint.com/" title="http://jsonlint.com/">JSON をバリデーターに掛けてみてください</a>。</p> + +<h4 id="How_to_write_in_text" name="How_to_write_in_text">「\{{」を記述する方法</h4> + +<p>"<code>\{{</code>" という文字の並びはマクロの開始を示すため、実際にページ内で "<code>\{{</code>" および "<code>}}</code>" を使用したい場合は問題になります。おそらく <code>DocumentParsingError</code> メッセージが発生するでしょう。</p> + +<p>この場合、 <code>\\{</code> のように最初の中括弧をバックスラッシュでエスケープすることができます。</p> + +<h3 id="Template_Syntax" name="Template_Syntax">テンプレートの構文</h3> + +<p>それぞれの KumaScript テンプレートは、 <a href="https://github.com/mdn/kumascript/tree/master/macros">KumaScript の macros ディレクトリ</a>に格納されているファイルです。これらのファイルは GitHub 上の何らかのオープンソースプロジェクトのファイルとして作成したり編集したりします (詳しくは <a href="https://github.com/mdn/kumascript">the KumaScript README</a> をご覧ください)。</p> + +<p>KumaScript テンプレートは、いくつかの簡単な規則で、<a href="https://ejs.co">組込み JavaScript テンプレートエンジン</a>によって処理されます。</p> + +<ul> + <li>テンプレート内では、マクロから渡された引数は <code>$0</code>, <code>$1</code>, <code>$2</code>, などのような変数として利用できます。引数のリスト全体は、テンプレート内で変数 <code>arguments</code> として利用できます。</li> + <li>多くのテキストは出力として扱われ、出力ストリームに入ります。</li> + <li>JavaScript の変数や式は、以下のブロックを用いて出力ストリームに挿入可能です。 + <ul> + <li><code class="language-ejs"><%= expr %></code> — 出力される前に HTML エスケープされた JavaScript の式の値 (<code><</code> および <code>></code> は <code>&lt;</code> および <code>&gt;</code> となる)</li> + <li><code class="language-ejs"><%- expr %></code> — エスケープされない JavaScript の式の値 (マークアップを動的に構築したり、マークアップを含むことができる他のテンプレートの結果に使用してください)</li> + <li>このブロック直下にセミコロンを含めるとエラーとなる。</li> + </ul> + </li> + <li><code class="language-ejs"><%</code> と <code>%></code> の間は JavaScript として解釈される。すなわち、ループ、条件文、関数などを含めることが可能。</li> + <li><code class="language-ejs"><% %></code> ブロック内は出力ストリームに含まれない。ブロック内の変数などをブロック外で使用する場合は、以下のように <code><%= %></code> を用いる。 + <pre class="brush: js notranslate"><% for (var i = 0; i < $0; i++) { %> + Hello #<%= i %> +<% } %></pre> + + <p>Note how the JavaScript code is contained in <code class="language-ejs"><% ... %></code>, and output happens in the space between <code class="language-ejs">%> ... <%</code>. The <code>for</code> loop in JS can begin with one <code class="language-ejs"><% %></code> block, transition to output mode, and finish up in a second <code class="language-ejs"><% %></code> JS block.</p> + </li> + <li>EJS の構文の詳細については、<a href="https://ejs.co">上流モジュールのドキュメント</a>でご確認ください。</li> +</ul> + +<h3 id="Tips">Tips</h3> + +<p>マクロのリストと、マクロが MDN でどの様に使用されているか<a href="/ja/dashboards/macros">マクロダッシュボード</a>で確認することができます。</p> + +<h2 id="Advanced_Features" name="Advanced_Features">より高度な機能</h2> + +<p>KumaScript には前章までに紹介したもの以外に、より高度な機能もあります。</p> + +<h3 id="Environment_variables" name="Environment_variables">環境変数</h3> + +<p>When the wiki makes a call to the KumaScript service, it passes along some context on the current document that KumaScript makes available to templates as variables:</p> + +<dl> + <dt><code>env.path</code></dt> + <dd>現在の wiki 文書へのパス</dd> + <dt><code>env.url</code></dt> + <dd>現在の wiki 文書への 絶対 URL</dd> + <dt><code>env.id</code></dt> + <dd>現在の wiki 文書のユニーク ID</dd> + <dt><code>env.files</code></dt> + <dd>An array of the files attached to the current wiki document; each object in the array is as described under {{ anch("File objects") }} below</dd> + <dt><code>env.review_tags</code></dt> + <dd>記事のレビュータグ配列 ("technical"、 "editorial"など。)</dd> + <dt><code>env.locale</code></dt> + <dd>現在の wiki 文書のロケール</dd> + <dt><code>env.title</code></dt> + <dd>現在の wiki 文書のタイトル</dd> + <dt><code>env.slug</code></dt> + <dd>現在の wiki 文書の URL スラッグ</dd> + <dt><code>env.tags</code></dt> + <dd>現在の wiki 文書に付与されたタグの名称のリスト</dd> + <dt><code>env.modified</code></dt> + <dd>現在の wiki 文書の最終更新日を示すタイムスタンプ</dd> + <dt><code>env.cache_control</code></dt> + <dd><code>Cache-Control</code> header sent in the request for the current wiki document, useful in deciding whether to invalidate caches</dd> +</dl> + +<h4 id="File_objects" name="File_objects">File オブジェクト</h4> + +<p>個々の file オブジェクトは以下の様なフィールドを持ちます。</p> + +<dl> + <dt><code>title</code></dt> + <dd>添付ファイルのタイトル</dd> + <dt><code>description</code></dt> + <dd>現行版の添付ファイルに関する説明</dd> + <dt><code>filename</code></dt> + <dd>添付ファイルのファイル名</dd> + <dt><code>size</code></dt> + <dd>添付ファイルのサイズ（※単位 = bytes )</dd> + <dt><code>author</code></dt> + <dd>添付ファイルをアップロードした人のユーザ名</dd> + <dt><code>mime</code></dt> + <dd>添付ファイルの MIME type</dd> + <dt><code>url</code></dt> + <dd>添付ファイルの URL</dd> +</dl> + +<h4 id="Working_with_tag_lists" name="Working_with_tag_lists">タグリストでの作業</h4> + +<p>The <code>env.tags</code> and <code>env.review_tags</code> variables return arrays of tags. You can work with these in many ways, of course, but here are a couple of suggestions.</p> + +<h5 id="Looking_to_see_if_a_specific_tag_is_set">Looking to see if a specific tag is set</h5> + +<p>You can look to see if a specific tag exists on a page like this:</p> + +<pre class="brush: js notranslate">if (env.tags.indexOf("tag") != −1) { + // The page has the tag "tag" +} +</pre> + +<h5 id="Iterating_over_all_the_tags_on_a_page">Iterating over all the tags on a page</h5> + +<p>You can also iterate over all the tags on a page, like this:</p> + +<pre class="brush: js notranslate">env.tag.forEach(function(tag) { + // do whatever you need to do, such as: + if (tag.indexOf("a") == 0) { + // this tag starts with "a" - woohoo! + } +});</pre> + +<h3 id="APIs_and_Modules" name="APIs_and_Modules">API とモジュール</h3> + +<p>KumaScript offers some built-in methods and APIs for KumaScript macros. Macros can also use <code>module.exports</code> to export new API methods.</p> + +<p>KumaScript では、ビルトインのユーティリティ API だけでなく、wiki 文書として編集可能なモジュール内で新規の API を定義する機能も提供されています。</p> + +<h4 id="Built-in_methods" name="Built-in_methods">ビルトインメソッド</h4> + +<p>This manually-maintained documentation is likely to fall out of date with the code. With that in mind, <a class="link-https" href="https://github.com/mdn/kumascript/blob/master/lib/kumascript/api.js#L175" title="https://github.com/mdn/kumascript/blob/master/lib/kumascript/api.js#L208">you can always check out the latest state of built-in APIs in the KumaScript source</a>. But here is a selection of useful methods exposed to templates:</p> + +<dl> + <dt><code class="language-javascript">md5(string)</code></dt> + <dd>与えられた文字列の MD5 16 進ダイジェストを返す</dd> + <dt><code class="language-javascript">template("name", ["arg0", "arg1", ..., "argN"])</code></dt> + <dd> + <p>Executes and returns the result of the named template with the given list of parameters.</p> + + <p>Example: <code class="language-javascript"><%- template("warning", ["foo", "bar", "baz"]) %></code>.</p> + + <p>Example using the <code>DOMxRef</code> macro: <code class="language-javascript"><%- template("DOMxRef", ["Event.bubbles", "bubbles"]) %></code>.</p> + + <p>This is a JavaScript function. So, if one of the parameters is an arg variable like $2, do not put it in quotes. Like this: <code class="language-javascript"><%- template("warning", [$1, $2, "baz"]) %></code>. If you need to call another template from within a block of code, do not use <code><%</code> ... <code>%></code>. Example: <code class="language-javascript">myvar = "<li>" + template("LXRSearch", ["ident", "i", $1]) + "</li>";</code></p> + </dd> + <dt><code class="language-javascript">require(name)</code></dt> + <dd>Loads another template as a module; any output is ignored. Anything assigned to <code class="language-javascript">module.exports</code> in the template is returned.</dd> + <dd>Used in templates like so: <code class="language-javascript"><% const my_module = require('MyModule'); %></code>.</dd> + <dt><code class="language-javascript">cacheFn(key, timeout, function_to_cache)</code></dt> + <dd>Using the given key and cache entry lifetime, cache the results of the given function. Honors the value of <code>env.cache_control</code> to invalidate cache on <code>no-cache</code>, which can be sent by a logged-in user hitting shift-refresh.</dd> + <dt><code class="language-javascript">request</code></dt> + <dd>Access to <a class="link-https" href="https://github.com/mikeal/request" title="https://github.com/mikeal/request"><code>mikeal/request</code></a>, a library for making HTTP requests. Using this module in KumaScript templates is not yet very friendly, so you may want to wrap usage in module APIs that simplify things.</dd> + <dt><code class="language-javascript">log.debug(string)</code></dt> + <dd>Outputs a debug message into the script log on the page (i.e. the big red box that usually displays errors).</dd> +</dl> + +<h4 id="Built-in_API_modules" name="Built-in_API_modules">組込み API モジュール</h4> + +<p>There are a set of built in API that are automatically loaded and made available to every template by the environment script.</p> + +<p>For the most part, these attempt to provide stand-ins for legacy DekiScript features to ease template migration. But, going forward, these can be used to share common variables and methods between templates:</p> + +<ul> + <li><code>kuma.*</code> - <a href="https://github.com/mdn/kumascript/blob/master/src/api/kuma.js">Kuma</a></li> + <li><code>MDN.*</code> - <a href="https://github.com/mdn/kumascript/blob/master/src/api/mdn.js">MDN:Common</a></li> + <li><code>page.*</code> - <a href="https://github.com/mdn/kumascript/blob/master/src/api/page.js">DekiScript:Page</a></li> + <li><code>string.*</code> - <a href="https://github.com/mdn/kumascript/blob/master/src/api/string.js">DekiScript:String</a></li> + <li><code>uri.*</code> - <a class="link-https" href="https://github.com/mdn/kumascript/blob/master/src/api/uri.js">DekiScript:Uri</a></li> + <li><code>web.*</code> - <a class="link-https" href="https://github.com/mdn/kumascript/blob/master/src/api/web.js">DekiScript:Web</a></li> + <li><code>wiki.*</code> - <a class="link-https" href="https://github.com/mdn/kumascript/blob/master/src/api/wiki.js">DekiScript:Wiki</a></li> +</ul> + +<p>You can see the most up to date list of methods under <code>kuma</code> from <a href="https://github.com/mdn/kumascript/blob/master/src/api/kuma.js">the KumaScript source code</a>, but here are a few:</p> + +<dl> + <dt><code class="language-javascript">kuma.inspect(object)</code></dt> + <dd>Renders any JS object as a string, handy for use with <code>log.debug()</code>. See also: <a href="https://nodejs.org/api/util.html#util_util_inspect_object_options">node.js <code class="language-javascript">util.inspect()</code></a>.</dd> + <dt><code class="language-javascript">kuma.htmlEscape(string)</code></dt> + <dd>Escapes the characters <code>&, <, >, "</code> to <code>&amp, &lt;, &gt;, &quot;</code>, respectively.</dd> + <dt><code class="language-javascript">kuma.url</code></dt> + <dd>See also: <a href="http://nodejs.org/api/url.html">node.js <code>url</code> module</a>.</dd> + <dt><code class="language-javascript">kuma.fetchFeed(url)</code></dt> + <dd>Fetch an RSS feed and parse it into a JS object. See also: <a href="https://github.com/mdn/kumascript/blob/master/macros/InsertFeedLinkList.ejs"><code>InsertFeedLinkList</code></a></dd> +</dl> + +<h4 id="Creating_modules" name="Creating_modules">モジュールの作成</h4> + +<p>Using the built-in <code>require()</code> method, you can load a template as a module to share common variables and methods between templates. A module can be defined in a template like this:</p> + +<pre class="brush: js notranslate"><% +module.exports = { + add: function (a, b) { + return a + b; + } +} +%></pre> + +<p>Assuming this template is saved under <a href="https://github.com/mdn/kumascript/tree/master/macros">https://github.com/mdn/kumascript/tree/master/macros</a> as <code>MathLib.ejs</code>, you can use it in another template like so:</p> + +<pre class="brush: js notranslate"><% +var math_lib = require("MathLib"); +%> +The result of 2 + 2 = <%= math_lib.add(2, 2) %></pre> + +<p>このテンプレートの出力は以下の様になるでしょう。</p> + +<pre class="brush: html no-line-numbers notranslate">The result of 2 + 2 = 4</pre> + +<h2 id="Tips_and_caveats">Tips and caveats</h2> + +<h3 id="Debugging" name="Debugging">デバッグ</h3> + +<p>A useful tip when debugging. You can use the <code>log.debug()</code> method to output text to the scripting messages area at the top of the page that's running your template. Note that you need to be really sure to remove these when you're done debugging, as they're visible to all users! To use it, just do something like this:</p> + +<pre class="brush: js no-line-numbers notranslate"><%- log.debug("Some text goes here"); %></pre> + +<p>You can, of course, create more complex output using script code if it's helpful.</p> + +<h3 id="Caching" name="Caching">キャッシュ</h3> + +<p>KumaScript templates are heavily cached to improve performance. For the most part, this works great to serve up content that doesn't change very often. But, as a logged-in user, you have two options to force a page to be regenerated, in case you notice issues with scripting:</p> + +<ul> + <li>Hit Refresh in your browser. This causes KumaScript to invalidate its cache for the content on the current page by issuing a request with a <code>Cache-Control: max-age=0</code> header.</li> + <li>Hit Shift-Refresh in your browser. This causes KumaScript to invalidate cache for the current page, as well as for any templates or content used by the current page by issuing a request with a <code>Cache-Control: no-cache</code> header.</li> +</ul> + +<h3 id="Using_search_keywords_to_open_template_pages" name="Using_search_keywords_to_open_template_pages">検索キーワードを使用してテンプレートページを開く</h3> + +<p>When using templates, it's common to open the template's code in a browser window to review the comments at the top, which are used to document the template, its parameters, and how to use it properly. To quickly access templates, you can create a Firefox <a href="http://kb.mozillazine.org/Using_keyword_searches">search keyword</a>, which gives you a shortcut you can type in the URL box to get to a template more easily.</p> + +<p>To create a search keyword, open the bookmarks window by choosing "Show all bookmarks" in the Bookmarks menu, or by pressing <kbd>Control+Shift+B</kbd> (<kbd>Command+Shift+B</kbd> on Mac). Then from the utility ("Gear") menu in the Library window that appears, choose "New Bookmark...".</p> + +<p>This causes the bookmark editing dialog to appear. Fill that out as follows:</p> + +<dl> + <dt>Name</dt> + <dd>A suitable name for your search keyword; "Open MDN Template" is a good one.</dd> + <dt>Location</dt> + <dd><code>https://github.com/mdn/kumascript/blob/master/macros/%s</code></dd> + <dt>Tags{{Optional_Inline}}</dt> + <dd>A list of tags used to organize your bookmarks; these are entirely optional and what (if any) tags you use is up to you.</dd> + <dt>Keyword</dt> + <dd>The shortcut text you wish to use to access the template. Ideally, this should be something short and quick to type, such as simply "t" or "mdnt".</dd> + <dt>Description{{Optional_Inline}}</dt> + <dd>A suitable description explaining what the search keyword does.</dd> +</dl> + +<p>The resulting dialog looks something like this:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/14432/Screen%20Shot%202016-11-28%20at%203.08.39%20PM.png" style="height: 289px; width: 500px;"></p> + +<p>Then click the "Add" button to save your new search keyword. From then on, typing your keyword, then a space, then the name of a macro will open that macro in your current tab. So if you used "t" as the keyword, typing <kbd>t ListSubpages</kbd> will show you the page at {{TemplateLink("ListSubpages")}}.</p> + +<h2 id="Cookbook" name="Cookbook">クックブック</h2> + +<p>This section will list examples of common patterns for templates used on MDN, including samples of legacy DekiScript templates and their new KumaScript equivalents.</p> + +<h3 id="Force_templates_used_on_a_page_to_be_reloaded">Force templates used on a page to be reloaded</h3> + +<p>It bears repeating: To force templates used on a page to be reloaded after editing, hit Shift-Reload. Just using Reload by itself will cause the page contents to be regenerated, but using cached templates and included content. A Shift-Reload is necessary to invalidate caches beyond just the content of the page itself.</p> + +<h3 id="Recovering_from_.22Unknown_Error.22" name="Recovering_from_.22Unknown_Error.22">「不明なエラー」からの回復</h3> + +<p>ページ読込時に、時折、このようなスクリプティング・メッセージが表示される事があります。</p> + +<pre class="brush: none no-line-numbers notranslate">Kumascript service failed unexpectedly: <class 'httplib.BadStatusLine'></pre> + +<p>これはおそらく、 KumaScript サービスの一時的な障害です。ページの再読込みでこの問題が解決する事があります。これで問題が解決しない場合はスーパーリロード（<kbd><kbd>shift</kbd> + <kbd>F5</kbd></kbd>）を試してみて下さい。これらの試みの後もエラーが解消されない場合は、<a class="link-https" href="https://bugzilla.mozilla.org/enter_bug.cgi?product=mozilla.org&format=itrequest">file an IT bug</a> for Mozilla Developer Network to ask for an investigation.</p> + +<h3 id="Broken_wiki.languages_マクロ">Broken wiki.languages() マクロ</h3> + +<p>幾つかのページで、以下の様なスクリプトエラーメッセージを見かける場合があるでしょう。</p> + +<pre class="brush: none; no-line-numbers notranslate">Syntax error at line 436, column 461: Expected valid JSON object as the parameter of the preceding macro but...</pre> + +<p>その様なページを編集状態にした場合、ページ下部に以下の様なマクロが見つかるかもしれません。</p> + +<pre class="brush: none no-line-numbers notranslate">\{{ wiki.languages(<code class="language-json">{ "zh-tw": "zh_tw/Core_JavaScript_1.5_教學/JavaScript_概要", ... }</code>) }}</pre> + +<p>To fix the problem, just delete the macro. Or, replace the curly braces on either side with HTML comments <code><!-- --></code> to preserve the information, like so:</p> + +<pre class="brush: html no-line-numbers notranslate"><!-- wiki.languages({ "zh-tw": "zh_tw/Core_JavaScript_1.5_教學/JavaScript_概要", ... }) --></pre> + +<p>Because Kuma supports localization differently, these macros aren't actually needed any more. But, they've been left intact in case we need to revisit the relationships between localized pages. Unfortunately, it seems like migration has failed to convert some of them properly.</p> + +<h3 id="Finding_the_Current_Pages_Language" name="Finding_the_Current_Page's_Language">ページの言語の取得</h3> + +<p>In KumaScript, the locale of the current document is exposed as an environment variable:</p> + +<pre class="brush: js no-line-numbers notranslate">const lang = env.locale;</pre> + +<p>The <code>env.locale</code> variable should be reliable and defined for every document.</p> + +<h3 id="Reading_the_contents_of_a_page_attachment">Reading the contents of a page attachment</h3> + +<p>You can read the contents of an attached file by using the <code>mdn.getFileContent()</code> function, like this:</p> + +<pre class="brush: js notranslate"><% + let contents = mdn.getFileContent(fileUrl); + // ... do stuff with the contents ... +%> +</pre> + +<p>or</p> + +<pre class="brush: js no-line-numbers notranslate"><%- mdn.getFileContent(fileObject); %> +</pre> + +<p>In other words, you may specify either the URL of the file to read or as a file object. The file objects for a page can be accessed through the array <code>env.files</code>. So, for example, to embed the contents of the first file attached to the article, you can do this:</p> + +<pre class="brush: js no-line-numbers notranslate"><%- mdn.getFileContent(env.files[0]); %> +</pre> + +<div class="blockIndicator note"> +<p><strong>Note:</strong> You probably don't want to try to embed the contents of a non-text file this way, as the raw contents would be injected as text. This is meant to let you access the contents of text attachments.</p> +</div> + +<p>If the file isn't found, an empty string is returned. There is currently no way to tell the difference between an empty file and a nonexistent one. But if you're putting empty files on the wiki, you're doing it wrong.</p> + +<h3 id="Localizing_template_content" name="Localizing_template_content">テンプレートのローカライズ</h3> + +<p>Templates are not translated like wiki pages, rather any single template might be used for any number of locales.</p> + +<p>So the main way to output content tailored to the current document locale is to pivot on the value of <code>env.locale</code>. There are many ways to do this, but a few patterns are common in the conversion of legacy DekiScript templates:</p> + +<h4 id="Ifelse_blocks_in_KumaScript" name="Ifelse_blocks_in_KumaScript">If/else ブロックを用いる例</h4> + +<p>The KumaScript equivalent of this can be achieved with simple if/else blocks, like so:</p> + +<pre class="brush: js notranslate"><% if ("fr" == env.locale) { %> +<%- template("CSSRef") %> « <a href="/fr/docs/Référence_CSS/Extensions_Mozilla">Référence CSS: Extensions Mozilla</a> +<% } else if ("ja" == env.locale) { %> +<%- template("CSSRef") %> « <a href="/ja/docs/CSS_Reference/Mozilla_Extensions">CSS リファレンス: Mozilla 拡張仕様</a> +<% } else if ("pl" == env.locale) { %> +<%- template("CSSRef") %> « <a href="/pl/docs/Dokumentacja_CSS/Rozszerzenia_Mozilli">Dokumentacja CSS: Rozszerzenia Mozilli</a> +<% } else if ("de" == env.locale) { %> +<%- template("CSSRef") %> « <a href="/de/docs/CSS_Referenz/Mozilla_CSS_Erweiterungen">CSS Referenz: Mozilla Erweiterungen</a> +<% } else { %> +<%- template("CSSRef") %> « <a href="/en-US/docs/CSS_Reference/Mozilla_Extensions">CSS Reference: Mozilla Extensions</a> +<% } %></pre> + +<p>Depending on what text editor is your favorite, you may be able to copy & paste from the browser-based editor and attack this pattern with a series of search/replace regexes to get you most of the way there.</p> + +<p>My favorite editor is MacVim, and a series of regexes like this does the bulk of the work with just a little manual clean up following:</p> + +<pre class="brush: none notranslate">%s#<span#^M<span#g +%s#<span lang="\(.*\)" .*>#<% } else if ("\1" == env.locale) { %>#g +%s#<span class="script">template.CSSxRef(#<%- template("CSSxRef", [# +%s#)</span> </span>#]) %> +</pre> + +<p>Your mileage may vary, and patterns change slightly from template to template. That's why the migration script was unable to just handle this automatically, after all.</p> + +<h4 id="String_variables_and_switch" name="String_variables_and_switch">文字列値と switch</h4> + +<p>Rather than switch between full chunks of markup, you can define a set of strings, switch them based on locale, and then use them to fill in placeholders in a single chunk of markup:</p> + +<pre class="brush: js notranslate"><% +var s_title = 'Firefox for Developers'; +switch (env.locale) { + case 'de': + s_title = "Firefox für Entwickler"; + break; + case 'fr': + s_title = "Firefox pour les développeurs"; + break; + case 'es': + s_title = "Firefox para desarrolladores"; + break; +}; +%> +<span class="title"><%= s_title %></span></pre> + +<h4 id="Use_mdn.localString">Use <code class="language-javascript">mdn.localString()</code></h4> + +<p>A recent addition to the <code>MDN:Common</code> module is <code class="language-javascript">mdn.localString()</code>, used like this:</p> + +<pre class="brush: js notranslate"><% +var s_title = mdn.localString({ + "en-US": "Firefox for Developers", + "de": "Firefox für Entwickler", + "es": "Firefox para desarrolladores" +}); +%> +<span class="title"><%= s_title %></span></pre> + +<p>これは switch 文による分岐よりも簡潔であり、テンプレート内で一種類や二種類程度の文字列のみの翻訳が必要なケースなどでは、switch 文より良い選択となるかもしれません。ロケールにより多くの文字列を切り替える必要がある場合（※例: <a href="/ja/docs/Template:CSSRef" title="Template:CSSRef | MDN">Template:CSSRef | MDN</a>）は、switch 文 を用いた方が良いでしょう。 if 文を用いた場合が良い場合もあります。適切なものを選択して御利用下さい。</p> + +<p>オブジェクトに適切なロケールが無い場合、 "en-US" の値が初期値として使用されます。</p> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<ul> + <li><a href="https://github.com/mdn/kumascript">KumaScript ソースコード</a></li> + <li><a href="https://wiki.mozilla.org/MDN/Kuma">Kuma wiki</a></li> +</ul> diff --git a/files/ja/mdn/tools/kumascript/troubleshooting/index.html b/files/ja/mdn/tools/kumascript/troubleshooting/index.html new file mode 100644 index 0000000000..c7c6a3a8a3 --- /dev/null +++ b/files/ja/mdn/tools/kumascript/troubleshooting/index.html @@ -0,0 +1,65 @@ +--- +title: KumaScript エラーのトラブルシューティング +slug: MDN/Tools/KumaScript/Troubleshooting +tags: + - KumaScript + - MDN Meta + - Tools + - エラー + - ガイド +translation_of: MDN/Tools/KumaScript/Troubleshooting +--- +<div>{{MDNSidebar}}</div> + +<div class="summary"> +<p>ページに出てくる <a href="/ja/docs/MDN/Contribute/Tools/KumaScript">KumaScript</a> エラーは読み手にとって不快なもので、大きく赤い恐ろしげなボックスですが、幸運なことに MDN アカウントを持つユーザーは誰でも、ドキュメントを直してこうしたエラーを修正できます。ページがエラーを起こしたとき、<a href="/ja/docs/with-errors">エラーのあるドキュメント</a>リストに追加されます。サイト編集者は通常このリストを検査して、エラーを発見、修正します。この記事では4種類の KumaScript エラーと、修正するための対策について詳しく見ます。</p> +</div> + +<h2 id="DocumentParsingError">DocumentParsingError</h2> + +<p><code>DocumentParsingError</code> のエラーは KumaScript がドキュメント自体を理解できないときに表示されます。最もよくある原因は <a href="/en-US/docs/MDN/Contribute/Content/Macros">macro</a> 内の文法エラーです。</p> + +<p>以下をチェックします:</p> + +<dl> + <dt>マクロ呼出しのつもりではない場合に中括弧を使った。</dt> + <dd>If you need to write \{ in a document without calling a macro you can escape it with a \ like this: <code>\\{</code></dd> + <dt>マクロパラメーターに特殊な文字を使った。</dt> + <dd>If you need to use a " or a \ inside of a macro parameter they can be escaped with a \ like this: <code>\\</code> or <code>\"</code></dd> + <dt>マクロパラメーター間にカンマがない。</dt> + <dd>Macro parameters need to be delimited by a comma (,) but not at the end of the list of parameters; for example <code>\{\{anch("top", "Back to top")}}</code>.</dd> + <dt>マクロ呼び出し内に HTML タグがある</dt> + <dd>If you apply styling to a macro, it will often break because, for example, a <code></code></code> tag may have appeared inside the macro code in the source code. Check the source view to see what's there, and remove any unnecessary styling.</dd> +</dl> + +<ul> +</ul> + +<h2 id="TemplateLoadingError">TemplateLoadingError</h2> + +<p><code>TemplateLoadingError</code> のエラーは KumaScript がページにどの <a href="/en-US/docs/MDN/Contribute/Content/Macros">macro</a> を取り込むか探せないときに表示されます。</p> + +<p>以下をチェックします:</p> + +<dl> + <dt>マクロ名を誤ったり、マクロがリネームされた。</dt> + <dd><a href="https://github.com/mdn/kumascript/tree/master/macros">GitHub repo</a> で既知のマクロのリストを確認できます。</dd> +</dl> + +<div class="note"> +<p><strong>Tip:</strong> You can make it quick and easy to jump to a specific macro by adding a <a href="http://kb.mozillazine.org/Using_keyword_searches">search keyword</a> to Firefox. See {{SectionOnPage("/en-US/docs/MDN/Contribute/Tools/KumaScript", "Using search keywords to open template pages")}} for a step-by-step guide to creating the search keyword for this.</p> +</div> + +<h2 id="TemplateExecutionError">TemplateExecutionError</h2> + +<p><code>TemplateExecutionError</code> のエラーは KumaScript が macro 内のエラーに遭遇したときに表示されます。このエラーは管理者のみが修正できて、バグとして報告が必要となります。</p> + +<p>エラーを報告する前に、これが修正済みでないことを確認します。KumaScript を強制的にページのフレッシュコピーを読み込ませることでできます。これには <kbd>Shift</kbd> を押しっぱなしでページ再読み込みします (Windows/Linux では <kbd>Shift</kbd> + <kbd>Ctrl</kbd> + <kbd>R</kbd> 、Mac では <kbd>Shift</kbd> + <kbd>Cmd</kbd> + <kbd>R</kbd> )。</p> + +<p>エラーが続く場合、ページの URL とエラーのテキストをつけて<a href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Mozilla_Developer_Network&component=General#h=detail|bug">bug 報告します</a>。</p> + +<h2 id="Error_Unknown">Error & Unknown</h2> + +<p>これは、エラーがこれ以外の種類にない場合のカテゴリーです。</p> + +<p>修正をチェックして、<a href="#TemplateExecutionError">TemplateExecutionError</a> に記述されるようなしつこいバグとして報告します。</p> diff --git a/files/ja/mdn/tools/page_deletion/index.html b/files/ja/mdn/tools/page_deletion/index.html new file mode 100644 index 0000000000..e6ebdd1910 --- /dev/null +++ b/files/ja/mdn/tools/page_deletion/index.html @@ -0,0 +1,61 @@ +--- +title: ページの削除 +slug: MDN/Tools/Page_deletion +tags: + - Guide + - MDN + - MDN Project + - Page-level +translation_of: MDN/Tools/Page_deletion +--- +<div>{{MDNSidebar}}</div> + +<p>MDN からページを完全に削除することは滅多にありません。もっともよくある理由は、ページがスパムによって作成された、または間違って作成された場合です。かつては有用であったページが時代遅れの技術の記述となった場合には、削除するのではなく MDN の /Archive セクションに移動することでアーカイブされます。</p> + +<h2 id="Requesting_page_deletion" name="Requesting_page_deletion">ページの削除の申請</h2> + +<p><span class="seoSummary">MDN の<a href="/ja/docs/MDN/Community/Roles/Admins">管理者</a>だけがページを削除することができます。管理者以外のユーザーは、ページの削除をリクエストすることができます。</span></p> + +<p>ページを削除するには次のようにしてください。</p> + +<ol> + <li><strong>ページコンテンツの削除や変更はしないでください。</strong>ページ削除時にはその時点のコンテンツを記録しておきます。</li> + <li>ページに "Junk" タグを追加してください。他のタグは削除しないでください。</li> + <li>ページの削除に緊急を要する場合 (例えばコンテンツが不適切、攻撃的、あるいは技術的に危険なものである場合など) は、 <a href="mailto:mdn-admins@mozilla.org" title="Notify an administrator">MDN 管理者にお知らせください</a>。</li> +</ol> + +<p>管理者は削除が適切かどうか判断した上で、随時ページを削除していきます。</p> + +<h2 id="How_to_delete_a_page" name="How_to_delete_a_page">ページを削除するには</h2> + +<p>ページを削除すると決めた管理者は、以下のようにしてください。</p> + +<ol> + <li>削除したいページの右上隅付近にある<strong>詳細</strong>メニューを開いてください。</li> + <li><strong>このページを削除</strong>をクリックしてください。「ページの削除」画面が次のように現れます。<br> + <br> + 削除しようと選択したページのタイトルと、関連する一部のメタデータが表示されます。</li> + <li><strong>理由</strong>欄に "Spam" や "Junk" や "Created by mistake" など、適切な理由を入力してください。</li> + <li><strong>削除</strong>ボタンをクリックしてください。「文書が削除されました」画面が表示され、このページへのリンクがあれば表示されます。 (権限のないユーザーには、<strong>この文書を復元</strong>ボタンが表示されません。)</li> +</ol> + +<h2 id="Restricted_access" name="Restricted_access">アクセス制限</h2> + +<p>ページ削除ツールには文書の構造を破壊する可能性が存在するため、アクセスには上位の権限を必要とします。</p> + +<h3 id="Roles_that_have_this_permission" name="Roles_that_have_this_permission">この権限を持つロール</h3> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Admins"><strong>Admins</strong></a></li> +</ul> + +<h3 id="Conditions_for_gaining_this_permission" name="Conditions_for_gaining_this_permission">この権限を得るための条件</h3> + +<p>このツールにアクセスする権限を得るための条件は以下のとおりです。</p> + +<ul> + <li><strong>日常的に</strong>この権限を必要としていること (例えば、頻繁にスパムや間違いのページに対応する必要がある場合)。たまにしかページを削除する必要がないのであれば、管理者に依頼してください。</li> + <li>日常的に MDN を編集しており、建設的な協力の記録がある場合。</li> +</ul> + +<p>この権限を取得する手続については、<a href="/ja/docs/MDN/Contribute/Processes/Requesting_elevated_privileges">上位権限の申請</a>を参照してください。</p> diff --git a/files/ja/mdn/tools/page_moving/index.html b/files/ja/mdn/tools/page_moving/index.html new file mode 100644 index 0000000000..920c6f299c --- /dev/null +++ b/files/ja/mdn/tools/page_moving/index.html @@ -0,0 +1,57 @@ +--- +title: ページの移動 +slug: MDN/Tools/Page_moving +tags: + - Guide + - MDN Meta + - Page-level + - Tools +translation_of: MDN/Tools/Page_moving +--- +<div>{{MDNSidebar}}</div> + +<p>なぜページ (またはページのツリー) を移動するのでしょう。サイトの階層の適切な場所ではなく、サイトの最上位に作成してしまったのかもしれません。あるいは既存の文書を整頓しているのかもしれませんね。古い内容をアーカイブする必要があるのかもしれません。このような理由で MDN はページを移動する機能を持っており、1つのページを移動するだけではなく、その下位のページをまとめて移動することもできます。</p> + +<p><span class="seoSummary"><strong>ページ移動ツール</strong>により、編集者は MDN ツリー内の文書およびそのすべてのサブページの URL またはスラッグを変更することができます。ページを整頓したり、間違った位置にあるページを修正したりするときに、とても手軽で強力なツールです。</span></p> + +<div class="note"> +<p><strong>メモ:</strong> 特別な権限を持つユーザーだけが MDN でページを移動することができます。<strong>この記事を移動</strong>という選択肢が<strong>詳細</strong> メニューに表示されない場合、使用するのに権限が必要です。この権限を得る方法については、下にある<a href="#Restricted_access">アクセス制限</a> を見てください。</p> +</div> + +<h2 id="How_to_move_pages" name="How_to_move_pages">ページを移動するには</h2> + +<p>ページまたはページのツリーを移動するには、以下のようにします。</p> + +<ol> + <li>MDN で移動したいページの右上の角にある<strong>詳細</strong> メニューを開いてください。<br> + <img alt="" src="https://mdn.mozillademos.org/files/14565/MDN_right_menu.png" style="height: 208px; width: 200px;"></li> + <li><strong>この記事を移動</strong> をクリックしてください。下のような「ページの移動」画面が表示されます。<br> + <img alt="" src="https://mdn.mozillademos.org/files/14567/MDN_page_move.png" style="height: 437px; width: 375px;"><br> + 一番上には、すべて (アルファベットが) 大文字で、移動しようとしているページのタイトルが表示され、続いてページを移動するためのフォームを正しく記入する方法についての注意書きの一覧が表示されます。ページタイトルは編集可能となっていますが、ここで変更しても反映されません。この問題の状態については、 {{bug(828533)}} を参照してください。</li> + <li><strong>新しい URL スラグ</strong>の隣の枠に、ページの移動先としたいスラグを入力してください。この行の上にあるのは <strong>URL のプレビュー</strong>で、ここに、<strong>新しい URL スラグ</strong>の値を反映した、ページ移動後のフルパスの URL が表示されます。</li> + <li>この移動操作によって影響を受ける全てのサブページの一覧が表示されます。<strong>N ページを移動</strong>ボタンと<strong>キャンセル</strong>ボタンの下にあります。サブページがなければ、その旨が表示されます。この一覧は、ページの移動が予測しなかった副作用を与えるのか判断するのに役立つかもしれません。閲覧の多いコンテンツの移動や、一度に大量のページを移動するのには注意を払ってください。</li> + <li>すべてが望み通り設定されていると分かったら、 <strong>N ページを移動する</strong>ボタンをクリックします。非同期のバックグラウンドプロセスが始まり、各ページを移動して<strong>かつ</strong>元のページにリダイレクトを設置します。ですので、古い URL もリダイレクトによって動作し続けます。移動のプロセスが完了したらメールが届きます。そのメールには、ページの新しい場所にクリックして移動できるリンクが含まれています。</li> +</ol> + +<h2 id="Restricted_access" name="Restricted_access">アクセス制限</h2> + +<p>内容をおかしな場所に移動することで害となる明らかな可能性が存在するため、このツールは誰もが使えるようにはなっていません。</p> + +<h3 id="Roles_that_have_this_permission" name="Roles_that_have_this_permission">この権限を持つロール</h3> + +<ul> + <li><a href="/ja/docs/MDN/Contribute/Admins"><strong>Admins</strong></a></li> + <li><a href="/ja/docs/MDN/Contribute/Topic_driver_role"><strong>Topic drivers</strong></a></li> + <li><a href="/ja/docs/MDN/Contribute/Localization_driver_role"><strong>Localization drivers</strong></a></li> +</ul> + +<h3 id="Conditions_for_gaining_this_permission" name="Conditions_for_gaining_this_permission">この権限を得るための条件</h3> + +<p>このツールにアクセスする権限を得るための条件は以下のとおりです。</p> + +<ul> + <li><strong>日常的に</strong>この権限を必要としていること (例えば、頻繁にページの移動を行う必要がある、あるトピックについて大きなリファクタリングを行っているなど)。たまにしかページを移動する必要がないのであれば、管理者に依頼してください。</li> + <li>日常的に MDN を編集していて、 <a href="/ja/docs/MDN/Contribute/Content/Style_guide#Page_titles">ページの命名</a> 規則に通じていること。</li> +</ul> + +<p>この権限を取得する手続については、<a href="/ja/docs/MDN/Contribute/Processes/Requesting_elevated_privileges">上位権限の申請</a>を参照してください。</p> diff --git a/files/ja/mdn/tools/page_regeneration/index.html b/files/ja/mdn/tools/page_regeneration/index.html new file mode 100644 index 0000000000..590eda0260 --- /dev/null +++ b/files/ja/mdn/tools/page_regeneration/index.html @@ -0,0 +1,34 @@ +--- +title: MDN 上のページのレンダリング +slug: MDN/Tools/Page_regeneration +tags: + - Guide + - MDN Meta + - Page-level + - Tools +translation_of: MDN/Tools/Page_regeneration +--- +<div>{{MDNSidebar}}</div> + +<p>MDN サイトは性能上の理由でページをキャッシュしています。 この結果、ページに対する保存済みの変更が、次回リロード時に反映されない場合があります。常にではないがしばしば、ページがの更新が処理中であることを示すバナーが表示されます。ブラウザーで強制リフレッシュしてサーバーからページをリロードできますが、サーバー上の更新が完了しないと効果がないことがあります。</p> + +<p>いくつかのページ (特に Landing ページ【訳注: 階層下のページの一覧を列挙するページ】) では、マクロを使って自動的に内容の生成と更新を行っています。Landing ページのためにこれを行うことで、作者が手動で更新しなくても、新しい記事が自動的にページに載ることが保証されます。これは長期間の貢献者には便利であり、新参者にはサイトの階層のどこにリンクすべきか分からずに成果を見失うことを避けるのに役立ちます。</p> + +<p>またあるページを別のページにトランスクルージョンする(例えば {{TemplateLink("Page")}} マクロを使って)のにも使います。</p> + +<p><span class="seoSummary">MDN は性能上の理由でレンダリングしたコンテンツをキャッシュしているため、元の素材（たとえばマクロの出力や引用されるページ）に加わった変更は自動的にはページに反映されません。そのような元の素材に頻繁に変更が加わることがわかっているならば、ページの自動生成を有効にすることを検討したくなるかもしれません。</span></p> + +<p>自動生成を有効にするには:<strong> </strong>【訳注: この機能は現在、英語版のページでのみ設定できます】</p> + +<ol> + <li><strong>EDIT</strong> ボタンをクリックし、編集モードに入ります。</li> + <li>ページタイトルの下にある <strong>Edit page title and properties</strong> をクリックします。ページのメタデータフィールドが現れます。</li> + <li><strong>Rendering max age</strong> に値を設定します。この値が、キャッシュされたページが(マクロの再実行も含めて)再生成されるスケジュールを決定します。普通は 4 または 8 Hours を指定します。 文書が頻繁に変更される技術に関しては、より少ない数値を指定しても良いでしょう。</li> + <li>変更を保存します。リビジョンコメントに、設定内容を記録しておくのは良い習慣です。例: "Rendering max age を 4 Hours に設定"</li> +</ol> + +<p>ページは指定したスケジュールに従って再生成されます。</p> + +<div class="note"> +<p><strong>注:</strong> "Edit page title and properties" オプションは、文書の作成時には現れませんので、一度保存してから開き直す必要があります。</p> +</div> diff --git a/files/ja/mdn/tools/page_watching/index.html b/files/ja/mdn/tools/page_watching/index.html new file mode 100644 index 0000000000..fe7b3a7f45 --- /dev/null +++ b/files/ja/mdn/tools/page_watching/index.html @@ -0,0 +1,49 @@ +--- +title: ページやページ群を監視・購読する +slug: MDN/Tools/Page_watching +tags: + - Guide + - MDN Meta + - Page-level + - Tools +translation_of: MDN/Tools/Page_watching +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">MDN ページを購読することで、そのページが更新・変更された時はいつでもメールで通知を受け取ることができます。</span>すべての MDN ページの右上の隅に、監視ボタンがあります。購読のオプションにアクセスするには、監視ボタンの上にポインターを動かして監視メニューを開くいてください。</p> + +<p><img alt="MDN の監視メニューのスクリーンショット" src="https://mdn.mozillademos.org/files/12551/MDN_-_Watch_Menu.png" style="border-style: solid; border-width: 1px; display: block; height: 298px; margin: 0 auto; width: 463px;"></p> + +<p>そのページだけを購読するか、サブページも一緒に購読するかをオプションで選択してください。</p> + +<h2 id="Subscribe_to_a_page" name="Subscribe_to_a_page">ページを購読する</h2> + +<p>ユーザーがそのページを編集するたびにメール通知を受け取るには、ページの上部にある詳細メニューの最初のオプション「この記事を購読」をクリックします。</p> + +<h2 id="Subscribe_to_a_page_and_all_its_sub-articles" name="Subscribe_to_a_page_and_all_its_sub-articles">ページとすべてのサブページを購読する</h2> + +<p>2つ目のオプション「この記事と全サブ記事を購読」をクリックすると、ユーザーがそのページとすべてのサブページを編集するたびにメール通知を受け取るようになります。これは購読を要求した後に追加されたサブページも含むため、将来多くのサブページが作られた場合、その通知も同様に受け取ります。</p> + +<h2 id="Unsubscribe_from_a_page" name="Unsubscribe_from_a_page">ページの購読解除</h2> + +<p>購読を解除してページの監視をやめる場合は、再び監視メニューを開いて「この記事の購読を中止」をクリックしてください。ページを購読していると「この記事の購読を中止」とだけ表示されています。ページが変更されるたびにメール通知を受けることはなくなります。</p> + +<h2 id="The_page_change_emails" name="The_page_change_emails">ページ変更のメール</h2> + +<p>ページを購読すると、ページが保存されるたびにメールを受け取ります。このメールは notifications@developer.mozilla.org から MDN アカウントに登録されたメールアドレスに送信されます。各メッセージにはこの形のタイトルがあります:</p> + +<pre class="notranslate">[MDN] ページ "<em>ページタイトル</em>" が <em>ユーザー名</em> によって変更されました</pre> + +<p>メッセージはタイトル情報の繰り返しで始まり、つぎにコンテンツの標準差分を表示して、正確に何が変更されたかを示します。変更は HTML ソースコードで表示され、 MDN のコンテンツに慣れていない場合少し読みにくいかもしれません。</p> + +<p>差分の下には、変更に対応するのに役立つ、次のようなリンクの一覧があります:</p> + +<ul> + <li>その変更を行ったユーザーの MDN プロファイルを表示する</li> + <li>MDN のオンサイト履歴機能を使ってページの新旧のバージョンを比較する</li> + <li>ブラウザーで記事自体を見る</li> + <li>記事を編集する</li> + <li>記事の履歴を見る</li> +</ul> + +<p>メールの最後には、"HTML element reference とその全サブ記事に対する編集の購読を開始しました" といった、どんな購読でメールが生成されたかの通知や、購読をやめるためのリンクがあります。購読をやめるリンクをクリックすると、その監視リクエストのメッセージを受け取らなくなります。</p> diff --git a/files/ja/mdn/tools/put_api/index.html b/files/ja/mdn/tools/put_api/index.html new file mode 100644 index 0000000000..6e05522016 --- /dev/null +++ b/files/ja/mdn/tools/put_api/index.html @@ -0,0 +1,208 @@ +--- +title: PUT API +slug: MDN/Tools/PUT_API +tags: + - Advanced + - Automation + - Documentation + - Draft + - Guide + - MDN Meta + - PUT API + - Page-level + - Tools +translation_of: MDN/Tools/PUT_API +--- +<div>{{MDNSidebar}}</div> + +<div> {{draft}}</div> + +<p><span class="seoSummary">MDN Wiki はページの全体、または一部の更新のための<strong>実験的な</strong> <a href="/ja/docs/Web/HTTP">HTTP</a> PUT API を提供しています。</span>この機能は、次のような時に便利です:</p> + +<ul> + <li>プロジェクトのページを作成し、自動ビルド、テスト、デプロイスクリプトからある節のコンテンツを更新することができる。これはコミュニティがプロジェクトの進捗の最新についていくのに役立ちます。</li> + <li>ソースコードと並行してドキュメントを提供する場合、HTML をプッシュして MDN のサブセクションにレンダリングできます。これでチームの作業フローにとって適切な方法でドキュメントを維持できて、MDN に貢献したりローカライズ担当がコンテンツを翻訳できるままになります。</li> +</ul> + +<h2 id="Testing_your_application" name="Testing_your_application">アプリケーションをテストする</h2> + +<p>MDN を実行するソフトウェアを開発する中で、次のようにいろいろなステージ上のサイトインスタンスをホストしています:</p> + +<ul> + <li>Production (<a href="http://developer.mozilla.org/" title="http://developer.mozilla.org/">http://developer.mozilla.org/</a>), the real site with stable code and where changes to content matter.</li> + <li>Staging (<a href="http://developer.allizom.org/" title="http://developer.allizom.org/">http://developer.allizom.org/</a>), a version of the site where changes are throwaway and upcoming features are tested.</li> + <li>Development (<a href="http://developer-dev.allizom.org/" title="http://developer-dev.allizom.org/">http://developer-dev.allizom.org/</a>), a version of the site running the absolute latest and untested code.</li> +</ul> + +<p>プロダクションサイトを無駄にしないようにするには、まずステージングに対してアプリケーションを開発する必要があります。それから、あなたが望むことを合理的に実行することができたら、それをプロダクションに反映するように再構成します。また、開発に取り組むこともできますが、問題が発生する可能性があります。</p> + +<h2 id="Creating_an_API_key" name="Creating_an_API_key">API キーを作成する</h2> + +<p>APIキーを使うと、毎回 Persona ログインするような介入を要求せずに、アプリケーションを代理人として動作させることができます。SSL 上の HTTP ベーシック認証を使ってユーザー名とパスワードを提供します。基本的な使用のトラッキングを集めて、どのように使われているかがわかるようにします。そして、たまたま持つべきでない人々に渡った場合は、アクセスを無効にするよう API キーを削除できます。</p> + +<p>If you have the correct privileges to do so, to create an API key, sign into MDN and <a href="https://developer.mozilla.org/ja/users/account/keys" title="https://developer.mozilla.org/ja/users/account/keys">visit the API keys management page</a>. This page lets you create and delete API keys, as well as inspect recent usage history. Only Mozillians in good standing can currently get API keys, since they grant abilities to automate changes to content rapidly, so unprivileged users must request the ability by filing a bug.</p> + +<p>{{NoteStart}}The above link goes to the Production site, and the same keys do not work between Production and Staging. You can also get to this page by visiting your profile on the respective site: Click on your username in the upper right of the site. On your profile page, you should see a "Manage API Keys" button.{{NoteEnd}}</p> + +<p>From there, clicking on the "<a href="https://developer.mozilla.org/ja/users/account/keys/new" title="https://developer.mozilla.org/ja/users/account/keys/new">Create a new API key</a>" button should take you to an entry form so you can submit a request for an API key.</p> + +<p>After filling out and submitting the form, you will receive a key ID and secret. These are your username and password, respectively. Copy these down somewhere safe (eg. to your application's configuration settings); the site will never display them again, and there is no recovery method. If you lose them, simply delete the API key and create another.</p> + +<h2 id="Making_a_PUT_request" name="Making_a_PUT_request">PUT リクエストを作成する</h2> + +<p>Since the PUT API works by way of HTTP, it should be compatible with the application environment and libraries of your choice. This first example uses <a href="http://curl.haxx.se/" title="http://curl.haxx.se/">the command-line tool cURL</a> and a UNIX shell to demonstrate how to issue a simple PUT request to MDN.</p> + +<h3 id="Request" name="Request">リクエスト</h3> + +<pre class="brush: bash notranslate"># Base URL and API key from staging (example only; substitute your own) +MDN_BASE_URL="https://developer.allizom.org" +MDN_KEY_ID="frsNFFR3w0yEALRE9IA9oN1KwoDno8vVGrzsBNvCofI" +MDN_SECRET="423PdCvnvraH0FkCDTKnizTmKGNkEdgQTi6RlEFTiWs" + +# Document-specific details +DOC_USERNAME="lmorchard" # Change this to your name +DOC_PATH=/ja//docs/User:$DOC_USERNAME/PutExample" +DOC_TYPE="text/html" +DOC_DATA="<b>HELLO WORLD</b>" + +# Putting it all together... +curl -si -X PUT -H"Content-Type: $DOC_TYPE" -d"$DOC_DATA" -u"$MDN_KEY_ID:$MDN_SECRET" "$MDN_BASE_URL$DOC_PATH"</pre> + +<p>Since there's a lot going on in this cURL invocation, the example is broken into variables:</p> + +<ul> + <li><code>MDN_BASE_URL</code> - as mentioned before, you should plan to switch your application between staging and production servers on MDN. This variable allows for that.</li> + <li><code>MDN_KEY_ID</code> - the key ID from the API key you created. Note that these are server-specific - the same keys do not work between staging and production.</li> + <li><code>MDN_SECRET</code> - the secret from the API key that corresponds with the key ID.</li> + <li><code>DOC_USERNAME</code> - change this to your MDN username.</li> + <li><code>DOC_PATH</code> - the URL path to the document with content you want to manipulate.</li> + <li><code>DOC_TYPE</code> - the content in the request will be <code>text/html</code></li> + <li><code>DOC_DATA</code> - the content sent in the PUT request body; this is the content that will be used in a new revision to the document</li> +</ul> + +<p>So, along with the variables, here are some general notes on the example and its use of the PUT API:</p> + +<ul> + <li>The key ID and secret are supplied as username and password, respectively, in HTTP Basic authentication over SSL.</li> + <li>The <code>DOC_PATH</code> for this example includes a username - presumably yours - but that's just for the sake of example and ensuring you have your own sample document to play with. You can use any URL path to any document on the wiki.</li> + <li>A <code>Content-Type</code> header is required, and lets MDN know how to process the content sent in the PUT request. Several content types are supported, and this feature will be described in greater detail shortly.</li> + <li>Content intended for the document is sent in the request body, using the representation promised in the <code>Content-Type</code> header</li> +</ul> + +<h3 id="Response" name="Response">レスポンス</h3> + +<p>There are several responses you may see if you try this example: <code>403</code>, <code>404</code>, <code>201</code>, or <code>205</code>. (You may see others, but those suggest something has gone wrong with the site. That will, hopefully, be rare.)</p> + +<h4 id="403_Forbidden" name="403_Forbidden">403 Forbidden</h4> + +<p>If either the key ID or secret are incorrect, you'll see a <code>403 Forbidden</code> response. Double check your key details and that you're using the right pair for the right server. Create a new API key, if necessary.</p> + +<h4 id="404_Not_Found" name="404_Not_Found">404 Not Found</h4> + +<p>If you've never created a document at the URL path <code>/en-US/docs/User:$MDN_USERNAME</code>, you'll see a <code>404 Not Found</code> response.</p> + +<p>{{NoteStart}}The PUT API will not automatically create parent documents. If you're creating a number of documents intended to comprise a subsection of MDN, make sure to create parent documents first from the top down in the hierarchy.{{NoteEnd}}</p> + +<h4 id="201_Created" name="201_Created">201 Created</h4> + +<p>If the parent document exists, but the path itself doesn't, you should see a <code>201 Created</code> response. This signifies that a new document was created, as opposed to an existing one having been updated.</p> + +<h4 id="205_Reset_Content" name="205_Reset_Content">205 Reset Content</h4> + +<p>In the case of an updated document, you'll see a <code>205 Reset Content</code> response. This means that the document content has been updated, and that you should reload the document if you happen to need to see the results.</p> + +<p>{{NoteStart}}MDN performs certain filtering and processing steps on content, so what you put in may not be exactly what gets served back.{{NoteEnd}}</p> + +<h2 id="Supported_Content_Types" name="Supported_Content_Types">サポートされるコンテンツのタイプ</h2> + +<p>The PUT API accepts one of several content types in the request body.</p> + +<h3 id="texthtml" name="texthtml">text/html</h3> + +<p>There are actually two forms of <code>text/html</code> accepted: fragment and document.</p> + +<h4 id="Fragment" name="Fragment">Fragment</h4> + +<p>An HTML fragment is just an arbitrary chunk of markup, and is used as-is to revise document content. This is the simplest way to update documents.</p> + +<h4 id="Document" name="Document">Document</h4> + +<p>However, if the request body consists of an <code><html></code> element containing <code><head></code> and <code><body></code> elements, it's treated as a full HTML document. In this case, the following processing happens:</p> + +<ul> + <li>From the <code><head></code> element, the contents of <code><title></code> is extracted and used as the title for the document on MDN.</li> + <li>The contents of <code><body></code> is extracted as the content for a new revision. </li> +</ul> + +<p>This is a more complex way to update documents, but is intended as a convenience to accomodate submission of existing HTML pages.</p> + +<h3 id="applicationjson" name="applicationjson">application/json</h3> + +<p>Although the <code>text/html</code> content type is handy, there are more fields belonging to documents that are useful to manage. These include the following:</p> + +<ul> + <li><code>title</code> - the document title</li> + <li><code>content</code> - the content intended for the new revision</li> + <li><code>tags</code> - tags used to organize documents: this is given as a single string, with tags separated by commas</li> + <li><code>review_tags</code> - tags used to request content reviews: this is given as a single string, with tags separated by commas</li> + <li><code>summary</code> - a comment describing the revision to be made</li> + <li><code>show_toc</code> - a flag (0/1) indicating whether the table of contents should be shown for this document</li> +</ul> + +<p>These fields can be supplied as string values in a JSON-encoded object with the <code>application/json</code> content-type in a PUT request.</p> + +<pre class="brush: bash notranslate"># Auth Stuff +DOC_USERNAME="lmorchard" # Change this to your name +MDN_KEY_ID="frsNFFR3w0yEALRE9IA9oN1KwoDno8vVGrzsBNvCofI" +MDN_SECRET="423PdCvnvraH0FkCDTKnizTmKGNkEdgQTi6RlEFTiWs" + +# Base Settings (for Staging Env) +MDN_BASE_URL="https://developer.allizom.org" +DOC_PATH=/ja//docs/User:$DOC_USERNAME/PutExample" +DOC_TYPE="application/json" + +<code class="language-bash"># Doc Content +echo '{"content": "<b>Hello World</b>", "title": "New Sample Title", "show_toc": 1, "tags": "Beginner, Tutorial", "review_tags": "editorial, technical", "summary": "Sample JSON update from the API"}' > /tmp/mdn.json + +# Submitting Content</code> +curl -X PUT -H "Content-Type: $DOC_TYPE" -d @/tmp/mdn.json -u"$MDN_KEY_ID:$MDN_SECRET" "$MDN_BASE_URL$DOC_PATH" +</pre> + +<h3 id="multipartform-data" name="multipartform-data">multipart/form-data</h3> + +<p>This content type is handled basically like <code>application/json</code> - the same fields are accepted. But, it might be less useful than JSON and is supported mainly for testing purposes.</p> + +<h2 id="Updating_a_single_section" name="Updating_a_single_section">1 つのセクションを更新する</h2> + +<p>Normally, an HTTP PUT request replaces the entirety of a document with the submitted content in a new revision. However, you can use the query parameter <code>?section</code> to constrain revision to a single section of the document and leave the rest of the content as-is. This is handy for automating changes to one part of a document that is otherwise managed by hand, or even for aggregating changes from many sources or scripts into one document.</p> + +<h3 id="Creating_document_sections" name="Creating_document_sections">文書のセクションを作成する</h3> + +<p>Documents on MDN can be broken up into sections. These sections are useful for building a table of contents, linking to specific parts, and editing subsets of document content.</p> + +<h4 id="Using_headers" name="Using_headers">Using headers</h4> + +<p>Headers (ie. <code><h2></code> .. <code><h6></code>) make sections in MDN documents. The text of each header is transformed automatically into an ID, and that's used for anchor links in the table of contents sidebar on most documents. Those auto-generated IDs can be overriden with the <code>name</code> attribute on headers. Either way, looking at the table of contents is the easiest way to see how a document is broken up into sections, and to discover the IDs for those sections.</p> + +<p>The contents of a section include its header and everything following the header up to (but not including) another header of the same or higher level. So, a section that starts with an <code><h2></code> continues until the next <code><h2></code>, including any subsections started by <code><h3></code> .. <code><h6></code>. That also means sections can be nested: An <code><h3></code> appearing after an <code><h2></code> creates a subsection, including any further nested subsections started by <code><h4></code> .. <code><h6></code>, up to the next <code><h3></code> or <code><h2></code>.</p> + +<p>@@TODO: Show an HTML example with headers, here. This is a bit confusing.</p> + +<h4 id="Using_container_elements" name="Using_container_elements">Using container elements</h4> + +<p>Setting an <code>id</code> attribute on a container element (eg. a <code><div></code> or <code><span></code> or <code><section></code>) in the source editor also creates a section, at least with respect to the PUT API. This is a bit more advanced and requires manual changes to raw HTML, rather than using the WYSIWYG editor. But, if you want to update a chunk of the page without the need for headers, this is how to do it.</p> + +<h3 id="Specifying_a_section" name="Specifying_a_section">セクションを指定する</h3> + +<ul> + <li>Look at the table of contents, note the anchor ID for the link (ie. the <code>#hash</code> part of the URL).<br> + Example: <code>https://developer.mozilla.org/ja/docs/User:lmorchard/PUT-API#Specifying_a_section</code></li> + <li>Take everything after the "#" character, and you have the section ID.<br> + Example: <code>Specifying_a_section</code></li> + <li>Add <code>?section={ID}</code> to the URL for the document, substituting the section ID for <code>{ID}</code>.<br> + Example: <code>https://developer.mozilla.org/ja/docs/User:lmorchard/PUT-API?section=Specifying_a_section</code></li> + <li>If you view <a href="https://developer.mozilla.org/ja/docs/User:lmorchard/PUT-API?section=Specifying_a_section" title="https://developer.mozilla.org/ja/docs/User:lmorchard/PUT-API?section=Specifying_a_section">that URL</a> in a browser (ie. HTTP GET), you'll see just that section of the document.<br> + (For more details on what you can do with HTTP GET, see also: <a href="/ja/docs/Project:The_Kuma_API" title='/ja/docs/Project:The_Kuma_API""'>Project:The_Kuma_API</a>)</li> + <li>If you issue a PUT request to that URL, you'll modify just that section of the document.<br> + (But, don't do that to the example URL, or you'll clobber the page you're reading right now!)</li> +</ul> diff --git a/files/ja/mdn/tools/revision_dashboard/index.html b/files/ja/mdn/tools/revision_dashboard/index.html new file mode 100644 index 0000000000..10c96bfa07 --- /dev/null +++ b/files/ja/mdn/tools/revision_dashboard/index.html @@ -0,0 +1,117 @@ +--- +title: リビジョンダッシュボード +slug: MDN/Tools/Revision_dashboard +tags: + - Guide + - MDN Meta + - Site-wide + - Tools +translation_of: MDN/Tools/Revision_dashboard +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary"><a href="/dashboards/revisions" title="https://developer.mozilla.org/dashboards/revisions">リビジョンダッシュボード</a> は MDN Web Docs Wiki の機能で MDN での最近の更新と追加を見たり、何が変更されたのか詳細を確認したり、それらの更新に対して様々な方法で行動することができます。</span> この記事では、リビジョンダッシュボードの使い方を説明します。</p> + +<h2 id="First_look" name="First_look">外観</h2> + +<p>リビジョンダッシュボードのインターフェイスは多くの要素を持ち、便利な機能が満載です。まずはインターフェイスの主要な部分の概観から始めましょう。</p> + +<p><img alt="Annotated screenshot of main revision dashboard view" src="https://mdn.mozillademos.org/files/11481/MDN_Revision_Dashboard_main.png" style="height: 625px; width: 1102px;"></p> + +<p>ここで注意すべき最も大事なことは履歴のリストで、ここでフィルターにマッチする履歴や、履歴の差分 (クリックした履歴で変更された内容が見られます) を一通り見ることができます。</p> + +<h2 id="The_revision_list" name="The_revision_list">リビジョン一覧</h2> + +<p>リビジョンダッシュボードウィンドウの中ほどにあるリビジョン一覧は、最近なされた変更を提供します。この一覧は、最近変更された記事が最初に来るように順序付けられていて、先に進むともっと古い履歴になります。</p> + +<p>リビジョン一覧のすぐ下にあるのは、検索クエリーにマッチしたページがどれくらいあり、そのうちのどこを見ているのかを示すインジゲーターです。何もフィルターをかけていない場合、MDN wiki になされたすべての履歴のページ数が見えます。</p> + +<p>一覧の各行は wiki への 1 つの変更に対応しています。"変更" とは次のいずれかからなっています:</p> + +<ul> + <li>新しいページが作成されました。これはリビジョンタイムスタンプの下に "new" のタグで示されます。</li> + <li>ページが移動されました。これはコメント欄の影のある四角に "<old path> ➞ <new path>" のように示されます。</li> + <li>ページのテキストが変更されました。</li> + <li>ページのタグが変更されました。</li> + <li>ページが削除されました。{{unimplemented_inline()}}</li> +</ul> + +<p>各行は 4 つの列からなります: リビジョン、タイトル、コメント、著者です。</p> + +<h3 id="Revision_column" name="Revision_column">リビジョン列</h3> + +<p>リビジョン列はなされた変更の情報が与えられます。この列ではいくつかの情報が提供されます:</p> + +<dl> + <dt>タイムスタンプ</dt> + <dd>リビジョンが保存された正確な日付と時間。これはリビジョン詳細ページへのリンクで、そこではリビジョンのメタデータとコンテンツが表示されます。</dd> + <dt>ロケール</dt> + <dd>記事のロケールが列のタグとして示されます。これは言語の省略コードで表示され、例えば英語では "en-US" です。</dd> + <dt>ファイル変更インジゲーター</dt> + <dd>これまで存在しない新しい記事には <strong>new</strong> のタグが表示されます。ページが削除されたことを示す場合は、<strong>deleted</strong> タグが出てきます。ページが 1 回の改訂だけで削除された場合、<strong>new</strong> と <strong>deleted</strong> タグの両方が表示されることもありえます。</dd> + <dt> + <h3 id="Title_column" name="Title_column">タイトル列</h3> + </dt> +</dl> + +<dl> + <dt>記事のタイトル</dt> + <dd>記事のタイトルは、ページにセットされているため、列に表示されます。タイトルは、直接移動して素早く簡単に見られるような、wiki 記事へのリンクでもあります。</dd> + <dt>記事のパス</dt> + <dd>記事のタイトルの下に、記事のパスが表示されます。これは記事の URL の一部分で、<code>http://developer.mozilla.org/<em><locale></em>/docs/</code> の後に来るものです。</dd> + <dt> + <h3 id="Comment_column" name="Comment_column">コメント列</h3> + </dt> +</dl> + +<dl> + <dt>リビジョンコメント</dt> + <dd>変更の著者がリビジョンコメントを変更の保存時に追加していた場合、そこにあります。これは小さめのイタリックなテキストで表示されます。</dd> + <dt>移動の情報</dt> + <dd>リビジョンがページの移動を表す場合、wiki 上の移動元と行き先のパスが表示されます。</dd> + <dt> + <h3 id="Author_column" name="Author_column">著者列</h3> + </dt> +</dl> + +<p>著者の列はそのリビジョンを保存した人のユーザー名が表示されます。それをクリックしてユーザーのプロフィールページをすぐに見ることができます。</p> + +<div class="note"> +<p><strong>管理者のみ:</strong> 管理者権限を持つ MDN ユーザーは著者列の見出しに <strong>Toggle IPs</strong> ボタンもあります。これをクリックするとそれぞれの著者の IP アドレスが表示され、不正なユーザーを IP アドレスによって禁止することができます。ユーザーが禁止されたら、ユーザー名の下に印が出ますが、これは管理者のみに見えます。</p> +</div> + +<h2 id="Filtering" name="Filtering">フィルター</h2> + +<p>MDN はいくつかの便利なフィルターオプションを提供しており、あなたのニーズに応じてリビジョンの「物」の量を削減できます。フィルターを調整して、<strong>絞り込み</strong> ボタンを押して適用します。しばらくすると、ディスプレイはフィルター結果を更新します。いくつかのフィルターを利用できます:</p> + +<dl> + <dt>ロケール</dt> + <dd>You may filter so that you only see changes in a specific locale. 既定では, you see changes across all locales, but this may not be useful to you. Indeed, if you're a member of a localization team, 例えば、the only locales you're likely to care about are your own and English. You can specify the locale to filter by in the URL when going to the revision dashboard by adding "locale=<localename>" to the query string. 例えば、: <a href="https://developer.mozilla.org/ja/dashboards/revisions?locale=en-US" title="https://developer.mozilla.org/ja/dashboards/revisions?locale=en-US">https://developer.mozilla.org/ja/dashboards/revisions?locale=en-US</a> filters to show only changes to English documents.</dd> + <dt>ユーザー</dt> + <dd>Interested in what a specific user has been up to? You can look at the revisions submitted by a single user by entering it in this field. You can specify a user in the URL when going to the revision dashboard by adding "user=<username>" to the query string. 例えば、you can see changes by the user Sheppy with <a href="https://developer.mozilla.org/ja/dashboards/revisions?user=Sheppy" title="https://developer.mozilla.org/ja/dashboards/revisions?user=Sheppy">https://developer.mozilla.org/ja/dashboards/revisions?user=Sheppy</a>. This box will offer suggestions as you type, to help you find exactly the person you're looking for.</dd> + <dt>トピック</dt> + <dd>If you'd like to see changes only about a given topic area, you can specify a topic string. This will be matched against the URLs of articles that have been changed and show only those whose titles include this string. You can specify the parameter "topic=<topic>" in the URL's query string to filter on this, as well. 例えば、if you'd like to see only JavaScript-related changes: <a href="https://developer.mozilla.org/ja/dashboards/revisions?topic=JavaScript" title="https://developer.mozilla.org/ja/dashboards/revisions?topic=JavaScript">https://developer.mozilla.org/ja/dashboards/revisions?topic=JavaScript</a>.</dd> + <dt>開始日と終了日</dt> + <dd>You can specify that you want to see only revisions in a certain range of dates, or with a certain starting or ending date. The dashboard UI provides date selection widgets for these fields. You can specify these parameters in the URL's query string, but you must use your system locale's version of the date string. 例えば、: https://developer.mozilla.org/ja/dashboards/revisions?start_date=09%2F01%2F2015 for revisions starting with September 2, 2015 in the en-US locale.</dd> + <dt>先行期間</dt> + <dd>Rather than typing or selecting start or end dates, you can specify that you want to see revisions from a selected period prior to the present time, such as the last hour, day, week, or 30 days.</dd> +</dl> + +<p>フィルターを組み合わせて使うのにも注目すぺきで、ユーザーインターフェイスや URL のクエリーストリングの両方でそれは言えます。かなり複雑な検索も実効できます。例えば、ユーザー{{UserLink("evilpie")}} が書いた英語の JavaScript 記事を見つけるには、このようにします <a href="https://developer.mozilla.org/ja/dashboards/revisions?locale=en-US&user=evilpie&topic=JavaScript" title="https://developer.mozilla.org/ja/dashboards/revisions?locale=en-US&user=evilpie&topic=JavaScript">https://developer.mozilla.org/ja/dashboards/revisions?locale=en-US&user=evilpie&topic=JavaScript</a>.</p> + + + +<h2 id="The_revision_diff" name="The_revision_diff">更新の差分</h2> + +<p>ページのあるリビジョンと前のリビジョンの違いを表示する「差分」を見ることができます。あるリビジョンの差分を見るには、リンクではない行のいずれかをクリックします (つまり、タイムスタンプ、記事のタイトル、著者のユーザー名以外)。この行はリビジョンの差分とリビジョンコントロールを説明します。</p> + +<p><img alt="Annotated screenshot of revision dashboard view" src="https://mdn.mozillademos.org/files/11485/MDN_Revision_Dashboard_diff.png" style="height: 245px; width: 1201px;"></p> + +<p>リビジョンコントロールは次の記事操作を許可します:</p> + +<ul> + <li><strong>もとに戻す</strong>: 記事を表示されたものの前に戻します。</li> + <li><strong>ページを表示</strong>: ページの現在の状況を表示します。</li> + <li><strong>ページを編集</strong>: 編集モードでページを開きます。</li> + <li><strong>履歴</strong>: ページの履歴ビューを開きます。</li> +</ul> diff --git a/files/ja/mdn/tools/sample_server/index.html b/files/ja/mdn/tools/sample_server/index.html new file mode 100644 index 0000000000..6f8af2e0f5 --- /dev/null +++ b/files/ja/mdn/tools/sample_server/index.html @@ -0,0 +1,107 @@ +--- +title: MDN サンプルサーバ +slug: MDN/Tools/Sample_server +tags: + - Advanced + - Draft + - Guide + - MDN Meta + - Site-wide + - Tools +translation_of: MDN/Tools/Sample_server +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/ja/docs/MDN")}}</div> + +<p><span class="seoSummary">MDN の <a href="/ja/docs/MDN/Kuma">Kuma</a> プラットフォームは内蔵の<a href="/ja/docs/MDN/Contribute/Editor/Live_samples">ライブサンプルシステム</a>を提供して単純な（時にはそう単純でない）コードのサンプルをその出力と共にページの中で表示する機能を提供していますが、この機能では許可されていないことがあり、またサーバへの通信を必要とするサンプルもあります。私たちは MDN サンプルサーバを用意し、このような、またその他の問題も合わせて、解決することにしました。</span> この記事は、そのサンプルサーバを利用するためのガイドです。</p> + +<h2 id="Possible_use_cases" name="Possible_use_cases">想定するユースケース</h2> + +<p>たいていのサンプルは組み込みの <a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Editor/Live_samples">live sample system</a> で表現できますが、例外もあります。サンプルサーバーの利用が必要となる理由は下記の通りです:</p> + +<ul> + <li>サンプルにサーバー上で永続的に実行されるコードが必要、例えば WebSocket サーバーにはサーバーコンポーネントと、サンプルサーバー上のクライアントコンポーネントもあるなど。</li> + <li>MDN wiki のコンテンツでは動かない技術を使ったサンプルや、読み手がコンテンツに集中する能力に影響するようなものは明らかに候補となります; これにはサウンド効果やメディアや大量のアニメーションを再生するものが含まれます。</li> + <li>MDN でホストできないようなリソースにアクセスする必要があるサンプルはサンプルサーバーに置かれます。</li> +</ul> + +<h2 id="Referencing_samples" name="Referencing_samples">サンプルへの参照を追加する</h2> + +<p>各サンプルのコードは <a href="https://github.com/mdn/samples-server">GitHub で管理されて</a>おり、そのすべてのサンプルの実行可能/使用可能なインストールアクセスを提供するサーバーを持っています。各サンプルには固有の名前があり、リンクされる際には常にその名前のみで参照されます。以下のマクロの1つを使います。</p> + +<h3 id="GithubSampleLink" name="GithubSampleLink">GithubSampleLink</h3> + +<p>{{TemplateLink("GithubSampleLink")}} は Github にある与えられた名前を持つサンプルのサンプルコードへのリンクを作成します。リンクのテキストとして使用する文字列をオプションで変更することもできます。</p> + +<h3 id="GithubSampleFileLink" name="GithubSampleFileLink">GithubSampleFileLink</h3> + +<p>{{TemplateLink("GithubSampleFileLink")}} は Github にあるサンプルコードの中の指定された名前のファイルへのリンクを作成します。引数として、サンプルの名前、 リンクしたいファイルへのサンプルコード内での相対パスがあり、オプションでリンクのテキストを指定することもできます。</p> + +<h3 id="SampleServerLink" name="SampleServerLink">SampleServerLink</h3> + +<p>{{TemplateLink("SampleServerLink")}} はサンプルサーバー上のユーザーインタラクティブなサンプルへのリンクを挿入します。これはユーザーにサンプルへ移動してブラウザー内で遊ぶことができるように使います; これはサンプルがサーバーのみで作られてクライアント側のコードから別の場所から参照する場合には使いません。サンプルの名前と、オプションでリンクの代替テキストを入力として受けます。</p> + +<h2 id="高度なサンプルに貢献する">高度なサンプルに貢献する</h2> + +<p><a href="https://mdn-samples.mozilla.org/">サンプルサーバー</a>に置かれたサンプルに貢献するには、GitHub の <a href="https://github.com/mdn/samples-server">MDN サンプルサーバーリポジトリ</a>をフォークする必要があります。現在、すべてのサンプルは GitHub の同じリポジトリにあります。</p> + +<p>それぞれのサンプルは <a href="https://github.com/mdn/samples-server/tree/master/s"><code>s/</code> ディレクトリー</a>の下に自身のディレクトリーを持っています。新しいサンプルを作るには、そこに適切な名前のディレクトリーを追加します。例えば、ちょっとしたゲームを実装するための Fetch API の使い方を示す例であれぱ、<code>s/fetch-trivia</code> にサンプルを置いても良いでしょう。</p> + +<h3 id="Structure_of_an_advanced_sample" name="Structure_of_an_advanced_sample">高度なサンプルの構造</h3> + +<p>それぞれのサンプルに一つの必須ファイルがあります (これは皮肉にもまだ使われていませんが、すぐ使われるため入れておいてください): <code>manifest.json</code> というマニフェストファイルで、これはサンプルを説明し、サンプルサーバー自体からと、これをメンテ・使用するツールから使われるメタデータを提供します。その他のすべてはオプションです。もっと詳しく見ていきましょう。</p> + +<h4 id="マニフェストファイル_manifest.json">マニフェストファイル: manifest.json</h4> + +<p>マニフェストファイルは第一に、サンプルのリストをビルドするのに使われますが、最終的には各サンプルのスタートアップとシャットダウンプロセスを改良することに使われるでしょう。これは次のような JSON オブジェクトです:</p> + +<pre class="brush: json line-numbers language-json notranslate"><code class="language-json"><span class="punctuation token">{</span> + <span class="key token">"name":</span> <span class="string token">"WebSocket based chat server with WebRTC video chat support"</span><span class="punctuation token">,</span> + <span class="key token">"docsUrl":</span> <span class="string token">"https://developer.mozilla.org/ja/docs/Web/API/WebRTC_API/Signaling_and_video_calling"</span><span class="punctuation token">,</span> + <span class="key token">"description":</span> <span class="string token">"Uses Node.js to set up a WebSocket-based chat server, and provides a web page you can use to join the chat. Adds a feature to start a video call with another chat participant."</span> +<span class="punctuation token">}</span></code></pre> + +<p>現在オブジェクトには3つの項目があり、<em>すべてが必須です </em>(まだ使用してないですが、すぐ使います):</p> + +<dl> + <dt><code>name</code></dt> + <dd>実例の名前です。例の比較的短い名前であるべきです。</dd> + <dt><code>docsUrl</code></dt> + <dd>この例を詳しく扱っている MDN の主なページの URL です。例が複数のページから参照されている場合、「メイン」ページ (または存在するならランディングページ) のアドレスであるべきです。</dd> + <dt><code>description</code></dt> + <dd>実例を説明する長めの文で、これがデモする技術についての情報を含みます。</dd> +</dl> + +<h4 id="スタートアップ時にサンプルを動かす_startup.sh">スタートアップ時にサンプルを動かす: startup.sh</h4> + +<p>When the sample server starts up or samples are restarted, each sample's base directory is scanned to see if there's a shell script file named <code>startup.sh</code>. If the file exists, it is executed, so that the sample has the opportunity to install support files, run any scripts, and start up any server processes that are needed to support the sample. For example, the <a href="https://developer.mozilla.org/ja/docs/Web/API/WebRTC_API/Signaling_and_video_calling">WebSocket chat sample's</a> startup.sh script looks like this:</p> + +<pre class="brush: bash line-numbers language-bash notranslate"><code class="language-bash">npm install websocket +node chatserver.js</code></pre> + +<p>The first line uses the Node package manager, <code>npm</code>, to install the module named <code>websocket</code>, which provides support for creating and/or talking to <a href="https://developer.mozilla.org/ja/docs/Web/API/WebSocket_API">WebSocket</a> servers.</p> + +<p>The second line actually starts up the server process, which is implemented as a JavaScript script which is started up and run in the background.</p> + +<h4 id="Node.js_モジュールを使う_package.json">Node.js モジュールを使う: package.json</h4> + +<p>To use Node modules in your project, you'll need to add a <code>package.json</code> file, which lists information about your sample but also includes a list of dependencies, so that those dependencies can be installed for you by the Node package manager (<code>npm</code>).</p> + +<h4 id="Optional_files" name="Optional_files">オプションのファイル</h4> + +<p>You may of course have other files. Obvious candidates are an <code>index.html</code> file so that users that browse to your sample see some content, style sheets, support HTML and JavaScript files, images and other media, and so forth.</p> + +<h3 id="Submitting_your_sample" name="Submitting_your_sample">サンプルを投稿する</h3> + +<p>Once you've finished and tested your sample, you will want to submit it so that it can be tested and eventually installed onto the production sample server. This is done using the standard Github <a href="https://help.github.com/articles/using-pull-requests/">pull request</a> process.</p> + +<h2 id="Tips_and_errata" name="Tips_and_errata">Tips とエラッタ</h2> + +<p>Because the sample server itself is still a work in progress, there are quirks and issues with how samples work. Here are some tips that will help you avoid some of the worst potential problems.</p> + +<h3 id="Port_numbers" name="Port_numbers">Port numbers</h3> + +<p>If your sample needs to use a network port, you will have to take care not to inadvertently use one that's already being used by another sample (or by a system service on the server). At some point in the future, there will be an entry in the sample manifest for requesting a port number, so that the system will allocate them and keep track of which are used and which are not. But until then, be careful not to step on any toes!</p> + +<h2 id="進行中の作業">進行中の作業</h2> + +<p>このページそのもの、そしてここに記述されているサーバについては、作業が継続中です。</p> diff --git a/files/ja/mdn/tools/search/index.html b/files/ja/mdn/tools/search/index.html new file mode 100644 index 0000000000..fdef55a96b --- /dev/null +++ b/files/ja/mdn/tools/search/index.html @@ -0,0 +1,158 @@ +--- +title: MDN の検索機能 +slug: MDN/Tools/Search +tags: + - Guide + - MDN Meta + - Site-wide + - Tools +translation_of: MDN/Tools/Search +--- +<div>{{MDNSidebar}}</div> + +<p class="summary"><span class="seoSummary">MDN のオンサイト検索機能では、外部の検索エンジンで MDN の記事を検索した時には得られない多くの機能が提供されます。この記事では MDN の検索エンジンを最大限に活用する方法を記します。</span></p> + +<h2 id="Basic_search_options" name="Basic_search_options">基本的な検索オプション</h2> + +<h3 id="Filtering_results" name="Filtering_results">結果をフィルタリングする</h3> + +<p>MDN で検索クエリの結果を表示する際に、トピック、技術レベル、文書タイプで結果をフィルタリングするオプションがあります。これは、関連するキーワードが複数の文脈で表示される可能性のあるメソッドを探している場合などに便利です。トピックフィルターを使用して、最も興味のある API の結果のみを表示することができます。これらのフィルターは、ページに設定されたタグによって、どのページを含めるか除外するかを決定します (ページを作成または編集する際に<a href="/ja/docs/MDN/Contribute/Howto/Tag">適切にタグ付けする</a>のはこれが理由です)。以下の種類のフィルターを適用することができます。</p> + +<dl> + <dt>トピック</dt> + <dd>トピックのタグに従って検索結果を絞り込む</dd> + <dt>技術レベル</dt> + <dd><strong>Beginner</strong>, <strong>Intermediate</strong>, <strong>Advanced</strong> の各タグで絞り込む</dd> + <dt>文書タイプ</dt> + <dd><strong>Example</strong>, <strong>Guide</strong>, <strong>Tools</strong> の各タグで絞り込む</dd> +</dl> + +<h2 id="Advanced_search_options" name="Advanced_search_options">高度な検索オプション</h2> + +<p>MDN 貢献者向けに特定のマクロや HTML 属性などを検索できるよう、マクロの出力ではなく生の HTML でページのソースを検索できる高度な検索機能を用意しています。</p> + +<p>今のところこの高度な検索用のユーザーインターフェイスは用意しておらず、URL で直接アクセスすることで利用できます。検索結果は通常の MDN の検索結果ページあるいは JSON フォーマットのいずれかで得られます (後者の検索結果は例えば KumaScript などから使うこともできます)。この節ではその使い方を説明します。</p> + +<p><strong>注:</strong> ここで紹介する検索クエリーは広く利用される目的で作る URL ではありません。ツールやユーティリティから使用するためのものであり、将来変更される可能性があります。クエリーのパフォーマンスも高くない場合があります。</p> + +<h3 id="Search_query_format" name="Search_query_format">検索クエリーの書式</h3> + +<p>高度な検索クエリーは検索に適切な引数を付けた URL で実行してください。ベースとなる URL は次のいずれかです。</p> + +<dl> + <dt><code>https://developer.mozilla.org/ja/search</code></dt> + <dd>通常の MDN 検索結果ページを出力とする場合はこちらを使います。</dd> + <dt><code>https://developer.mozilla.org/ja/search.json</code></dt> + <dd>JSON 形式で結果を取得する場合はこちらを使います。検索結果の書式については {{anch("JSON response body format")}} をご覧ください。</dd> +</dl> + +<p>これに続けて、欲しい結果を得るには適切なパラメータを追加してください。次のパラメータを組み合わせて利用できます:</p> + +<dl> + <dt><code>q=</code></dt> + <dd>マッチする検索クエリー。これは基本検索で使われるパラメーターと同じです。</dd> + <dt><code>locale=</code></dt> + <dd>検索対象とするロケール。既定ではすべてのロケールが対象となります。すべてのロケールを明示的に指定するにはワイルドカード "*" を指定することもできます。例えば、 <code>locale=ja</code> とすれば検索結果を日本語だけに絞り込めます。</dd> + <dt><code>css_classnames=</code></dt> + <dd>検索対象とする CSS クラス名。ページの HTML に少なくとも指定されたクラスが 1 つ以上含まれているページを検索します。</dd> + <dt><code>html_attributes=</code></dt> + <dd>検索対象とする HTML 属性テキスト。これは前方一致検索です。つまり、指定したテキストが HTML の属性文字列の始めにある場合、検索にマッチします。詳しくは下記をご覧ください。</dd> + <dt><code>kumascript_macros=</code></dt> + <dd>検索対象とする 1 つ以上の KumaScript のリスト。これをつかって特定のマクロを使った記事を検索できます。例えば、マクロを廃止する場合や、パラメータが変更され既存のページを更新する必要がある場合に便利です。</dd> + <dt><code>highlight=</code></dt> + <dd><code>true</code> か <code>false</code> のどちらかで、既定では <code>true</code> です。検索クエリーにマッチする結果の周りに <code><a href="/ja/docs/Web/HTML/Element/mark"><mark></a></code> 要素を含めるかどうかを決めます。</dd> + <dt><code>per_page=</code></dt> + <dd>100以下の数値です。既定では Kuma はページ当たり10個の結果を出力します。それとは異なる値を使用する場合にこの引数を使用してください。</dd> +</dl> + +<h3 id="Examples" name="Examples">例</h3> + +<p>検索例をいくつか示します。</p> + +<h4 id="Searching_by_locale" name="Searching_by_locale">ロケールによる検索</h4> + +<pre class="syntaxbox notranslate">https://developer.mozilla.org/en-US/search?locale=<var>ja</var></pre> + +<p>この例では日本語の記事のリストが得られます。言語 (ロケール) 以外での絞り込みはされません。このページの翻訳時点では 12092 ページが見つかります (もちろん翻訳ページは増え続けているのであなたが試すときにはもっと大きな数になっているはずです！)</p> + +<h4 id="Searching_by_CSS_class_name" name="Searching_by_CSS_class_name">CSS クラス名による検索</h4> + +<pre class="syntaxbox notranslate">https://developer.mozilla.org/ja/search?locale=ja&css_classnames=<var>smaller</var></pre> + +<p>この例では CSS で <code>smaller</code> クラスを使っている記事のリストが得られます。ページ翻訳時点では 42 ページに絞り込まれます。</p> + +<h4 id="Searching_by_HTML_attribute_string" name="Searching_by_HTML_attribute_string">HTML 属性文字列による検索</h4> + +<pre class="syntaxbox notranslate">https://developer.mozilla.org/ja/search?locale=ja&html_attributes=<var>style</var></pre> + +<p>この例では HTML 要素に <code>style</code> 属性が使われている記事のリストが得られます。ページ翻訳時点では 7277 ページが該当します。これらはダメなページで修正されるべきものです。少しずつ標準化したクラスで置き換えていく必要があります。</p> + +<p>属性値も含めて検索することはできますが、検索文字列に <code>=</code> や <code>/</code> を含める場合にはこれらを URL エンコードする必要があることに注意してください。例えば、www.mozilla.org にリンクしているページは次のように検索します:</p> + +<pre class="syntaxbox notranslate">https://developer.mozilla.org/ja/search?locale=ja&html_attributes=<var>href%3D%22https%3A%2F%2Fwww.mozilla.org</var></pre> + +<p>この検索結果は 80 件になりました。www.mozilla.org にリンクしているページは意外と少ないですね！</p> + +<h4 id="KumaScript_マクロの使用状況による検索">KumaScript マクロの使用状況による検索</h4> + +<pre class="syntaxbox notranslate">https://developer.mozilla.org/ja/search?locale=ja&kumascript_macros=<var>TemplateLink</var></pre> + +<p>この例では {{TemplateLink("TemplateLink")}} マクロを使用しているページを検索します。マクロの引数が変更された時や、マクロの使用をやめたいときに検索することができます。</p> + +<h3 id="JSON_response_body_format" name="JSON_response_body_format">JSON レスポンス本文の書式</h3> + +<p>JSON で検索結果を取得する場合も、通常の検索結果ページ同様に数件ずつのページ単位で結果が返されます。各ページには検索結果に関するメタデータが含まれる KumaScript オブジェクトと、通常のページオブジェクトにページ編集用の URL フィールドが追加されたものの配列が返されます。</p> + +<p>結果のオブジェクトに含まれるデータは次の通りです。</p> + +<dl> + <dt><code>count</code></dt> + <dd>検索結果の総数</dd> + <dt><code>next</code></dt> + <dd>検索結果の次ページ URL (あるいは最終ページの場合は {{JSxRef("Global_Objects/null", "null")}})</dd> + <dt><code>previous</code></dt> + <dd>検索結果の前ページ URL (あるいは最初のページの場合は {{JSxRef("Global_Objects/null", "null")}})</dd> + <dt><code>query</code></dt> + <dd>結果を検索するのに使われた検索クエリー</dd> + <dt><code>page</code></dt> + <dd>このオブジェクトに含まれる検索結果ページ番号</dd> + <dt><code>pages</code></dt> + <dd>検索結果ページの総数</dd> + <dt><code>start</code></dt> + <dd>このページの結果のうち最初の項目の番号</dd> + <dt><code>end</code></dt> + <dd>このページの結果のうち最後の項目の番号</dd> + <dt><code>filters</code></dt> + <dd>さまざまな検索フィルターの設定を含めた配列。通常の検索に利用可能なフィルターです</dd> + <dt><code>documents</code></dt> + <dd>マッチしたページの{{anch("Page_objects", "ページオブジェクト")}}の配列</dd> +</dl> + +<h4 id="Page_objects" name="Page_objects">ページオブジェクト</h4> + +<p>各ページオブジェクトには次のものが含まれます。</p> + +<dl> + <dt><code>title</code></dt> + <dd>記事タイトル</dd> + <dt><code>slug</code></dt> + <dd>記事のスラグ。ページの URL のうち、ロケール名とスラッシュに続くものすべてです。</dd> + <dt><code>locale</code></dt> + <dd>ページのロケール</dd> + <dt><code>excerpt</code></dt> + <dd>ページコンテンツの断片 (スニペット)。これは記事本文の冒頭部分か、"SEO Summary" クラスが使われていればそのクラスで指定されたコンテンツ。<a href="/ja/docs/MDN/Contribute/Tools/Search$edit#Search_query_format">検索クエリ引数</a>内で <code>highlight=false</code> を指定しない限り、excerpt には <code><a href="/ja/docs/Web/HTML/Element/mark"><mark></a></code> 要素が入ります。</dd> + <dt><code>url</code></dt> + <dd>ページの完全な URL</dd> + <dt><code>edit_url</code></dt> + <dd>ページを編集モードで開く完全な URL</dd> + <dt><code>tags</code></dt> + <dd>ページのタグの配列</dd> + <dt><code>score</code></dt> + <dd>検索エンジンで割り当てられたスコア値</dd> + <dt><code>explanation</code></dt> + <dd>検索クエリーにどのように何故マッチしたかという検索エンジンからの雑多な情報。このコンテンツの詳細についてはこのページでは解説しません。</dd> +</dl> + +<h2 id="See_also" name="See_also">関連情報</h2> + +<p>追加の<a href="/ja/docs/MDN/Kuma/Getting_started#Finding_pages">管理者のみの検索機能</a>がいくつかあり、例えばスラッグが特定の文字で始まっているページを検索したりすることができます。</p> diff --git a/files/ja/mdn/tools/template_editing/index.html b/files/ja/mdn/tools/template_editing/index.html new file mode 100644 index 0000000000..d32794f82e --- /dev/null +++ b/files/ja/mdn/tools/template_editing/index.html @@ -0,0 +1,38 @@ +--- +title: テンプレートの編集 +slug: MDN/Tools/Template_editing +tags: + - Page-level +translation_of: MDN/Tools/Template_editing +--- +<div>{{MDNSidebar}}</div><p>MDNでは、 <a href="/ja/docs/MDN/Contribute/Tools/KumaScript">KumaScript</a> で書かれたテンプレートがコンテンツの自動生成、およびページのカスタマイズに使われています。 それぞれのテンプレートは、別々の Wiki ページに置かれていて、ページ名は以下のとおりです:<br> + <code>/en-US/docs/Template:<em>テンプレートの名前</em></code></p> + +<p><span class="seoSummary">MDN の Wikiを編集している人なら誰でも、マクロを通じてテンプレートを呼び出すことができます。KumaScript は強力なので、テンプレートの作成と編集のための権限は、必要な経験を持ち合わせた信頼できるユーザーのみに与えられています。</span></p> + +<h2 id="この権限を持つ役割の人">この権限を持つ役割の人</h2> + +<ul> + <li><a href="/ja/docs/MDN/Community/Roles/Admins"><strong>MDN管理者</strong></a></li> + <li><a href="/ja/docs/MDN/Community/Roles/Topic_driver_role"><strong>トピックドライバ</strong></a></li> + <li><a href="/ja/docs/MDN/Community/Roles/Localization_driver_role"><strong>ローカライゼーションドライバ</strong></a></li> +</ul> + +<h2 id="この権限を得るための条件">この権限を得るための条件</h2> + +<p>このツールにアクセスする権限を得るための条件は以下のとおりです:</p> + +<ul> + <li><strong>常に</strong>この権限を必要としていること。 例えば、新しいマクロの作成する、古いマクロを修正する、または多くをローカライズするなど。</li> + <li>MDN を定期的に編集していて、 JavaScript でのコードの書き方を知っていること、そしてKumaScript によるテンプレートの制約とリスクを知っていること。</li> + <li>"テンプレート編集権限を持っているpeer" のうち<strong>2人による</strong>保証があり、なおかつどの peer からも<strong>拒否</strong>されていないこと。</li> +</ul> + +<p>この権限を得るためのプロセスについては、<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Processes/Requesting_elevated_privileges">上位権限のリクエスト</a> を見てください。</p> + +<h2 id="テンプレート編集の権限を持っている人（peer）たち">テンプレート編集の権限を持っている人（peer）たち</h2> + +<ul> + <li>現在の peer: <a href="/en-US/profiles/sheppy/">Sheppy</a>, <a href="/en-US/profiles/teoli">teoli</a>, <a href="/en-US/profiles/Fscholz">fscholz</a>, <a href="/en-US/profiles/wbamberg">wbamberg</a>, <a href="/en-US/profiles/Chrisdavidmills">chrisdavidmills</a>, <a href="/en-US/profiles/Jeremie">Jeremie</a>.</li> + <li>新たな peer の追加、peer の削除は、現在の peer の賛同を得ることで行われます。</li> +</ul> diff --git a/files/ja/mdn/tools/zones/index.html b/files/ja/mdn/tools/zones/index.html new file mode 100644 index 0000000000..2bb4599e2d --- /dev/null +++ b/files/ja/mdn/tools/zones/index.html @@ -0,0 +1,203 @@ +--- +title: ゾーン +slug: MDN/Tools/Zones +tags: + - Deprecated + - Guide + - MDN Meta + - Site-wide + - Tools +translation_of: Archive/MDN/Zones +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary"><strong>ゾーン</strong>は MDN の特別なエリアで、そのコンテンツは特別ゾーンナビゲーションボックス、ページのヘッダにおける強調された視覚要素のような追加ユーザインタフェースと共に提供されます。</span> このガイドはゾーンの構築と維持について取り扱います。</p> + +<div class="warning"> +<p><strong>ゾーンの使用は廃止されました</strong><br> + Due to an unsatisfactory user experience and the performance costs of its implementation, we are in the process of deprecating zones. <em>Please only create a new zone if you absolutely must</em>; generally, this should only be done to fix problems related to content which is a zone in English but not in other locales. Please drop into #mdn on IRC to ask questions about anything you read here, especially if you're considering creating a zone or turning any existing material into a zone.</p> +</div> + +<h2 id="ゾーンの特徴">ゾーンの特徴</h2> + +<p>Once you've created a zone, as covered below, you have various special features and abilities that you can, and should, take advantage of:</p> + +<ul> + <li>A colored header area with a color that uniquely identifies your zone.</li> + <li>A "hero image" representing the zone in the header area.</li> + <li>A zone landing page, at the base of the zone's navigation hierarchy, which presents a larger than usual banner area with the hero image in a large size and space for a short blurb describing the zone.</li> + <li>A special navigation sidebar; zones may include content from anywhere on MDN in this navigation, even if they're not actually contained within the zone's direct hierarchy.</li> + <li>Subpages of the zone's landing page — that is, pages actually physically located beneath the landing page — inherit the zone's color and hero image, with a smaller banner area at the top of the page.</li> +</ul> + +<p>There are basically two types of zone: the <strong>in-wiki zone</strong>, and the <strong>mini-site zone</strong>.</p> + +<h3 id="Wiki_内のゾーン">Wiki 内のゾーン</h3> + +<p>An <strong>in-wiki zone</strong> is a zone which takes advantage of zone functionality while remaining part of the main flow of MDN's documentation content. These are sort of semi-zones, in that they generally don't include content from outside their own hierarchy.</p> + +<p>An in-wiki zone allows a segment of MDN to add the additional visuals and, probably more importantly, the zone navigation sidebar, without removing the user from the main flow of MDN content.</p> + +<div class="note"> +<p><strong>Note:</strong> In-wiki zones do not typically appear in the "Zones" list on the MDN home page, since they're treated as part of the main body of MDN's documentation content.</p> +</div> + +<h3 id="ミニサイト_ゾーン">ミニサイト ゾーン</h3> + +<p>A <strong>mini-site zone</strong> is a zone which, while edited and managed using the same interface as any wiki page on MDN, is presented outside the main flow of documentation content. In all functional respects, it supports all the standard wiki functionality provided by the <a href="/en-US/docs/MDN/Kuma">Kuma</a> platform on which MDN is built. A good example is the <a href="/en-US/Apps">App Center</a>.</p> + +<p>When a mini-site zone is created, it is given a new URL outside the "/docs/" tree on MDN, typically at the URL <code>https://developer.mozilla.org/<em><locale></em>/zone/<em><your_zone_name></em></code>.</p> + +<div class="note"> +<p><strong>Note:</strong> In general, only very high-profile, special-purpose content should be moved out of the wiki hierarchy; these zones are intended primarily for setting up special-purpose promotional and/or program-related content.</p> +</div> + +<h2 id="何をゾーンにするべきか">何をゾーンにするべきか?</h2> + +<p>This is an interesting question, and to be honest, the answer is likely to change over time. Zones are a new concept for MDN, and we're still learning exactly how we'll use them.</p> + +<p>There are basically two reasons to create a zone:</p> + +<ol> + <li>You need to set up a <strong>mini-site</strong> for a promotional campaign or a specific product.</li> + <li>You want to create a one-stop shop, so to speak, for a topic that spans multiple technology areas.</li> +</ol> + +<h2 id="ゾーンを作成する">ゾーンを作成する</h2> + +<p>The first step is to create the content. At a minimum, you need to create the initial landing page that will become the root page for your zone. Once you have at least the root page, and possibly even your sub-content, you can then have the pages turned into a zone.</p> + +<p>In order to turn a section of MDN into a zone requires MDN administrator privileges, so you'll need to ask an MDN administrator to do it for you. There are a few things you'll need to provide to the admin as part of your request:</p> + +<ul> + <li>What page on MDN should be turned into the root page for the new zone. Keep in mind that all pages below it in the site's hierarchy will become part of the zone.</li> + <li>Is your zone an {{anch("In-wiki zones", "in-wiki zone")}} or a {{anch("Mini-site zones", "mini-site zone")}}?</li> + <li>You'll need to provide style information and artwork for the customization of the header area in the new zone. See {{anch("Customizing the appearance")}} for details.</li> +</ul> + +<div class="note"> +<p><strong>Note:</strong> Because zones are a special-purpose construct, you will likely be asked to justify why the content should be a zone at all. Refer to {{anch("What should be a zone.3F", "What should be a zone?")}} for insight.</p> +</div> + +<h2 id="ゾーンのアクセスポリシーを変更する">ゾーンのアクセスポリシーを変更する</h2> + +<p>At this time, there's no functional support for access control for zones. This functionality is coming in the future. If you need access control for your zone, please let us know, so we can adjust the priority of that work.</p> + +<h2 id="表示をカスタマイズする">表示をカスタマイズする</h2> + +<p>Part of what makes a zone a zone is the ability to customize its visual identity. Minimally, this means a special color and image used as the background in the header area of the zone's pages to help the user know that they're in a specific zone. It's also possible to make other basic adjustments to the appearance of the page, as long as the overall feeling of being on MDN is retained.</p> + +<div class="note"> +<p><strong>Note:</strong> It's important to keep in mind that the instructions below are <strong>suggestions</strong>. You can try to tinker further with the CSS for your zone. Just keep in mind that your changes may be reviewed by our UX and/or design teams, and will be expected to blend in well with the rest of MDN.</p> +</div> + +<h3 id="基本的なカスタマイズ">基本的なカスタマイズ</h3> + +<p>The basic, required customizations for each zone are the background color and image for the header area of the pages in the zone. When requesting that a zone be created, you'll be asked to provide these. Here are basic guidelines to what you need to provide.</p> + +<ul> + <li>The background color should be reasonably distinctive from other zones' backgrounds, while being relevant to the topic area covered by the zone. You should specify this to the MDN administrator setting up your zone as a {{cssxref("<color>")}}.</li> + <li>The background image is, by default, presented near the right side of the header area (or the left side in a right-to-left locale). This image may be in any Web-compatible format, although PNG is generally best. It should either blend into your specified background color or (preferably) have a transparent background. As a general rule, the background image should be about 468 pixels wide and 400 pixels tall, although the CSS on the page can be set to use {{cssxref("overflow")}} to crop it if necessary. That said, making the image too large increases page size, so that should be avoided.</li> + <li>The image may be sent to the MDN admin with your zone creation request, or may be one that's already been uploaded to MDN as an attachment to an appropriate page.</li> +</ul> + +<p>With this information, the MDN admin team can set up the basic CSS for your zone for you. If you'd like, however, you can go a step farther and provide the CSS yourself. By following the guidelines in {{anch("Additional customizations")}}, you can experiment with other changes to the appearance of your zone.</p> + +<h3 id="さらなるカスタマイズ">さらなるカスタマイズ</h3> + +<p>If you'd like to investigate additional customization options, take a look at the CSS/stylus template located <a href="https://github.com/mozilla/kuma/blob/master/media/redesign/stylus/zones.styl">in github</a>. This lists all the Stylus CSS for the styles you're allowed to alter using your zone's custom CSS.</p> + +<p>If you wish to perform additional customizations, you may do so, with one major caveat: your customizations must not be so drastic that they make the pages in the zone no longer "feel" like part of MDN.</p> + +<p>When customizing the zone's stylesheet, it's your job to sort out from the template which styles you want to alter and to put together the CSS to do so. Once you've done so, provide that CSS to the MDN admin team, and they'll install it for you.</p> + +<p>All zone-related content has the class <code>zone</code> on it.</p> + +<div class="note"> +<p><strong>Note:</strong> Please note that because the site is actively undergoing development, anything about specific classes and styles discussed here is subject to change without notice.</p> +</div> + +<h4 id="背景色">背景色</h4> + +<p>As mentioned previously, the first thing you're likely to customize is the background color for your zone's header area. The CSS looks something like this:</p> + +<pre class="brush: css notranslate">.zone #main-header, .zone .zone-article-header, .zone .zone-landing-header { + background-color: <strong><em>zone-color</em></strong>; +} +</pre> + +<p>The ID <code>main-header</code> refers to the site navigation area at the very top of the page. This includes the "Mozilla" cross-site navigation tab, search box, and other global navigation functionality.</p> + +<p>The class <code>zone-article-header</code> represents the appearance of the header area on article pages within the zone. That is, all pages other than the base landing page within the zone will have this class on their heading area.</p> + +<p>The class <code>zone-landing-header</code> is used for the header area on the zone's landing page. This is the taller heading area on the landing page, with the larger image in it.</p> + +<p>As a general rule, you want all of these areas to have the same color; indeed, the article and landing page header colors should be the same. The only reason you might configure them differently is if they were gradients and you wanted to adjust them to have the same overall "average" color despite the different height of the space.</p> + +<p><strong>In short:</strong> Replace <strong><em>zone-color</em></strong> in the CSS snippet above with the {{cssxref("<color>")}} you've selected for your zone color.</p> + +<h4 id="ランディングページのヘッダ画像">ランディングページのヘッダ画像</h4> + +<p>You will also want to change the image that represents your zone on the zone's landing page. This page has a larger header box to accomodate a larger image to represent your zone. The CSS looks like this:</p> + +<pre class="brush: css notranslate">.zone .zone-landing-header .zone-image { + background-image: url(<strong><em>zone-image-url</em></strong>); +} +</pre> + +<p>The <code>zone-image</code> class is used to specify and style the image for your zone's landing page header. This image should be no wider than 468 pixels, although you can override this by using additional CSS here. Simply replace <em><strong>zone-image-url</strong></em> with the URL of the image to use.</p> + +<div class="note"> +<p><strong>Note:</strong> The easiest way to provide the image is to simply attach it to an appropriate page on MDN and use the resulting URL.</p> +</div> + +<h4 id="記事ページのヘッダ画像">記事ページのヘッダ画像</h4> + +<p>Additionally, you should set the image that represents your zone on its subpages. By default, this image is constrained to 200 pixels wide by 400 pixels tall, but, again, that can be overridden.</p> + +<pre class="brush: css notranslate">.zone .zone-article-header .zone-image { + background-image: url(<strong><em>zone-image-url</em></strong>); +} +</pre> + +<p>Just replace <em><strong>zone-image-url</strong></em> with the URL of the image to use.</p> + +<div class="note"> +<p><strong>Note:</strong> The easiest way to provide the image is to simply attach it to an appropriate page on MDN and use the resulting URL. You can choose to use the same image as you do for the landing page header image, with some scaling or cropping applied, or you can use a different image.</p> +</div> + +<h4 id="ヘッダボタンの下の境界">ヘッダボタンの下の境界</h4> + +<p>The last thing you're generally advised to change is the appearance of the bottom border of the buttons in the zone header area. This is the CSS:</p> + +<pre class="brush: css notranslate">.zone .zone-landing-header a.button { + box-shadow: inset 0 -1px <strong><em>color</em></strong>; +} +</pre> + +<p>Here, replace <strong><em>color</em></strong> with a {{cssxref("<color>")}} that is very similar to your background color, but slightly darker.</p> + +<h2 id="ゾーンナビゲーション">ゾーンナビゲーション</h2> + +<h3 id="ゾーンナビゲーションサイドバー">ゾーンナビゲーションサイドバー</h3> + +<p>The sidebar appearing on every page in a zone is defined in the zone's landing page content, in a section called "Subnav" (visible only when editing the page). This section may contain a manually curated list of pages or use a macro, such as {{TemplateLink("ListSubpages")}}. In the latter case you will need to <a href="/en-US/docs/MDN/Kuma/Introduction_to_KumaScript#Caching">force-reload</a> (shift+refresh) the zone's landing page in order to update the sidebar.</p> + +<h3 id="クイックリンク">クイックリンク</h3> + +<p>As is the case with any page on MDN, pages within zones may use the <a href="/en-US/docs/MDN/Contribute/Content/Quicklinks">quicklinks</a> feature. Quicklinks are a navigation box, presented in the left sidebar area, offering links the user may follow to related material. These links may be within MDN or off-site, and may be nested up to two total levels deep, using folders.</p> + +<p>To aid in generating common types of quicklinks for zones, we have some macros you can use.</p> + +<h4 id="QuickLinksWithSubpages">QuickLinksWithSubpages</h4> + +<p>The {{TemplateLink("QuickLinksWithSubpages")}} macro generates all of the HTML required to present a quicklinks box on the page with the links corresponding to the pages in a specified hierarchy. You can also use it with no parameters at all to present quicklinks of subpages of the current page, although this is not commonly as useful in a zone since the zone navigation will generally present this for you.</p> + +<h2 id="ゾーンのスタイルガイド">ゾーンのスタイルガイド</h2> + +<h2 id="注記">注記</h2> + +<p>This section offers some notes that are worth keeping in mind when creating, working with, and using zones.</p> + +<ul> + <li>Every page in a zone automatically inherits the navigation sidebar provided on their zone's root page.</li> + <li>If a page in a zone has a quicklinks section, the quicklinks are displayed below the zone's navigation in the sidebar. Toggling off the quicklinks makes both the quicklinks and the navigation bar disappear, allowing more room for the page content.</li> +</ul> diff --git a/files/ja/mdn/troubleshooting/index.html b/files/ja/mdn/troubleshooting/index.html new file mode 100644 index 0000000000..48b431b4b6 --- /dev/null +++ b/files/ja/mdn/troubleshooting/index.html @@ -0,0 +1,86 @@ +--- +title: トラブルシューティング +slug: MDN/Troubleshooting +tags: + - Documentation + - MDN + - Writing Documentation + - troubleshooting +translation_of: MDN/Troubleshooting +--- +<div>{{MDNSidebar}}</div> + +<p>この記事では、 MDN を利用して起こる問題と、その対処法を記します。</p> + +<h2 id="私の古いアカウントでログインできない">私の古いアカウントでログインできない</h2> + +<dl> + <dt>現象</dt> + <dd>数年前に MDN アカウントを持っていたが、今は唯一のログイン方法が GitHub なのでログインできない。あるいは GitHub でプロファイルを作成済みだが、古いアカウントに接続できない。</dd> + <dt>原因</dt> + <dd>GitHub認証 <a href="/en-US/docs/Archive/MDN/Persona_sign-ins">以外のログイン方法</a> のサポートは2016年11月1日以来削除されました。MDNプロファイルとGitHubアカウントをそれ以前にリンクさせてない場合、古いアカウントではログインできません。</dd> + <dt>対処法</dt> + <dd>Bugzillaで<strong> <a class="external-icon external" href="https://mzl.la/accounthelp">"Account Help" bug</a> </strong>を提出します。古いアカウントについての情報(パスワード以外!)を提供して、新アカウントがあればそれも書きます。MDN エンジニアが反応して手助けします。</dd> +</dl> + +<h2 id="ページを保存できない">ページを保存できない</h2> + +<dl> + <dt>現象</dt> + <dd>あなたが変更したものを保存しようとして、変更が保存できないというメッセージを受けている。</dd> + <dt>原因</dt> + <dd>変更が MDN のスパムトラップに捕捉されています。我々の知る限り、これはときどき間違えます。</dd> + <dt>対処法</dt> + <dd>エラーメッセージに指示されいてるように、リビジョンのコピーを保存して、<a href="mailto://mdn-admins@mozilla.org">MDN サイト管理者</a> にメール送信します。管理者の1人が実際に正当な変更であることを検証して、あなたの変更と同様なものをブロックしないようにスパムフィルターを訓練して、今後はこの問題に会わないように、あなたをホワイトリストに追加します。</dd> +</dl> + +<h2 id="公開した変更がページに出てこない">公開した変更がページに出てこない</h2> + +<dl> + <dt>現象</dt> + <dd>記事にいくらかの変更をして <strong>公開</strong> をクリックする。たった今行った変更が通常のページの見た目に反映されない。</dd> + <dt>原因</dt> + <dd>ページコンテンツがサーバーにキャッシュされていて、ページが変更されて以来リフレッシュされていません。</dd> + <dt>対処法</dt> + <dd>ブラウザーで強制リフレッシュします (例えば Shift+再読み込み)。更新されたコンテンツが見えるか、ページ更新が処理されているメッセージが見えるでしょう。2番目の場合、数分間待ってからページが更新されたかを見るために通常のリフレッシュをします。</dd> +</dl> + +<h2 id="マクロで生成したコンテンツが古い">マクロで生成したコンテンツが古い</h2> + +<dl> + <dt>現象</dt> + <dd>マクロで生成されるコンテンツを含むページを見ている。このマクロが更新されて製品に置かれているのが分かっているが、ページは古い値を表示している。</dd> + <dt>原因</dt> + <dd>マクロの出力がキャッシュされていて、マクロが更新されて以来リフレッシュされていません。このとき、マクロコードへの変更は、そのマクロを使うページに対して自動更新が強制されません。</dd> + <dt>対処法</dt> + <dd>ブラウザーで強制リフレッシュします (例えば Shift+再読み込み)。更新された出力が見えるか、ページ更新が処理されているメッセージが見えるでしょう。2番目の場合、数分間待ってからページが更新されたかを見るために通常のリフレッシュをします。</dd> +</dl> + +<h2 id="ページのスクリプトエラー">ページのスクリプトエラー</h2> + +<dl> + <dt>現象</dt> + <dd>ページ上にこんな恐ろしい赤いボックスが見える:<br> + <img alt="There was a scripting error on this page. While it is being addressed by site editors, you can view partial content below. More information about this error" src="https://mdn.mozillademos.org/files/15259/macro_error_box.png" style="height: 114px; width: 590px;"></dd> + <dt>原因</dt> + <dd>ページ内のマクロでの KumaScript エラーが原因です。マクロが GitHub に保存されて、製品に移される前にレビューやテストを通るようになった今は、この問題は製品ではさほど起こりません。自分自身でマクロを編集したり、マクロを破たんさせる引数と共にマクロを呼び出したりしたら見られる時もあります。ローカルでMDNプラットホームをビルドした場合でも見られるかもしれません。</dd> + <dt>対処法</dt> + <dd>マクロ呼び出しを変更した場合、マクロの引数名を <a href="https://github.com/mdn/kumascript/tree/master/macros">KumaScript GitHub repo</a> と見比べます。疑問のマクロを修正途中の場合、<a href="/en-US/docs/MDN/Contribute/Tools/KumaScript/Troubleshooting">KumaScript エラーのトラブルシューティング</a> が役立つかもしれません。</dd> +</dl> + +<h2 id="ページプレビュー時のスクリプトエラー">ページプレビュー時のスクリプトエラー</h2> + +<dl> + <dt>現象</dt> + <dd>ページを編集していて、<strong>プレビュー</strong>ボタンをクリックする。ページのプレビュー内に(前の節に載っている)スクリプトエラーがある。</dd> + <dt>原因</dt> + <dd>編集しているページ内に既存のスクリプトエラーがあるか、あるいはあなたがマクロの引数を変えたりすることでエラーを導入した。</dd> + <dt>対処法</dt> + <dd> + <p>あなたがページ内のマクロやテンプレートを修正していないのが本当に確実なとき、このエラーを無視できます。編集したページが最終的に保存されて再度通常表示されたときにエラーが消えるのが期待できます (通常表示でエラーがない限り)。</p> + + <p>あなたがエラーを導入したかどうかわからない場合、新しいウィンドウで同じページのコピーを開きます (そのページの最後に保存された版が出てきます)。編集モードに入り、すぐに<strong>プレビュー</strong> をクリックします。ここでエラーが起こった場合は、自信をもってあなたは原因ではないですし、その前に記述されたものでは消えている可能性が高いでしょう。</p> + + <p>あなたの変更について、古いウィンドウからの古いエラーと同じく新しいエラーが出ている場合、新しいウィンドウを閉じて古いウィンドウで作業を続けます。しかしながら、これらが別のエラーの場合、古いウィンドウで本当に何か壊したのかもそれませんので、注意して新しいウィンドウに変更をコピーして、そのたびに<strong>プレビュー</strong> をクリックします。古いエラーがすぐにここにも出る場合、あなたが最後に行った変更がエラーを起こした可能性が高く、その成果をよく調べるべきでしょう。最終的に、副作用として、<strong>プレビュー</strong>を何度もクリックして常にプレビューウィンドウを残している場合、エディターが失敗したり成果が失われる(破棄するときに起こりかねない)場合にも、素早くて未保存のままの大半の変更のコピーが残るでしょう。</p> + </dd> +</dl> diff --git a/files/ja/mdn/user_guide/writing/index.html b/files/ja/mdn/user_guide/writing/index.html new file mode 100644 index 0000000000..7fa04b601b --- /dev/null +++ b/files/ja/mdn/user_guide/writing/index.html @@ -0,0 +1,59 @@ +--- +title: コンテンツの作成 +slug: MDN/User_guide/Writing +tags: + - MDN + - MDN Project +translation_of: Archive/Meta_docs/Writing_content +--- +<p>MDN には、いつもたくさんのページの追加やアップデートがあります。たとえば、真新しいAPI のドキュメントや若干の変更がある古いAPIのページがあり、あなたの翻訳はいつでも役立ちます。</p> + +<h2 id="既存のページを編集する">既存のページを編集する</h2> + +<p>訂正したいページを見つけたら、右上の「編集」ボタンをクリックしてください。すると、該当ページが編集可能になったWYSIWYGエディタが開きます。どのように編集するかは、<a href="/docs/Project:MDN/Contributing/Editor_guide">MDN のエディタガイド</a>を読んでください。コンテンツの構築とレイアウトを自動的に手助けするマクロシステムなどの説明もあります。</p> + +<p>次のような場合に、既存ページの編集が必要です。</p> + +<ul> + <li>誤字脱字</li> + <li>わかりにくい表現</li> + <li>レイアウトや形式が乱雑</li> + <li>API ドキュメントの更新と、API のアップデートに合わせた更新</li> + <li>複数のブラウザの異なる振る舞いに関する情報</li> + <li>サンプルコードの追加と改善. 詳細は、{{anch("Add a code sample")}} を参照</li> + <li>仮ページ、または重要な情報の不足</li> +</ul> + +<h2 id="新しいページを作成する">新しいページを作成する</h2> + +<p>これは大きな出来事です！MDN に新しいページを追加すると、Webがあなたを愛しあなたを抱きしめてくれるでしょう。まだドキュメント化されていない API や新しい話題のチュートリアル・解説記事というように、新しいページの作成は、とても役に立ちます。</p> + +<p>MDN には、次のように新しいページの作成を始める方法があります。<a href="/docs/Project:MDN/Contributing/Getting_started#Logging_into_MDN">ログイン</a>してから始めてください:</p> + +<dl> + <dt>存在しないページのリンクをクリック</dt> + <dd>MDN をブラウズしていると、存在しないページへのリンクが見つかることがあるでしょう。リンク先のページを作らずに、記事を書くことがあるからです。これは、最終的にページ構成がどうなるか理解する手助けになるのですが、そこに取りかかるまでに、時間がかかる場合もあります。そんなところを見つけたら、自由に作業してみてください。リンクをクリックして、新規ページを編集すればいいのです。</dd> + <dt>サブページの作成</dt> + <dd>右上あたりの歯車マークから、<strong>"サブページを作成"</strong> を呼び出すことができます。この項目を選ぶと、そのとき表示していたページを親にした、新しいページの編集画面が開きます。タイトルとスラッグを設定したら、記事を書き始めましょう。</dd> + <dt>このページを複製</dt> + <dd>歯車マークの<strong>"このページを複製"</strong> オプションで、現在のページのコピーを作ることができます。この項目を選ぶと、そのとき表示していたページを複写した、新しいページの編集画面が開くので、タイトルとスラッグを設定しましょう。新しいページを作る場合、これはわりといい方法です。なぜなら、元と同じようなレイアウトで簡単にページを作れるからです。</dd> + <dt>存在しないページへのリンクを作成してクリック</dt> + <dd>これは、いくつかの方法の組み合わせです。どのページもどこからかリンクされている必要があるので、現在存在しているページから、新しいページにリンクを貼ってしまうのです。それから、元のページをいったん保存して、今挿入したリンクをクリックすれば、新しい記事の編集画面が開きます。</dd> +</dl> + +<div class="note"> +<p><strong>注記:</strong> ログインしていない場合、新しいページを編集するかわりに、404エラーが出るかもしれません。</p> +</div> + +<h2 id="関連情報">関連情報</h2> + +<p>ここでは、コンテンツ作成を始めるためのいくつかのヒントや確実に役立つ注意すべき情報を紹介しています。</p> + +<dl> + <dt><a href="https://wiki.mozilla.org/Modules">モジュールオーナー一覧 (Module owner lists)</a></dt> + <dd>Mozilla プロジェクトは、モジュールオーナーベースで活動しており、主要なコンポーネントは、オーナーまたは責任者がいます。このオーナーたちは、あなたが何かするときの最適な情報源です。あるいは、誰と話をすればいいか見つける一番の方法です。</dd> + <dt><a href="http://mxr.mozilla.org/">Mozilla ソースのクロスリファレンス (Mozilla source cross-reference)</a></dt> + <dd>MXR (Mozilla クロスリファレンス、Mozilla cross-reference) は、Mozilla プロジェクトのすべてのソースコードにアクセスできる場所です (一部の例外を除きます。例えば、Firefox OS のソースコードは GitHub 上にあります)。コードとそこに書かれたコメントは、とても役に立つ情報源です。</dd> + <dt><a href="http://wiki.mozilla.org/">Mozilla wiki</a></dt> + <dd>The Mozilla wiki — "wikimo" とも呼ばれます — は、プロセスやデザインノート・ドラフト・計画・暫定の仕様などが保存されています。雑然と混乱していますが、多くの場合、貴重な情報の宝庫になっています。</dd> +</dl> |