ウィキペディア:テンプレートドキュメント

ウィキペディアから、無料の百科事典
ナビゲーションにジャンプ 検索にジャンプ

テンプレートMediaWikiの非常に強力な機能ですが、新しいユーザーを混乱させる可能性があり、経験豊富なユーザーでさえ、より複雑なものを理解するのが難しい場合があります。したがって、テンプレートには、使いやすさを向上させるためのドキュメント添付する必要があります

テンプレートのドキュメントでは、テンプレートの機能と使用方法を説明する必要があります。テンプレート構文の複雑さを完全に理解していないユーザー(他の場所に注意を向ける経験豊富な寄稿者を含む)が正しく使用できるように、十分に単純である必要があります。これは、非常に広く使用されているテンプレートの場合に特に当てはまります。

テンプレートのドキュメントページが確立されたコミュニティの基準や原則と矛盾する場合、編集者は公式のポリシーまたはガイドラインに従う必要があります。編集者は、このハウツーガイドを含め、テンプレートのドキュメントページをポリシーであるかのように「引用」することも避けてくださいコミュニティによって徹底的に精査されたウィキペディアのポリシーとは対照的に、テンプレートのドキュメントページは、(あるとしても)あまり議論することなく作成できます(詳細については、WP:ローカルコンセンサスを参照してください)。

何を含めるか

テンプレートドキュメントは以下をカバーする必要があります:

  • テンプレート基本的な目的:それが何をするのか、そしてそれがすぐに明らかでない場合は、なぜそれを行う必要があるのか​​。同様の名前または目的を持つ他のテンプレートがある場合は、間違ったテンプレートが使用される可能性を減らすために、それらに言及することをお勧めします。テンプレートを特定の国や期間にのみ使用する必要がある場合、モバイルWebサイトに{{ Navboxの可視性}}がないなどの重要な制限またはテンプレートの使用を選択する前に編集者が知っておく必要のあるその他の事項を含めます
  • テンプレートパラメーター:番号が付けられているか、名前が付けられているか、オプションであるか、そうである場合は、デフォルト値とその効果。パラメータが限られた値のセットしかとることができない場合、または何らかの方法で制約されている場合、たとえば、「yes」、「no」、または数値しか使用できない場合は、これを明確に説明する必要があります。
  • 使用例使用する正確なウィキテキストとそれが生成する結果を指定します。ウィキテキストは<code>...</code>、明確にするためにコンテナで囲むことができますeasy to copy, like thisたとえば、テンプレートをオプションのパラメーターの有無にかかわらず、いくつかの異なる方法で使用できる場合は、さまざまな例を示します。そのための良い方法は、テンプレート自体をドキュメントに数回トランスクルージョンすることです(つまり、ライブの例を使用します)。そのたびに異なるパラメーターを使用し、それぞれの場合に使用されるパラメーターをリストします。テンプレート:XPDこれはウィキテキストで二回テンプレートコールをかけることなく行うことができます。
  • TemplateDataタグ:Wikipedia:TemplateData / Tutorialを参照してください
  • 関連テンプレート:テンプレートが一連のテンプレートの1つである場合は、これらへのリンクを含めます。特に、ナビゲーションが容易になるため、一連のすべてのテンプレートが他のテンプレートからリンクされていることを確認してください。(この目的には、別のナビゲーションテンプレートが役立つ場合があります。テンプレート:保護テンプレートを参照してください)。
  • カテゴリー適用( InterWikimediaリンクはで表示される必要がありウィキデータ-の詳細はウィキペディア:ウィキデータ)。ドキュメントと同様に、カテゴリは<noinclude>...</noinclude>テンプレートのコンテナ内、または<includeonly>{{Sandbox other||...}}</includeonly>ドキュメントページに配置されている場合タグ内にリストする必要があります。多くのテンプレートカテゴリが利用可能です。それらを参照するには、 Category:Wikipediaテンプレートを参照してください。

英語版ウィキペディアは、他の何百ものウィキペディアや姉妹プロジェクトのテンプレートのソースです。多くの場合、テンプレートは完全に自己完結型であるため、プロセスは簡単です。コンテンツは他のWikiの新しいテンプレートページにコピーされるだけで、すべてが機能します。ただし、より複雑なテンプレートでは、テンプレートがモジュールを呼び出したり、他のテンプレートをトランスクルージョンしたり、別のテンプレートとペアになっている場合にのみ機能したり、特定のCSSまたはJavascriptコードが機能する必要がある場合があります。このような場合、ドキュメントの最後に、これに必要なテンプレートまたはその他のコードの簡単なリストを含めると便利です。

どこに置くか

