diff options
Diffstat (limited to 'files/ja/mdn/guidelines')
| -rw-r--r-- | files/ja/mdn/guidelines/code_guidelines/css/index.html | 255 | ||||
| -rw-r--r-- | files/ja/mdn/guidelines/code_guidelines/general/index.html | 160 | ||||
| -rw-r--r-- | files/ja/mdn/guidelines/code_guidelines/html/index.html | 165 | ||||
| -rw-r--r-- | files/ja/mdn/guidelines/code_guidelines/index.html | 80 | ||||
| -rw-r--r-- | files/ja/mdn/guidelines/conventions_definitions/index.html | 201 | ||||
| -rw-r--r-- | files/ja/mdn/guidelines/css_style_guide/index.html | 861 | ||||
| -rw-r--r-- | files/ja/mdn/guidelines/does_this_belong_on_mdn/index.html | 202 | ||||
| -rw-r--r-- | files/ja/mdn/guidelines/editorial/index.html | 45 | ||||
| -rw-r--r-- | files/ja/mdn/guidelines/index.html | 16 | ||||
| -rw-r--r-- | files/ja/mdn/guidelines/video/index.html | 230 | ||||
| -rw-r--r-- | files/ja/mdn/guidelines/writing_style_guide/index.html | 814 |
11 files changed, 3029 insertions, 0 deletions
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> |