diff options
Diffstat (limited to 'files/ja/mdn/guidelines/writing_style_guide/index.html')
| -rw-r--r-- | files/ja/mdn/guidelines/writing_style_guide/index.html | 814 |
1 files changed, 814 insertions, 0 deletions
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> |