「ヘルプ:スタイル」の版間の差分
ナビゲーションに移動
検索に移動
細 (句読点、細かい修正) |
|||
| 106行目: | 106行目: | ||
# Demo |
# Demo |
||
echo "Hello World"}} |
echo "Hello World"}} |
||
| − | * コマンドラインの入力と出力を両方表示する必要がある場合は |
+ | * コマンドラインの入力と出力を両方表示する必要がある場合は {{ic|<nowiki>{{hc|input|output}}</nowiki>}} を使います。例: |
{{hc|$ sh ./hello_world.sh|Hello World}} |
{{hc|$ sh ./hello_world.sh|Hello World}} |
||
| − | * ファイルの中身を表示する必要があり、そのコードがどのファイルを指しているか読者に伝わらないかもしれないときは |
+ | * ファイルの中身を表示する必要があり、そのコードがどのファイルを指しているか読者に伝わらないかもしれないときは {{ic|<nowiki>{{hc|filename|content}}</nowiki>}} を使うことで見出しにファイル名を表示することもできます。例: |
{{hc|~/hello_world.sh|<nowiki> |
{{hc|~/hello_world.sh|<nowiki> |
||
#!/bin/sh |
#!/bin/sh |
||
| 121行目: | 121行目: | ||
=== コマンドラインのテキスト === |
=== コマンドラインのテキスト === |
||
| − | * インラインコード ([[テンプレート:ic]]) 使う場合、プロンプト記号を表示する必要はありませんが、テキストの周囲に必ずパーミッションの注意書きを |
+ | * インラインコード ([[テンプレート:ic]]) 使う場合、プロンプト記号を表示する必要はありませんが、テキストの周囲に必ずパーミッションの注意書きをはっきりとわかるように追加してください。 |
* ブロックコード ([[テンプレート:bc]] や空白文字で始まる行) を使う場合、一般ユーザのコマンドのプロンプトとして {{ic|$}} を、root のコマンドのプロンプトとして {{ic|#}} を使います。{{Note|{{ic|#}} はテキストファイル内のコメントを示すのにも使われるため、通常はコマンドを実行するのかテキストファイルのコメントを示すのかを明確に説明し、曖昧な表現は必ず避けるようにしてください。}} |
* ブロックコード ([[テンプレート:bc]] や空白文字で始まる行) を使う場合、一般ユーザのコマンドのプロンプトとして {{ic|$}} を、root のコマンドのプロンプトとして {{ic|#}} を使います。{{Note|{{ic|#}} はテキストファイル内のコメントを示すのにも使われるため、通常はコマンドを実行するのかテキストファイルのコメントを示すのかを明確に説明し、曖昧な表現は必ず避けるようにしてください。}} |
||
| − | ** コマンドブロックの前置きとなる文の最後は |
+ | ** コマンドブロックの前置きとなる文の最後は通常 {{ic|:}} にしたほうがよいです。 |
| − | ** 特別な事情がない限り |
+ | ** 特別な事情がない限り次を使います: {{bc|# ''command''}} 次は使いません: {{bc|$ sudo ''command''}} |
| − | ** root プロンプトと ''sudo'' コマンドを次のように一緒に使わないでください: {{bc|# sudo ''command''}} 唯一の例外は、''sudo'' が {{ic|-u}} フラグと一緒に使われる場合です: この場合、プロンプトを同じコードブロックの他のプロンプトに合わせることができます。それ以外では |
+ | ** root プロンプトと ''sudo'' コマンドを次のように一緒に使わないでください: {{bc|# sudo ''command''}} 唯一の例外は、''sudo'' が {{ic|-u}} フラグと一緒に使われる場合です: この場合、プロンプトを同じコードブロックの他のプロンプトに合わせることができます。それ以外ではデフォルトの {{ic|$}} を使ってください。 |
** コマンドを含む同じ囲みにコメントを付け足さないでください。例: {{bc|# pacman -S foo #パッケージ foo をインストール}} |
** コマンドを含む同じ囲みにコメントを付け足さないでください。例: {{bc|# pacman -S foo #パッケージ foo をインストール}} |
||
** 極端に長いコードを書くのは避けてください。可能であれば改行をうまく使ってください。 |
** 極端に長いコードを書くのは避けてください。可能であれば改行をうまく使ってください。 |
||
| 132行目: | 132行目: | ||
=== ファイル編集の記述 === |
=== ファイル編集の記述 === |
||
| − | * テキストファイルの編集する必要がある場合、原則 |
+ | * テキストファイルの編集する必要がある場合、原則として特定のテキストエディタ (''nano'', ''vim'', ''emacs'' など) の使用を前提としないでください。 |
| − | * テキストファイルを編集する必要がある場合、厳密な理由がない限り |
+ | * テキストファイルを編集する必要がある場合、厳密な理由がない限り間接的なコマンドを使わないでください。例えば {{ic|$ echo -e "clear\nreset" >> ~/.bash_logout}} は次のようにします: |
::{{ic|~/.bash_logout}} に以下の行を付け加えます: |
::{{ic|~/.bash_logout}} に以下の行を付け加えます: |
||
::{{bc|clear<br>reset}} |
::{{bc|clear<br>reset}} |
||
| 140行目: | 140行目: | ||
=== キーボードキー === |
=== キーボードキー === |
||
| − | * 記事内でのキーボードキーの表示は |
+ | * 記事内でのキーボードキーの表示は通常 [[テンプレート:ic]] のインスタンスを使います。 |
* 文字キーは小文字で表示します: {{ic|a}}。大文字を表示するには {{ic|Shift+a}} を使います。{{ic|Shift+A}} や {{ic|A}} は使いません。 |
* 文字キーは小文字で表示します: {{ic|a}}。大文字を表示するには {{ic|Shift+a}} を使います。{{ic|Shift+A}} や {{ic|A}} は使いません。 |
||
| − | * キーの ''組み合わせ'' は |
+ | * キーの ''組み合わせ'' は {{ic|+}} 記号を用い、その両端に空白文字を付けずにそれぞれのキーを結合するのが正しい表示の仕方です: {{ic|Ctrl+c}}。<br> {{ic|Ctrl + c}}, {{ic|Ctrl}}+{{ic|c}}, {{ic|Ctrl-c}} は準拠していない書式なので使用は避けてください。 |
| − | * キー入力の ''流れ'' は |
+ | * キー入力の ''流れ'' は冗長に説明 (例: {{ic|Shift+t}} に続けて {{ic|g}} を押します) するか、それぞれのキーにテンプレートの別々のインスタンスを用い、それらを1個の半角スペースで区切って簡潔に説明するのが正しい表示の仕方です: {{ic|g}} {{ic|Shift+t}}。 |
* 特別なキーの組み合わせの標準的な表示方法を以下にいくつか示します: |
* 特別なキーの組み合わせの標準的な表示方法を以下にいくつか示します: |
||
** {{ic|Shift}} ({{ic|SHIFT}} ではありません) |
** {{ic|Shift}} ({{ic|SHIFT}} ではありません) |
||
| 164行目: | 164行目: | ||
==== 公式パッケージ ==== |
==== 公式パッケージ ==== |
||
| − | * 公式パッケージのインストールの説明に |
+ | * 公式パッケージのインストールの説明に ''pacman'' のコマンド例を挙げないでください: この規則は、シンプルであるために (すべての Arch ユーザは、[[pacman]] の記事内容を知っておくべきです)、そして {{Ic|pacman -Sy package}} のようなコマンドで起こりうるエラーや、{{Ic|pacman -S package}} か {{Ic|pacman -Syu package}} のどちらを選ぶかのような、起こるかもしれない終わりのない議論を避けるために作られました。そのため、''pacman'' のフロントエンドやラッパーの使用を提案してはいけません。 |
: 代わりに、以下のような記述を使ってください: |
: 代わりに、以下のような記述を使ってください: |
||
:: {{Pkg|foobar}} パッケージを[[インストール]]してください。 |
:: {{Pkg|foobar}} パッケージを[[インストール]]してください。 |
||
| 176行目: | 176行目: | ||
* 言及したパッケージのリンクは必ず貼り、[[テンプレート:Pkg]] を使ってください。例: {{ic|<nowiki>{{Pkg|foobar}}</nowiki>}}。 |
* 言及したパッケージのリンクは必ず貼り、[[テンプレート:Pkg]] を使ってください。例: {{ic|<nowiki>{{Pkg|foobar}}</nowiki>}}。 |
||
* パッケージグループの参照する場合は、代わりに [[テンプレート:Grp]] を使ってください。例: {{ic|<nowiki>{{Grp|foobar}}</nowiki>}}。 |
* パッケージグループの参照する場合は、代わりに [[テンプレート:Grp]] を使ってください。例: {{ic|<nowiki>{{Grp|foobar}}</nowiki>}}。 |
||
| − | * 上記の例では[[インストール]]のリンクを利用しています (例: {{ic|<nowiki>[[install]]</nowiki>}}): インストールの指示が初めて出てくるところでは必ずリンクを使うことを推奨します。特に |
+ | * 上記の例では[[インストール]]のリンクを利用しています (例: {{ic|<nowiki>[[install]]</nowiki>}}): インストールの指示が初めて出てくるところでは必ずリンクを使うことを推奨します。特に Arch 初心者がアクセスするようなページのときはリンクを絶対に付けてください。 |
| − | * メンテナンスを容易にするために、パッケージが ''core''、''extra''、または ''community'' リポジトリでホストされている場合は |
+ | * メンテナンスを容易にするために、パッケージが ''core''、''extra''、または ''community'' リポジトリでホストされている場合はそのリポジトリを参照しないでください。パッケージが別のリポジトリに移されるのはよくあることです。ただし、そのパッケージがデフォルトでは有効化されていない公式リポジトリ (''multilib''、''testing'' など) でホストされている場合は、以下のようにして言及する必要があります: |
::{{Pkg|foobar}} パッケージを公式の [[multilib]] リポジトリから[[インストール]]してください。 |
::{{Pkg|foobar}} パッケージを公式の [[multilib]] リポジトリから[[インストール]]してください。 |
||
==== AUR パッケージ ==== |
==== AUR パッケージ ==== |
||
| − | * AUR パッケージのインストール手順の例は挙げないでください。公式の手順を説明したり、AUR ヘルパーについて述べたりしないでください。非公式パッケージをインストールしようとする全てのユーザーは |
+ | * AUR パッケージのインストール手順の例は挙げないでください。公式の手順を説明したり、AUR ヘルパーについて述べたりしないでください。非公式パッケージをインストールしようとする全てのユーザーは事前に [[Arch User Repository]] に目を通しておき、システムで起こりうるあらゆる結果を把握しておいてください。 |
: 代わりに、以下のように簡潔に述べてください: |
: 代わりに、以下のように簡潔に述べてください: |
||
:: {{AUR|foobar}} パッケージをインストールします。 |
:: {{AUR|foobar}} パッケージをインストールします。 |
||
| 190行目: | 190行目: | ||
==== 非公式リポジトリ ==== |
==== 非公式リポジトリ ==== |
||
| − | * ビルド済みのパッケージをインストールするために |
+ | * ビルド済みのパッケージをインストールするために非公式リポジトリの使用を提案するときは、リポジトリを有効化する方法を書かないでください。そのリポジトリが[[非公式ユーザーリポジトリ]]にかかれていることを確認してページヘのリンクを張ってください。また、[[#公式パッケージ|公式パッケージ]]と同様に、''pacman'' コマンドの例は不要です。例: |
:: [[非公式ユーザーリポジトリ#example|example]] リポジトリから ''foobar'' パッケージをインストールしてください。 |
:: [[非公式ユーザーリポジトリ#example|example]] リポジトリから ''foobar'' パッケージをインストールしてください。 |
||
: パッケージが [[AUR]] からもインストールできる場合: |
: パッケージが [[AUR]] からもインストールできる場合: |
||
| 201行目: | 201行目: | ||
=== systemd ユニットの操作 === |
=== systemd ユニットの操作 === |
||
| − | * ''systemctl'' を用いた [[systemd]] ユニットの有効化、起動、またはその他の基本的操作の例は挙げないでください。代わりに |
+ | * ''systemctl'' を用いた [[systemd]] ユニットの有効化、起動、またはその他の基本的操作の例は挙げないでください。代わりに関連するユニットを挙げて簡潔に説明してください。他のユニットとの依存関係または競合、そして行うべき操作についての説明が必要な場合は述べてください。 |
:: ブート時に GDM を起動させるには、{{ic|gdm.service}} を[[有効化]]してください。例: |
:: ブート時に GDM を起動させるには、{{ic|gdm.service}} を[[有効化]]してください。例: |
||
: または、ユニットがインスタンス化する必要があるテンプレートである場合: |
: または、ユニットがインスタンス化する必要があるテンプレートである場合: |
||
:: 無線インターフェイスの ''netctl'' プロファイルを自動的に切り替えるようにするには、インターフェイスの名前を指定して {{ic|netctl-auto@.service}} のインスタンスを[[有効化]]してください。例: {{ic|netctl-auto@wlan0.service}}。 |
:: 無線インターフェイスの ''netctl'' プロファイルを自動的に切り替えるようにするには、インターフェイスの名前を指定して {{ic|netctl-auto@.service}} のインスタンスを[[有効化]]してください。例: {{ic|netctl-auto@wlan0.service}}。 |
||
: 記事に合わせて言い回しを変えても構いません。 |
: 記事に合わせて言い回しを変えても構いません。 |
||
| − | : [[systemd#ユニットを使う]] の記事セクションへのリンクを |
+ | : [[systemd#ユニットを使う]] の記事セクションへのリンクを直接、または {{ic|<nowiki>[[start]]</nowiki>}} や {{ic|<nowiki>[[enable]]</nowiki>}}、 {{ic|<nowiki>[[stop]]</nowiki>}} のような専用の[https://wiki.archlinuxjp.org/index.php?title=特別:リンク元/Systemd&hidelinks=1&hidetrans=1 リダイレクト] を通して必ず貼ってください。 |
=== ノート・警告・ヒント === |
=== ノート・警告・ヒント === |
||
* [[テンプレート:Note|ノート]]は、当然のこととして期待するようなことが、ユーザー毎に異なる恐れがある記事中の箇所で情報を示すのに使います。これは、特に、使わなければ記事の本筋から少々外れてしまうと考えられるものに関する詳細な情報を示すのにも使います。もう1つの例として、パッケージ名の変更のような一時的なアナウンスを告知する必要がある場合が挙げられます。 |
* [[テンプレート:Note|ノート]]は、当然のこととして期待するようなことが、ユーザー毎に異なる恐れがある記事中の箇所で情報を示すのに使います。これは、特に、使わなければ記事の本筋から少々外れてしまうと考えられるものに関する詳細な情報を示すのにも使います。もう1つの例として、パッケージ名の変更のような一時的なアナウンスを告知する必要がある場合が挙げられます。 |
||
| − | : ノートは、重要であるけれど |
+ | : ノートは、重要であるけれど主題の領域に関してよく知らない場合に見落としやすい情報を目立たせるのに使うこともできます。 |
| − | * [[テンプレート:Warning|警告]]は、説明された手順によって元に戻すことがかなり難しくなったり、システムにダメージを与えてしまうような深刻な結果をもたらしてしまう可能性がある箇所で使用します。通常、警告は |
+ | * [[テンプレート:Warning|警告]]は、説明された手順によって元に戻すことがかなり難しくなったり、システムにダメージを与えてしまうような深刻な結果をもたらしてしまう可能性がある箇所で使用します。通常、警告は起こりうる最悪のケースが発生するような、またはそれを避けるような状態だけではなく、そのようなケースのシナリオの両方を示します。 |
| − | : 基本的には警告を多用しないでください: 警告を使用するべきかわからないときは |
+ | : 基本的には警告を多用しないでください: 警告を使用するべきかわからないときは多くの場合ノートを使ったほうがよいです。 |
| − | * [[テンプレート:Tip|ヒント]]は、役に立ち、誰かのメリットになるような方法や手順を示すときに使います。これは |
+ | * [[テンプレート:Tip|ヒント]]は、役に立ち、誰かのメリットになるような方法や手順を示すときに使います。これは扱っている操作を完了させるには必要がないため無視しても問題ありません。 |
| − | * 2つ以上のノート |
+ | * 2つ以上のノート、警告またはヒントを記事の同じ箇所に連続して表示する必要がある場合、1つのテンプレート中のリストにテキストをまとめてください。それらの内容に関連性が全くない限りはテンプレートを積み重ねないでください。例: |
:{{Tip| |
:{{Tip| |
||
:* ヒント例 #1. |
:* ヒント例 #1. |
||
| 222行目: | 222行目: | ||
=== シェル === |
=== シェル === |
||
| − | * 本当に必要でない限りは |
+ | * 本当に必要でない限りはユーザーのシェルとして特定のシェル (例: Bash) の使用を前提としないでください: 記事を書いたり編集する場合は可能な限りどのシェルでも実行できるようにしてください。 |
=== ハイパーテキスト === |
=== ハイパーテキスト === |
||
| − | * 書いた記事を、テキスト中に様々なキーワードを用いて |
+ | * 書いた記事を、テキスト中に様々なキーワードを用いて可能な限り多くの他の記事に内部リンクしてください。 |
* 新しい記事へのリンクは記事作成後にしてください。基本的に存在しない記事へのリンクは作成しないでください。 |
* 新しい記事へのリンクは記事作成後にしてください。基本的に存在しない記事へのリンクは作成しないでください。 |
||
| − | * [[Wikipedia:ja:システムコール|システムコール]]などの専門用語で |
+ | * [[Wikipedia:ja:システムコール|システムコール]]などの専門用語で ArchWiki の記事でカバーされていないものは、Wikipedia の関連するページにリンクしてください。 |
| − | * wiki の他の記事にリンクするときは |
+ | * wiki の他の記事にリンクするときは URL を使ってはいけません。内部リンクを利用するようにしてください: {{Ic|<nowiki>[[Wiki の記事]]</nowiki>}}。wiki エンジンが内部リンクを追跡できるようにすることでメンテナンスが楽になります。<br>内部リンクの使用法に関する詳細は[[ヘルプ:編集#リンク]]を見てください。 |
| − | ** 同じページのセクションにリンクするときは |
+ | ** 同じページのセクションにリンクするときはアンカー記号を隠さないでください (例: {{ic|<nowiki>[[#ドキュメントのセクションへのリンク|ドキュメントのセクションへのリンク]]</nowiki>}})。書式の再設定が不要になるのに加え、アンカーによってリンク先が完全な1つの記事ではなく記事のセクションへのものであることを明確に示せます。 |
* できる限り間接的なリンクはしないでください。例えば、"詳しくは[[systemd|ここ]]を見てください" ではなく "詳しくは [[systemd]] の記事を見てください" のように指示します。 |
* できる限り間接的なリンクはしないでください。例えば、"詳しくは[[systemd|ここ]]を見てください" ではなく "詳しくは [[systemd]] の記事を見てください" のように指示します。 |
||
| − | * 稀なケースを除いて |
+ | * 稀なケースを除いて記事を行き止まりページ (他のどの記事にもリンクしていない記事) や孤児ページ (他のどの記事からもリンクされていない記事) のままにしないでください。 |
| − | * 記事に具体的な処理を書いたり |
+ | * 記事に具体的な処理を書いたり特別なことを述べる前に、それらを詳細に扱った記事が既に存在していないか常に確認してください: 存在する場合は内容を重複させずにその記事にリンクしてください。 |
| − | * 記事の主題がアップストリームのドキュメントによく書かれ維持されている場合は |
+ | * 記事の主題がアップストリームのドキュメントによく書かれ維持されている場合はArch 特有の対応だけを記述し、一般的な情報については公式ドキュメントにリンクしてください。 |
* 編集中の記事と同じ言語でローカライズされたページヘのリンクには、[[特別:リンク元]]ページに表示されなくなってしまうので、wiki 間リンクを使わないでください。例えば、ハンガリー語の記事では {{ic|<nowiki>[[Main page (Magyar)]]</nowiki>}} を使うのが正しく、 {{ic|<nowiki>[[:hu:Main page]]</nowiki>}} を使うのは誤っています。<br> 分離された wiki が将来作られたときに、記事をその wiki に移動させやすくするため、代わりにこの種のリンクを他言語間に使うのは容認されています。<br> 最後に、この種のリンクと [[#言語間リンク]] との違いについて言及しますが、言語間リンクには最初にコロンが付きません。 |
* 編集中の記事と同じ言語でローカライズされたページヘのリンクには、[[特別:リンク元]]ページに表示されなくなってしまうので、wiki 間リンクを使わないでください。例えば、ハンガリー語の記事では {{ic|<nowiki>[[Main page (Magyar)]]</nowiki>}} を使うのが正しく、 {{ic|<nowiki>[[:hu:Main page]]</nowiki>}} を使うのは誤っています。<br> 分離された wiki が将来作られたときに、記事をその wiki に移動させやすくするため、代わりにこの種のリンクを他言語間に使うのは容認されています。<br> 最後に、この種のリンクと [[#言語間リンク]] との違いについて言及しますが、言語間リンクには最初にコロンが付きません。 |
||
=== コーディングスタイル === |
=== コーディングスタイル === |
||
| − | * コマンドやスクリプトを追加するときは |
+ | * コマンドやスクリプトを追加するときは記事全体を通して一貫したコーディングスタイルを用いてください。特に、他に関連のある記事がある場合はその記事にもこれが当てはまります。使用する言語の公式または最も一般的なコーディングスタイルのガイドラインが利用可能であれば、それを順守してください。 |
* 使用するプログラミング/スクリプト言語の非推奨な機能は使わないでください。例: シェルのコマンド置換には、バックティック/グレイヴ ({{ic|``}}) 構文は使わず、{{ic|$()}} 構文を使ってください。 |
* 使用するプログラミング/スクリプト言語の非推奨な機能は使わないでください。例: シェルのコマンド置換には、バックティック/グレイヴ ({{ic|``}}) 構文は使わず、{{ic|$()}} 構文を使ってください。 |
||
| 248行目: | 248行目: | ||
=== "Tips and tricks" セクション === |
=== "Tips and tricks" セクション === |
||
| − | * ''Tips and tricks'' セクションでは |
+ | * ''Tips and tricks'' セクションでは高度なヒントやソフトウェアの使用例を提供します。 |
* タイトルは ''Tips and tricks'' で統一してください。 |
* タイトルは ''Tips and tricks'' で統一してください。 |
||
* Tips and tricks の内容が多岐にわたる場合、サブセクションにしてまとめてください。 |
* Tips and tricks の内容が多岐にわたる場合、サブセクションにしてまとめてください。 |
||
| 254行目: | 254行目: | ||
=== "トラブルシューティング" セクション === |
=== "トラブルシューティング" セクション === |
||
| − | * ''トラブルシューティング''セクションは |
+ | * ''トラブルシューティング''セクションはソフトウェアやよくある問題の解決策に関する、頻繁に尋ねられる質問のために使います ([[#"既知の問題" セクション]] と比べてみてください)。 |
* タイトルは''トラブルシューティング'' (訳註: 英語版は ''Troubleshooting'') で統一してださい。(訳註: 英語版では) ''Trouble shooting''、''Trouble-shooting''、そして ''TroubleShooting'' は、よくあるスペルミスなので使わないでください。 |
* タイトルは''トラブルシューティング'' (訳註: 英語版は ''Troubleshooting'') で統一してださい。(訳註: 英語版では) ''Trouble shooting''、''Trouble-shooting''、そして ''TroubleShooting'' は、よくあるスペルミスなので使わないでください。 |
||
| − | * 既知のバクに対する一時的な応急処置を報告することもできますが、その場合、そのバグ報告へのリンクを提供することが強く望まれます。まだ報告されていない場合は |
+ | * 既知のバクに対する一時的な応急処置を報告することもできますが、その場合、そのバグ報告へのリンクを提供することが強く望まれます。まだ報告されていない場合は自分で報告してください。そうすることでそのバグが適切に修正される可能性が増します。<br> バグ報告をリンクすることは読者と編集者の双方にとって大きなメリットがあります: |
| − | ** 読者にとって、この Wiki が停止点ではなくなります: リンクしなければ頑張って検索しても見逃してしまったかもしれない |
+ | ** 読者にとって、この Wiki が停止点ではなくなります: リンクしなければ頑張って検索しても見逃してしまったかもしれないソースに近い情報を見つけられるようになります。 |
** Wiki の編集者にとって、報告されたバグが依然として問題になっているかどうかを確認する手間が省け、整理が楽になります: これは、読者が新しい情報を見つけ、wiki を編集しに戻って来るようになった場合、自律性の向上さえももたらすかもしれません。 |
** Wiki の編集者にとって、報告されたバグが依然として問題になっているかどうかを確認する手間が省け、整理が楽になります: これは、読者が新しい情報を見つけ、wiki を編集しに戻って来るようになった場合、自律性の向上さえももたらすかもしれません。 |
||
=== "既知の問題" セクション === |
=== "既知の問題" セクション === |
||
| − | * ''既知の問題'' セクションは |
+ | * ''既知の問題'' セクションは既知のバグやまだ解決策が存在しない利用上の問題のために使います ([[#"トラブルシューティング" セクション]] と比べてみてください)。 |
* タイトルは''既知の問題''で統一してください。 |
* タイトルは''既知の問題''で統一してください。 |
||
| − | * バグが既知の問題として報告されている場合、その報告へのリンクを提供することが強く望まれます; 報告されていない場合は |
+ | * バグが既知の問題として報告されている場合、その報告へのリンクを提供することが強く望まれます; 報告されていない場合は自分で報告してください。そうすることでバグが修正される可能性が増します。 |
=== "参照" セクション === |
=== "参照" セクション === |
||
| − | * ''参照''セクションでは |
+ | * ''参照''セクションでは追加情報の参考文献とソースのリストを提供します。 |
* リストのそれぞれの項目は {{Ic|*}} から始めてください。これを使うことで MediaWiki の箇条書きリストが生成されます。 |
* リストのそれぞれの項目は {{Ic|*}} から始めてください。これを使うことで MediaWiki の箇条書きリストが生成されます。 |
||
* タイトルは''参照''で統一してください。''外部リンク''や''さらなる資料''などのその他の類似したタイトルは使わないでください。 |
* タイトルは''参照''で統一してください。''外部リンク''や''さらなる資料''などのその他の類似したタイトルは使わないでください。 |
||
| 274行目: | 274行目: | ||
=== 適切ではない記述 === |
=== 適切ではない記述 === |
||
| − | * 記事に署名したり、記事の著者のクレジットを付けないでください: ArchWikiはこのコミュニティの成果物であり、それぞれの記事の編集履歴に貢献者のクレジットがしっかりと記されています。<br> ただし、記事を書くのに用いたソースを報告するのは、よいプラクティスといえます: このために''参照''セクションを使うことができます。 |
+ | * 記事に署名したり、記事の著者のクレジットを付けないでください: ArchWiki はこのコミュニティの成果物であり、それぞれの記事の編集履歴に貢献者のクレジットがしっかりと記されています。<br> ただし、記事を書くのに用いたソースを報告するのは、よいプラクティスといえます: このために''参照''セクションを使うことができます。 |
* 通常のユーザーのファイルアップロードは無効化されており、記事に既存の画像を含めるのは許可されていません: 代替手段として外部の画像やギャラリーへのリンクを貼ることができ、シンプルな図表が要る場合は [http://www.asciiflow.com/ Asciiflow] のような ASCII エディタを使うこともできます。論拠: |
* 通常のユーザーのファイルアップロードは無効化されており、記事に既存の画像を含めるのは許可されていません: 代替手段として外部の画像やギャラリーへのリンクを貼ることができ、シンプルな図表が要る場合は [http://www.asciiflow.com/ Asciiflow] のような ASCII エディタを使うこともできます。論拠: |
||
** メンテナンス: Arch はローリングリリースであり、画像を使うと記事の更新が非常に困難になると考えられます。 |
** メンテナンス: Arch はローリングリリースであり、画像を使うと記事の更新が非常に困難になると考えられます。 |
||
| 281行目: | 281行目: | ||
** アクセシビリティ: 私たちは、低速回線、テキスト専用ブラウザ、読み上げソフト、およびこれらに類似するものを用いるユーザーをサポートします。 |
** アクセシビリティ: 私たちは、低速回線、テキスト専用ブラウザ、読み上げソフト、およびこれらに類似するものを用いるユーザーをサポートします。 |
||
** 効率: 画像はサーバーの帯域と保存スペースを多く消費します。 |
** 効率: 画像はサーバーの帯域と保存スペースを多く消費します。 |
||
| − | ** シンプリシティ: テキストのみの記事のほうが |
+ | ** シンプリシティ: テキストのみの記事のほうがシンプルで整って見えます。 |
=== 言語使用域 === |
=== 言語使用域 === |
||
* 記事は、正式でプロらしい簡潔な文体で書いてください。編集確認と校正を行い、文法とスペルの間違いをなくすよう心がけてください。 |
* 記事は、正式でプロらしい簡潔な文体で書いてください。編集確認と校正を行い、文法とスペルの間違いをなくすよう心がけてください。 |
||
| − | * ''どうやって''だけではなく''なぜ''も説明するようにしてください。情報を説明するほうが |
+ | * ''どうやって''だけではなく''なぜ''も説明するようにしてください。情報を説明するほうが手順だけを示すより深く知識を伝えることができます。 |
* (訳註: 主に英語を使用する場合は、) 短縮形を使わないでください: "don't"、"isn't"、"you've" などは "do not"、"is not"、"you have" にしてください。 |
* (訳註: 主に英語を使用する場合は、) 短縮形を使わないでください: "don't"、"isn't"、"you've" などは "do not"、"is not"、"you have" にしてください。 |
||
* 単語の不必要な[[Wikipedia:Shortening (grammar)|短縮]]はしないでください。例: "repo"、"distro"、"config" ではなく "repository"、"distribution"、"configuration" を使います。<br> 同様に、''まれな''コマンドラインオプションには、1文字形式のオプションではなく長い形式のものを使ってください。 |
* 単語の不必要な[[Wikipedia:Shortening (grammar)|短縮]]はしないでください。例: "repo"、"distro"、"config" ではなく "repository"、"distribution"、"configuration" を使います。<br> 同様に、''まれな''コマンドラインオプションには、1文字形式のオプションではなく長い形式のものを使ってください。 |
||
| 292行目: | 292行目: | ||
* "現在"や"執筆時点で"、"すぐに"のような言葉で、限定されない時間の言及はしないでください。"2015年5月時点で"のような明確な表現で置き換えてください。 |
* "現在"や"執筆時点で"、"すぐに"のような言葉で、限定されない時間の言及はしないでください。"2015年5月時点で"のような明確な表現で置き換えてください。 |
||
* 客観的に書いてください: 記事に個人的なコメントを含めないでください。それには議論ページを使います。通常は1人称視点で書いてはいけません。 |
* 客観的に書いてください: 記事に個人的なコメントを含めないでください。それには議論ページを使います。通常は1人称視点で書いてはいけません。 |
||
| − | * 内容を編集する場合、文体はその記事の残りの部分で使われているものに合わせてください。例えば、2人称を使って読者に言葉をかけている場合、追加する内容にもこのスタイルを採用してください。3人称または受動態が記事全体を通して使われている場合も |
+ | * 内容を編集する場合、文体はその記事の残りの部分で使いたいときはわれているものに合わせてください。例えば、2人称を使って読者に言葉をかけている場合、追加する内容にもこのスタイルを採用してください。3人称または受動態が記事全体を通して使われている場合も同じようにしてください。 |
* さまざまな選択肢 (複数あるソフトウェアや方法など) の中から1つを提案する場合、他の選択肢よりもはっきりと推奨することはしないでください。しかし、それぞれの長所短所を客観的に記述することで、読者が自分に合った最善の判断をする手助けになります。 |
* さまざまな選択肢 (複数あるソフトウェアや方法など) の中から1つを提案する場合、他の選択肢よりもはっきりと推奨することはしないでください。しかし、それぞれの長所短所を客観的に記述することで、読者が自分に合った最善の判断をする手助けになります。 |
||
2016年10月19日 (水) 02:13時点における版
以下のスタイルの取り決めは記事を引き締めて、まとめて、見た目を統一することが狙いです。ArchWiki を編集するときはできるかぎり守るようにしてください。
目次
- 1 記事のページ
- 1.1 タイトル
- 1.2 レイアウト
- 1.3 マジックワード
- 1.4 カテゴリ
- 1.5 言語間リンク
- 1.6 記事の状態テンプレート
- 1.7 関連記事ボックス
- 1.8 前書きや導入
- 1.9 セクションの見出し
- 1.10 コードのフォーマット
- 1.11 コマンドラインのテキスト
- 1.12 ファイル編集の記述
- 1.13 キーボードキー
- 1.14 パッケージ管理の記述
- 1.15 systemd ユニットの操作
- 1.16 ノート・警告・ヒント
- 1.17 シェル
- 1.18 ハイパーテキスト
- 1.19 コーディングスタイル
- 1.20 サポートするカーネルのバージョン
- 1.21 "Tips and tricks" セクション
- 1.22 "トラブルシューティング" セクション
- 1.23 "既知の問題" セクション
- 1.24 "参照" セクション
- 1.25 適切ではない記述
- 1.26 言語使用域
- 2 カテゴリのページ
- 3 リダイレクトのページ
- 4 ユーザーのページ
- 5 共通ルール
記事のページ
タイトル
- タイトルは先頭だけを大文字にしてください。例: "Title for new page" は正しいですが、"Title for New Page" は誤っています。正式名称や大文字の頭字語に含まれている常用語は大文字にしてください。例えば "Advanced Linux Sound Architecture" が正しく、"Advanced Linux sound architecture" は誤っています。
名前空間はタイトルの一部として考えません。したがって "ArchWiki:Example article" が正しく、"ArchWiki:example article" は誤っています。サブページの名前の先頭は大文字にします。したがって "My page/My subpage" が正しく、"My page/my subpage" は誤っています。 - 通常は、タイトルのトピックは単数形にしますが、何かのグループやクラスなどを表していて可算名詞の場合は複数形にします。
- 記事の主題がフルネームでも、省略形でもどちらの名前でも知られている場合、記事のタイトルにはフルネームの方を使うほうが適しています。フルネームと省略形の両方を (括弧を使って) タイトルに入れるのは止めてください。代わりに省略形のページからフルネームのページに転送するようにします。
- 翻訳されたページのタイトルは必ずヘルプ:i18n#記事のタイトルに従ってください。
- 詳しくはヘルプ:記事命名ガイドラインを見てください。
レイアウト
- 記事の構成は以下の順番とします:
マジックワード
- 挙動スイッチ — そして一般に、記事に内容を追加するためには使用せず、その表示のされ方や挙動を変えるために使用するすべてのマジックワード — はすべて記事の最上部に配置してください。
このルールは特に{{DISPLAYTITLE:title}}と テンプレート:Lowercase title に適用され、これらは前者を使用します。
カテゴリ
- どの記事も必ず最低1つ以上の現存しているカテゴリに分類してください。
- 1つの記事は複数のカテゴリに分類することができます。ただし、そのカテゴリ同士が親子関係であってはいけません。
- カテゴリは必ず記事の最上部 (何らかのマジックワードがあればそのすぐ下) に配置してください。
- カテゴリと本文の最初の行 (もしくは言語間リンクがある場合はそれ) の間に空行を含めないでください。記事の上部に余分な空白が挿入されてしまいます。
- 詳しくはヘルプ:カテゴリを見てください。
言語間リンク
- 記事が内部または外部の Arch Linux wiki で翻訳されていたら、必ず言語間リンクをカテゴリのすぐ下、本文の最初の行のすぐ上に配置してください。
なお、言語間リンクは、実際にはページ左側の適切なカラムに表示されます。 - 言語間リンクと本文の最初の行の間に空行を含めないでください。記事の上部に余分な空白が挿入されてしまいます。
- 言語間リンクの追加、編集は、既に存在しているすべての翻訳記事に対して行ってください。
- 1つの言語に対して2つ以上の言語間リンクを記事に追加しないでください。
- 記事には、その記事の言語と同じ言語間リンクを追加しないでください。
- 言語間リンクは、言語の現地名ではなく、必ず言語タグ名に基づいてアルファベット順に並べてください。例えば、現地名では "Suomi" (フィンランド語) は "Français" (フランス語) の後に来ますが、言語タグ名では
[[fi:Title]](フィンランド語) は[[fr:Title]](フランス語) の先に来ます。 - 詳しくは ヘルプ:i18n や Wikipedia:Help:言語間リンク の記事を見てください。
記事の状態テンプレート
- 記事の状態テンプレートはカテゴリ (もしくは言語間リンクがある場合はそれ) のすぐ下、イントロダクション (もしくは関連記事ボックスがある場合はそれ) のすぐ上に配置します。
- 記事の状態テンプレートは、その使用法が適切であれば、記事のセクションの中でも使用することができます。
- 記事の状態テンプレートを使用する際は必ず専用の欄に短い説明を加えてください (例はそれぞれのテンプレートページにあります)。必要であればトークページで議論を始めます。
関連記事ボックス
- ArchWiki 内部にある関連記事のシンプルなリストを提供します。
- 使用する場合は、カテゴリ (もしくは言語間リンクや記事の状態テンプレートがあればそれ) のすぐ下に配置してください。
- 関連記事ボックスは テンプレート:Related articles start と テンプレート:Related と テンプレート:Related articles end のみで構成されています。各ページのガイドラインを参照してください。
- 英語以外の言語で書かれた記事は、そのリンクの文字列を翻訳するために テンプレート:Related2 を使うことができます。
- もっと完全で詳しいリストがほしいときは "参照" セクション を使ってください。リンクの説明と wiki 間または外部サイトへリンクを含めることができます。
前書きや導入
- 記事の主題を記述します。
ソフトウェアの説明は、(偏った見方になる可能性があるので) 自分の言葉で言い換えたり書いたりするより、アップストリームの著者が書いたものを使うとよいでしょう。これは (もし存在すれば) 大抵プロジェクトのホームページや about ページにあります。例として MediaTomb が挙げられます。 - 記事の最初のセクションのすぐ上に配置してください。
- 明示的に
==Introduction==や==Preface==セクションを作らずに、最初のセクションの見出しの上に配置してください。目次は、十分な数のセクションが記事にあれば、自動的に前書きと最初のセクションの間に表示されます。 - 詳しくはヘルプ:記事の書き方を見てください。
セクションの見出し
- 見出しは2段階目から使ってください (
==)。1段目は記事のタイトルに予約されています。 - サブセクションを作成するときは段階を飛ばさないでください。2段目のサブセクションは3段と続いていきます。
- 見出しは先頭だけ大文字にしてください。例: "My new heading" は正しいですが、"My New Heading" は誤っています。
- 見出しにリンクは使わないでください。スタイルが崩れます。普通は見出しではなくセクションの中身にアンカーテキストを記述します。以下のような文章を使って下さい:
- 詳しくは関連記事を参照してください。
- 同じく、HTML や wiki のマークアップコード、あるいはコードをフォーマットするテンプレートを見出しに使わないで下さい。ヘルプ:スタイル/書式と句読点も参照。
- 詳しくはヘルプ:効果的な見出しを見てください。
コードのフォーマット
- 短いコードやファイル名、コマンド名、変数などのインラインで表示したいものは
{{ic|code}}を使います。例:
コンソールでsh ./hello_world.shを実行してください。
- (コマンドラインの入出力するコードやファイルの中身など) コードが一行で適切なフレームを付ける場合、半角スペースを前に付けます。ヘルプ:編集#コードを見てください。例:
$ sh ./hello_world.sh
Hello World
- 複数行のコード (コマンドラインの入出力やファイルの中身) に適切なフレームを付ける場合、
{{bc|code}}を使います。例:
#!/bin/sh # Demo echo "Hello World"
- コマンドラインの入力と出力を両方表示する必要がある場合は
{{hc|input|output}}を使います。例:
$ sh ./hello_world.sh
Hello World
- ファイルの中身を表示する必要があり、そのコードがどのファイルを指しているか読者に伝わらないかもしれないときは
{{hc|filename|content}}を使うことで見出しにファイル名を表示することもできます。例:
~/hello_world.sh
#!/bin/sh # Demo echo "Hello World"
- 設定ファイルのようなコードブロックについては、読者を関連のある行に集中させ、それ以外の周囲の無関連な内容を省略する (
...) ことを考えてください。
- 詳しくはヘルプ:テンプレートを見てください。
=や|などテンプレートを破壊する文字の対処法についても載っています。
コマンドラインのテキスト
- インラインコード (テンプレート:ic) 使う場合、プロンプト記号を表示する必要はありませんが、テキストの周囲に必ずパーミッションの注意書きをはっきりとわかるように追加してください。
- ブロックコード (テンプレート:bc や空白文字で始まる行) を使う場合、一般ユーザのコマンドのプロンプトとして
$を、root のコマンドのプロンプトとして#を使います。- コマンドブロックの前置きとなる文の最後は通常
:にしたほうがよいです。 - 特別な事情がない限り次を使います:
# command
次は使いません:$ sudo command
- root プロンプトと sudo コマンドを次のように一緒に使わないでください:
# sudo command
唯一の例外は、sudo が-uフラグと一緒に使われる場合です: この場合、プロンプトを同じコードブロックの他のプロンプトに合わせることができます。それ以外ではデフォルトの$を使ってください。 - コマンドを含む同じ囲みにコメントを付け足さないでください。例:
# pacman -S foo #パッケージ foo をインストール
- 極端に長いコードを書くのは避けてください。可能であれば改行をうまく使ってください。
- コマンドブロックの前置きとなる文の最後は通常
- ユーザーの sudo や他の権限昇格ユーティリティ (例: gksu, kdesu) の使用を前提としないでください。
ファイル編集の記述
- テキストファイルの編集する必要がある場合、原則として特定のテキストエディタ (nano, vim, emacs など) の使用を前提としないでください。
- テキストファイルを編集する必要がある場合、厳密な理由がない限り間接的なコマンドを使わないでください。例えば
$ echo -e "clear\nreset" >> ~/.bash_logoutは次のようにします:
~/.bash_logoutに以下の行を付け加えます:clear
reset
- 適切な場所に ヘルプ:読み方#追加, 作成, 編集 そして source へのリンクを追加するのも良いでしょう。
キーボードキー
- 記事内でのキーボードキーの表示は通常 テンプレート:ic のインスタンスを使います。
- 文字キーは小文字で表示します:
a。大文字を表示するにはShift+aを使います。Shift+AやAは使いません。 - キーの 組み合わせ は
+記号を用い、その両端に空白文字を付けずにそれぞれのキーを結合するのが正しい表示の仕方です:Ctrl+c。
Ctrl + c,Ctrl+c,Ctrl-cは準拠していない書式なので使用は避けてください。 - キー入力の 流れ は冗長に説明 (例:
Shift+tに続けてgを押します) するか、それぞれのキーにテンプレートの別々のインスタンスを用い、それらを1個の半角スペースで区切って簡潔に説明するのが正しい表示の仕方です:gShift+t。 - 特別なキーの組み合わせの標準的な表示方法を以下にいくつか示します:
Shift(SHIFTではありません)Ctrl(CTRLやControlではありません)Alt(ALTでありません)Super(WindowsやModではありません)Enter(ENTERやReturnではありません)Esc(ESCやEscapeではありません)Space(SPACEではありません)BackspaceTabIns(INSやInsertではありません)Del(DELやDeleteではありません)PrintScreenPageUpPageDown
パッケージ管理の記述
公式パッケージ
- 公式パッケージのインストールの説明に pacman のコマンド例を挙げないでください: この規則は、シンプルであるために (すべての Arch ユーザは、pacman の記事内容を知っておくべきです)、そして
pacman -Sy packageのようなコマンドで起こりうるエラーや、pacman -S packageかpacman -Syu packageのどちらを選ぶかのような、起こるかもしれない終わりのない議論を避けるために作られました。そのため、pacman のフロントエンドやラッパーの使用を提案してはいけません。
- 代わりに、以下のような記述を使ってください:
- もしくは、アプリケーションの名前がパッケージの名前と異なっている場合:
- MyApplication は my-app-pkg パッケージでインストールできます。
- 複数のパッケージをインストールするように書きたいときは以下のようになります:
- パッケージグループを参照するときは以下を使用:
- 記事に合わせて言い回しを変えても構いません。
- 言及したパッケージのリンクは必ず貼り、テンプレート:Pkg を使ってください。例:
{{Pkg|foobar}}。 - パッケージグループの参照する場合は、代わりに テンプレート:Grp を使ってください。例:
{{Grp|foobar}}。 - 上記の例ではインストールのリンクを利用しています (例:
[[install]]): インストールの指示が初めて出てくるところでは必ずリンクを使うことを推奨します。特に Arch 初心者がアクセスするようなページのときはリンクを絶対に付けてください。 - メンテナンスを容易にするために、パッケージが core、extra、または community リポジトリでホストされている場合はそのリポジトリを参照しないでください。パッケージが別のリポジトリに移されるのはよくあることです。ただし、そのパッケージがデフォルトでは有効化されていない公式リポジトリ (multilib、testing など) でホストされている場合は、以下のようにして言及する必要があります:
AUR パッケージ
- AUR パッケージのインストール手順の例は挙げないでください。公式の手順を説明したり、AUR ヘルパーについて述べたりしないでください。非公式パッケージをインストールしようとする全てのユーザーは事前に Arch User Repository に目を通しておき、システムで起こりうるあらゆる結果を把握しておいてください。
- 言及したパッケージのリンクは必ず貼り、テンプレート:AUR を使ってください。例:
{{AUR|foobar}}。
非公式リポジトリ
- ビルド済みのパッケージをインストールするために非公式リポジトリの使用を提案するときは、リポジトリを有効化する方法を書かないでください。そのリポジトリが非公式ユーザーリポジトリにかかれていることを確認してページヘのリンクを張ってください。また、公式パッケージと同様に、pacman コマンドの例は不要です。例:
- example リポジトリから foobar パッケージをインストールしてください。
- パッケージが AUR からもインストールできる場合:
- パッケージが AUR とは違う名前で存在している場合:
- 記事に合わせて言い回しを変えても構いません。
- 非公式ユーザーリポジトリへのリンクは絶対で、適切なリポジトリセクションにリンクしてください。例:
[[Unofficial user repositories#example|example]]。
systemd ユニットの操作
- systemctl を用いた systemd ユニットの有効化、起動、またはその他の基本的操作の例は挙げないでください。代わりに関連するユニットを挙げて簡潔に説明してください。他のユニットとの依存関係または競合、そして行うべき操作についての説明が必要な場合は述べてください。
- ブート時に GDM を起動させるには、
gdm.serviceを有効化してください。例:
- ブート時に GDM を起動させるには、
- または、ユニットがインスタンス化する必要があるテンプレートである場合:
- 無線インターフェイスの netctl プロファイルを自動的に切り替えるようにするには、インターフェイスの名前を指定して
netctl-auto@.serviceのインスタンスを有効化してください。例:netctl-auto@wlan0.service。
- 無線インターフェイスの netctl プロファイルを自動的に切り替えるようにするには、インターフェイスの名前を指定して
- 記事に合わせて言い回しを変えても構いません。
- systemd#ユニットを使う の記事セクションへのリンクを直接、または
[[start]]や[[enable]]、[[stop]]のような専用のリダイレクト を通して必ず貼ってください。
ノート・警告・ヒント
- ノートは、当然のこととして期待するようなことが、ユーザー毎に異なる恐れがある記事中の箇所で情報を示すのに使います。これは、特に、使わなければ記事の本筋から少々外れてしまうと考えられるものに関する詳細な情報を示すのにも使います。もう1つの例として、パッケージ名の変更のような一時的なアナウンスを告知する必要がある場合が挙げられます。
- ノートは、重要であるけれど主題の領域に関してよく知らない場合に見落としやすい情報を目立たせるのに使うこともできます。
- 警告は、説明された手順によって元に戻すことがかなり難しくなったり、システムにダメージを与えてしまうような深刻な結果をもたらしてしまう可能性がある箇所で使用します。通常、警告は起こりうる最悪のケースが発生するような、またはそれを避けるような状態だけではなく、そのようなケースのシナリオの両方を示します。
- 基本的には警告を多用しないでください: 警告を使用するべきかわからないときは多くの場合ノートを使ったほうがよいです。
- ヒントは、役に立ち、誰かのメリットになるような方法や手順を示すときに使います。これは扱っている操作を完了させるには必要がないため無視しても問題ありません。
- 2つ以上のノート、警告またはヒントを記事の同じ箇所に連続して表示する必要がある場合、1つのテンプレート中のリストにテキストをまとめてください。それらの内容に関連性が全くない限りはテンプレートを積み重ねないでください。例:
シェル
- 本当に必要でない限りはユーザーのシェルとして特定のシェル (例: Bash) の使用を前提としないでください: 記事を書いたり編集する場合は可能な限りどのシェルでも実行できるようにしてください。
ハイパーテキスト
- 書いた記事を、テキスト中に様々なキーワードを用いて可能な限り多くの他の記事に内部リンクしてください。
- 新しい記事へのリンクは記事作成後にしてください。基本的に存在しない記事へのリンクは作成しないでください。
- システムコールなどの専門用語で ArchWiki の記事でカバーされていないものは、Wikipedia の関連するページにリンクしてください。
- wiki の他の記事にリンクするときは URL を使ってはいけません。内部リンクを利用するようにしてください:
[[Wiki の記事]]。wiki エンジンが内部リンクを追跡できるようにすることでメンテナンスが楽になります。
内部リンクの使用法に関する詳細はヘルプ:編集#リンクを見てください。- 同じページのセクションにリンクするときはアンカー記号を隠さないでください (例:
[[#ドキュメントのセクションへのリンク|ドキュメントのセクションへのリンク]])。書式の再設定が不要になるのに加え、アンカーによってリンク先が完全な1つの記事ではなく記事のセクションへのものであることを明確に示せます。
- 同じページのセクションにリンクするときはアンカー記号を隠さないでください (例:
- できる限り間接的なリンクはしないでください。例えば、"詳しくはここを見てください" ではなく "詳しくは systemd の記事を見てください" のように指示します。
- 稀なケースを除いて記事を行き止まりページ (他のどの記事にもリンクしていない記事) や孤児ページ (他のどの記事からもリンクされていない記事) のままにしないでください。
- 記事に具体的な処理を書いたり特別なことを述べる前に、それらを詳細に扱った記事が既に存在していないか常に確認してください: 存在する場合は内容を重複させずにその記事にリンクしてください。
- 記事の主題がアップストリームのドキュメントによく書かれ維持されている場合はArch 特有の対応だけを記述し、一般的な情報については公式ドキュメントにリンクしてください。
- 編集中の記事と同じ言語でローカライズされたページヘのリンクには、特別:リンク元ページに表示されなくなってしまうので、wiki 間リンクを使わないでください。例えば、ハンガリー語の記事では
[[Main page (Magyar)]]を使うのが正しく、[[:hu:Main page]]を使うのは誤っています。
分離された wiki が将来作られたときに、記事をその wiki に移動させやすくするため、代わりにこの種のリンクを他言語間に使うのは容認されています。
最後に、この種のリンクと #言語間リンク との違いについて言及しますが、言語間リンクには最初にコロンが付きません。
コーディングスタイル
- コマンドやスクリプトを追加するときは記事全体を通して一貫したコーディングスタイルを用いてください。特に、他に関連のある記事がある場合はその記事にもこれが当てはまります。使用する言語の公式または最も一般的なコーディングスタイルのガイドラインが利用可能であれば、それを順守してください。
- 使用するプログラミング/スクリプト言語の非推奨な機能は使わないでください。例: シェルのコマンド置換には、バックティック/グレイヴ (
``) 構文は使わず、$()構文を使ってください。
サポートするカーネルのバージョン
- core リポジトリにある最新の linux-lts パッケージと最新のインストールメディアのうち、低いほうのバージョン以上のカーネルバージョンに関わるあらゆるノートや対応は削除してはいけません。
"Tips and tricks" セクション
- Tips and tricks セクションでは高度なヒントやソフトウェアの使用例を提供します。
- タイトルは Tips and tricks で統一してください。
- Tips and tricks の内容が多岐にわたる場合、サブセクションにしてまとめてください。
"トラブルシューティング" セクション
- トラブルシューティングセクションはソフトウェアやよくある問題の解決策に関する、頻繁に尋ねられる質問のために使います (#"既知の問題" セクション と比べてみてください)。
- タイトルはトラブルシューティング (訳註: 英語版は Troubleshooting) で統一してださい。(訳註: 英語版では) Trouble shooting、Trouble-shooting、そして TroubleShooting は、よくあるスペルミスなので使わないでください。
- 既知のバクに対する一時的な応急処置を報告することもできますが、その場合、そのバグ報告へのリンクを提供することが強く望まれます。まだ報告されていない場合は自分で報告してください。そうすることでそのバグが適切に修正される可能性が増します。
バグ報告をリンクすることは読者と編集者の双方にとって大きなメリットがあります:- 読者にとって、この Wiki が停止点ではなくなります: リンクしなければ頑張って検索しても見逃してしまったかもしれないソースに近い情報を見つけられるようになります。
- Wiki の編集者にとって、報告されたバグが依然として問題になっているかどうかを確認する手間が省け、整理が楽になります: これは、読者が新しい情報を見つけ、wiki を編集しに戻って来るようになった場合、自律性の向上さえももたらすかもしれません。
"既知の問題" セクション
- 既知の問題 セクションは既知のバグやまだ解決策が存在しない利用上の問題のために使います (#"トラブルシューティング" セクション と比べてみてください)。
- タイトルは既知の問題で統一してください。
- バグが既知の問題として報告されている場合、その報告へのリンクを提供することが強く望まれます; 報告されていない場合は自分で報告してください。そうすることでバグが修正される可能性が増します。
"参照" セクション
- 参照セクションでは追加情報の参考文献とソースのリストを提供します。
- リストのそれぞれの項目は
*から始めてください。これを使うことで MediaWiki の箇条書きリストが生成されます。 - タイトルは参照で統一してください。外部リンクやさらなる資料などのその他の類似したタイトルは使わないでください。
適切ではない記述
- 記事に署名したり、記事の著者のクレジットを付けないでください: ArchWiki はこのコミュニティの成果物であり、それぞれの記事の編集履歴に貢献者のクレジットがしっかりと記されています。
ただし、記事を書くのに用いたソースを報告するのは、よいプラクティスといえます: このために参照セクションを使うことができます。 - 通常のユーザーのファイルアップロードは無効化されており、記事に既存の画像を含めるのは許可されていません: 代替手段として外部の画像やギャラリーへのリンクを貼ることができ、シンプルな図表が要る場合は Asciiflow のような ASCII エディタを使うこともできます。論拠:
- メンテナンス: Arch はローリングリリースであり、画像を使うと記事の更新が非常に困難になると考えられます。
- 必要性: Arch は GUI アプリケーションの開発と保守は一切していません。したがって、スクリーンショットを表示する必要性は全くありません。
- 管理: 自由形式の画像アップロードは、大きすぎたり不適切な画像の削除に時間がとられてしまうと考えられます。
- アクセシビリティ: 私たちは、低速回線、テキスト専用ブラウザ、読み上げソフト、およびこれらに類似するものを用いるユーザーをサポートします。
- 効率: 画像はサーバーの帯域と保存スペースを多く消費します。
- シンプリシティ: テキストのみの記事のほうがシンプルで整って見えます。
言語使用域
- 記事は、正式でプロらしい簡潔な文体で書いてください。編集確認と校正を行い、文法とスペルの間違いをなくすよう心がけてください。
- どうやってだけではなくなぜも説明するようにしてください。情報を説明するほうが手順だけを示すより深く知識を伝えることができます。
- (訳註: 主に英語を使用する場合は、) 短縮形を使わないでください: "don't"、"isn't"、"you've" などは "do not"、"is not"、"you have" にしてください。
- 単語の不必要な短縮はしないでください。例: "repo"、"distro"、"config" ではなく "repository"、"distribution"、"configuration" を使います。
同様に、まれなコマンドラインオプションには、1文字形式のオプションではなく長い形式のものを使ってください。 - 正確ではっきりした意味をもつ文にするために必要な言葉を省かないでください。例えば、リポジトリ名について言及する場合は、必ずそれにリポジトリを付け加えます。
- "現在"や"執筆時点で"、"すぐに"のような言葉で、限定されない時間の言及はしないでください。"2015年5月時点で"のような明確な表現で置き換えてください。
- 客観的に書いてください: 記事に個人的なコメントを含めないでください。それには議論ページを使います。通常は1人称視点で書いてはいけません。
- 内容を編集する場合、文体はその記事の残りの部分で使いたいときはわれているものに合わせてください。例えば、2人称を使って読者に言葉をかけている場合、追加する内容にもこのスタイルを採用してください。3人称または受動態が記事全体を通して使われている場合も同じようにしてください。
- さまざまな選択肢 (複数あるソフトウェアや方法など) の中から1つを提案する場合、他の選択肢よりもはっきりと推奨することはしないでください。しかし、それぞれの長所短所を客観的に記述することで、読者が自分に合った最善の判断をする手助けになります。
カテゴリのページ
- 全てのカテゴリは最低でも一つの親カテゴリの下にカテゴライズされなければなりません。ただし、ルートカテゴリ (カテゴリ:アーカイブ, カテゴリ:目次, カテゴリ:メンテナンス) は例外です。
- カテゴリは複数のカテゴリにカテゴライズすることができます。ただし、そのカテゴリ同士が親子関係であってはなりません。
- 循環参照はしないでください: 2つのカテゴリを相互に親カテゴリにすることはできません。
- カテゴリをそのカテゴリ自身でカテゴライズしないでください (自身にカテゴライズされたカテゴリ)。
- カテゴリは必ずカテゴリページの一番上に配置してください。
- カテゴリは、リネームされたときの一時的な場合を除き、リダイレクトしてはいけません。
- 通常、カテゴリ名は単数形にしてください ("主題"カテゴリ)。複数形は、単数形がその中の1つであるとして使える場合に使ってください ("集合"カテゴリ)。
リダイレクトのページ
- 転送ページにはリダイレクトのコード以外は含めてはいけません。唯一の例外:
- アーカイブページはリダイレクトですが、カテゴリ:アーカイブにカテゴライズされます。
- リダイレクトは内部の記事に限ります。wiki 間のリダイレクトは作成してはいけません。
- 言語間リンクを使用するリダイレクトはヘルプ:i18n の決まりにしたがってArchWiki:管理者からの許可が得られた場合にのみ例外的に可能となります。
ユーザーのページ
共通ルール
編集内容の要約
ヘルプ:編集を見てください。
HTML タグ
- HTML タグの利用は基本的に推奨されません。できるかぎり wiki のマークアップとテンプレートを使うようにしてください。ヘルプ:編集を参照。
<pre>code</pre>を使いたいときは常に{{bc|code}}を使ってください。<tt>text</tt>や<code>text</code>を使いたいときは常に{{ic|text}}を使ってください。- 特に HTML コメントは使わないようにしてください (
<!-- comment -->): HTML コメントで追加するようなノートは記事の議論ページに投稿してください。
コメントを書くところには適当な記事の状態テンプレートを追加してください。 <br>は必要なときにだけ使ってください: 新しい段落を始めたり改行するには、すぐ下に空行を挿入してください。
この規則によくある例外として、リストの項目内で改行する必要があるけれどサブ項目が使えない場合や、テンプレート内でリストを使うことができない場合などがあります。