Template名前空間のテンプレートのページは、そのテンプレートの外観と動作を制御するテンプレートコードの場所です。レンダリングされたテンプレート:ページのタイトルの下に通常表示れるのは([編集]タブの編集ウィンドウ、またはコードが保護されているテンプレートの場合は[ソースの表示]タブとは対照的に、レンダリングされたテンプレート自体であり、その後に別のテンプレートのレンダリングされたドキュメントを表示するセクションの後に、テンプレートが属するカテゴリが続きます。

ただし、テンプレートのドキュメントの編集可能なウィキコードは、多くの場合、テンプレート自体の別のサブページ配置され、テンプレートページの最後にトランスクルージョンされます。これにより、複雑なことが多いテンプレートコードがドキュメントから分離され、ドキュメントの編集が容易になり、テンプレートコードの誤った編集エラーの数が減ります。また、必要に応じてテンプレートを保護し、重要なテンプレートのコードへの編集アクセスを制限すると同時に、誰でもそれらのテンプレートのドキュメントを編集できるようにします。この方法は、「テンプレート-ドキュメントページパターン」と呼ばれることもあります。

テンプレートページ(TemplateDataを含む上のあらゆる種類のドキュメントは<noinclude>...</noinclude>、テンプレートが別のページで使用されたときに表示されないように、常にコンテナで囲む必要があります。

ドキュメントサブページを作成する方法

テンプレートにドキュメントを配置する

テンプレートを作成(公開)するときは、{{ドキュメント}}を入力する必要があります。次に、[view] [edit] [history] [purge]リンクを含むドキュメントページが作成されます。このペインの[edit]リンクをクリックすると、テンプレートドキュメントを作成および編集できます

{{ documentation }}を使用するテンプレートドキュメントサブページは、一貫性を保つために、次の一般的なパターンを使用して名前が付けられ、フォーマットされています。

テンプレートの名前がであるとしますTemplate:Xテンプレートを編集し、テンプレートコードの最後に以下を追加するか、{{subst:doc-code }}を使用します。

[-テンプレートコードの最後の行-] <noinclude>
{{ドキュメンテーション}}
<!-ここではなく、ウィキデータの/ docサブページとインターウィキにカテゴリを追加してください!->
</ noinclude>

これにより、テンプレートページの下部にある{{ドキュメント}}がトランスクルージョンされます。

重要:ことを確認してください開口部は、<noinclude>テンプレートコードまたはテキストの最後の文字の直後に始まるない新しい行に、また任意の間にスペースを持ちます。そうしないと、テンプレートを使用するときにテンプレートの下に余分なスペースが挿入されますが、これは通常は必要ありません。

テンプレートがすでに保護されている場合は、管理者にこれを行うように依頼するか、テンプレートのトークページでを使用し編集をリクエストしてください。ドキュメントとカテゴリがコンテナで囲まれたセクションにすでに存在する場合は、ドキュメントを2つの別々のページに分割しないことが最善であるため、ドキュメントサブページ(で囲む必要があります)に移動します。 {{edit protected}}<noinclude>...</noinclude><includeonly>...</includeonly>

自動作成

[create]空のドキュメントボックスの下部にあるリンクを使用して、プリロードされたドキュメントサブページを自動的に作成します一番上の行とカテゴリの後の適切なコメント行の下にドキュメントを挿入します。コメントはそのままにして、後でページを編集するときにレイアウトが保持されるようにします。関連するテンプレート、ポリシーページ、プロジェクトなどは、「関連項目」セクションを追加することでリンクできます。サブページを保存します。

手動作成

ドキュメントサブページを手動で作成するには、という名前のサブページを作成しますTemplate:X/doc詳細については、{{ドキュメントサブページ}}を参照するか、次の標準ウィキテキストをコピーして貼り付けてページを開始してください。

{{ドキュメント サブページ}} 
<!-このページの下部に示されているカテゴリとウィキデータのインターウィキを追加します->
==使用法==


<includeonly> {{サンドボックス その他|| 
<!- このより下のカテゴリ ; interwikisウィキデータ- >      

}} </ includeonly>

一番上の行には、現在のページを説明するメッセージとテンプレートページへのリンクが表示されます。サブページを保存し、「テンプレートの使用:ドキュメント」の手順に従います

TemplateDataを使用

リードグラフと使用状況テーブルを手動で作成する代わりに、{{ FormatTemplateData }}テンプレートでほとんどの作業を実行できます。TemplateDataをテーブルインターフェイスに記述し{{Format TemplateData|1=<templatedata>...</templatedata>}}、ページ上部のようテンプレート呼び出しにラップするだけです。

ノート

/ docサブページのトークページをテンプレート自体のトークページにリダイレクトすることをお勧めします。その後、テンプレートとそのドキュメントに関連するすべてのトークは、同じトークページになります。たとえば、にリダイレクトTemplate talk:X/docTemplate talk:Xます。

ドキュメントページは、両方のテンプレートの使用法をカバーしている場合は、別のテンプレートの/ docサブページにリダイレクトすることもできます。この場合、リンクをクリックしてドキュメントを表示または編集すると、リダイレクトのターゲットが直接開きます。リダイレクト自体にアクセスする必要がある場合(リダイレクトを削除して別のドキュメントページを作成する場合など)、ブラウザの上部にあるロケーションバーをクリックしてテンプレートのURLに移動し、最後に/ docを追加します。

空欄

空白のテンプレートを生成するには、ドキュメントからコピーして別のページに貼り付けることができます。次を使用します。

{{subst:#tag:pre|{{subst:Parameters|code|base={{subst:BASEPAGENAME}}}}|style=overflow: auto;}}

独自のプロパティ名が入力されたテンプレートのインスタンスを生成するには、次を使用します。

{{subst:Parameters|demo|base={{subst:BASEPAGENAME}}|_base=}}

カテゴリとインターウィキリンク

  • テンプレート自体をカテゴリに配置するにはドキュメントサブページのセクション[[Category:Category name]]コードを追加します<includeonly>...</includeonly>
  • テンプレート自体のためのインターウィキリンクを作成するには、に行くウィキデータおよびページへのリンクを追加するための指示に従ってください。
  • 配置するにはドキュメントのカテゴリにサブページを追加、[[Category:Category name]]内のコードを<noinclude>...</noinclude>上のセクションのdocサブページ。
  • テンプレートで記事をカテゴリに配置するには(記事にテンプレートが含まれている場合)、テンプレートページのセクション[[Category:Category name]]コードを追加し<includeonly>...</includeonly>ます。テンプレートコード内の正確な配置は、カテゴリコードの実行方法に影響を与える可能性があります。

/ sandboxと/ testcases

テンプレートに変更を加える前に、まずテンプレートコードをサンドボックスにコピーして、いくつかのテストケースを実行することをお勧めします。これは、テンプレートが数千または数百万のページに表示される可能性があるためです。テンプレートに対して正確に「/ sandbox」および「/ testcasesという名前のサブページを作成すると、テンプレートの緑色の{{documentation}}ボックスがこれを自動検出し、ヘッダーにそれらのページへのリンクを表示します。詳細については、Wikipedia:テンプレートサンドボックスとテストケース参照してください。

複数のテンプレート、1つのドキュメントページ

複数のテンプレートが連携して機能するか、非常に類似している場合、それらを一緒に文書化する単一の文書化ページを維持する方が明確で簡単なことがよくあります。これを行う最も簡単な方法は、テンプレートの1つで完全なドキュメントページを作成してから、他のテンプレートから「ソフトリダイレクト」を作成することです。たとえば、{{ wrap }}を参照してください

テンプレートページに直接

ドキュメントサブページが作成されておらず、{{ドキュメント}}テンプレートが|content=実際のテンプレートページのパラメータとともに使用されている場合、テンプレート自体をカテゴリに配置する[[Category:Category name]]には、コンテンツの後にドキュメントテンプレート内に追加します。たとえば、実際のテンプレートページに配置するには、次のようにします。

<!-テンプレートコードの最後の行-> <noinclude> 
{{ドキュメント
 |  content  = 
<!- テンプレート ドキュメント ->

[カテゴリカテゴリ ]] 
[[カテゴリーカテゴリー NAME2 ]] 
}} </ NOINCLUDE>

書類が不要な場合

表示されたテンプレートがドキュメントとして機能できるページにリンクする場合、個別のドキュメントは不要であり、作成する必要はありません。たとえば、{{ asbox }}テンプレートをベースとして使用するスタブテンプレートは、そのテンプレートを使用するすべてのスタブテンプレートのプリロードされた共通ドキュメントをすでに表示しており、追加のドキュメントは必要ありません。

ヒントとコツ

ドキュメントの作成を容易にするためのヒントを次に示します。

  • {{ Japanese year | 1800}}のようなテンプレートへのリンクは、{{ tlp | Japanese year | 1800}}と書くことで挿入できます同様のテンプレートについては、{{ tlp }}を参照してください
  • のようなHTMLタグは<ref group="note">...</ref>、{{ tag }}で簡単に挿入できますこの例は、{{ tag | ref | params = group = "note"}}と記述されています。
  • 等号={{=}}で挿入できますたとえば、{{要出典| date = 1900-02-29}}{{ tlp |要出典|日付{{=}} 1900-02-29}}によって作成されます。同等の表記は避けてください&#61; これは他の編集者にとって読みやすいものではありません。
  • 1つの<nowiki />タグを忘れないでください[[ <nowiki />example]]は[[example]]になり、[ <nowiki />http://en.wikipedia.org nolink ]は[ http://en.wikipedia.orgnolink ]になります。詳細については、WP:NOWIKIを参照してください。
  • カテゴリへのリンクには、{{ cat }}を使用しますたとえば、{{ cat |パラメータ構文が正しくないテンプレート}}、パラメータ構文が正しくないCategory:Templatesになります
  • テンプレートの/ sandboxページと/ testcasesページ(存在する場合)の分類を抑制するには、ドキュメントサブページの下部にある次のコードを使用します。
<includeonly> {{サンドボックス その他|| {{その他のテストケース || <! -カテゴリー以下、このラインしてくださいinterwikisウィキデータ- >
         

}}}} </ includeonly>
  • テンプレートが子情報ボックスの場合、ドキュメントは壊れているように見えます。<includeonly>タグを追加して、これを防ぎます。
{{一部の情報ボックス(子)テンプレート
| 子= <includeonly>はい</ includeonly>
| label1 =こんにちは
| data1 =世界
}} <noinclude> {{documentation}} </ noinclude>

も参照してください