ヘルプ:記事の書き方

提供: ArchWiki
移動先: 案内検索

この記事は wiki の作者や編集者を対象にかかれており、実用的な記事を作成して ArchWiki の読者に見聞を広めるのを補助します。

この記事を読むのに wiki ページを編集する方法を知る必要はありません。技術的な編集ハウツーよりも、もっと全般的なスタイルガイドです。

記事のイントロダクション

記事のイントロダクションは (大抵は) 読者が始めに出くわすものであり、これには記事の主題を彼らに紹介する目的があります。

それぞれの記事は一連の仮定から始まっています。これらの仮定が大抵の読者に当てはまることはほとんどなく、記事のイントロダクションは著者の仮定を満たす読者をフィルタリングする目的をもっています。読者に記事の残り部分の紹介をする必要は特にありませんが、記事全体を何度読んでもはっきりしないままになるような部分を整理するのに役立つことがあります。

たとえば、ある特定のやり方によるシステムの設定についての記事を書いたとします。しかし、それは読者がクリーンで最新の Arch Linux をプライマリハードドライブにインストールしたことを想定していました。たとえば、もしカーネルがカスタマイズされていたら、その方法はどのような影響を受けるでしょうか。または、もし パッケージ X が存在していなかったら、手順3はどのように動作するでしょうか。

記事を書き始める前にその方法に必要な条件を考え、示す必要があります。これには2つの重要なメリットがあります:

  1. 読者がその記事を読みたいかを、先に行き過ぎてしまう前に、判断できるようになります。
  2. 主題からずれたことを多く入れすぎずに記事が書けるようになります。

2番目は読者のパフォーマンスに対して大きな影響を与え、現に記事がスリム化されます。

記事のイントロダクションに含めるべき内容はたくさんあると思われるかもしれませんが、ここではより重要なものをいくつか順不同で示します:

  • 要求される前歴と知識
  • システムの状態と設定
  • ハードウェアコンポーネントの所有権
  • 読者がその記事に期待できないこと

テキスト

既に記事のイントロダクションで述べるかもしれないことをいくつか挙げました。以下では、効果的で役に立つ記事のイントロダクションの作成に関わる問題を見ていきます。

前歴と知識

前歴について述べる場合、この単語に2つの意味があることを頭に入れておく必要があります。1つ目の意味は、より一般的です。ある人のことをその人の知識・経験・評判から総合的に判断し、初心者グルと呼ぶことがあります。もう1つの意味は、イベントや活動への参加 (そして、これらを通して得た知識) という具体的な経験を指します。実際的な理由から、後者の意味での前歴を要求するほうが望ましいです。ArchWiki のほとんどの記事には特定の主題について述べる文脈が存在します。ある文脈で、初心者が自分の熟練度を誇示したり、一方でグルが関心がないことをあらわにするかもしれません。明確な前歴を要求すれば、読者が記事の続きについて行けるかどうかを判断できる可能性が高まります。

読者が記事を理解するために要求される知識を得る手助けになるような資料へのリンクを提供することもできます。

システムの状態と設定

パッケージ不足や設定が異なったシステム構成により、そのシステムで時々記事が全く役に立たなくなることがあります。したがって、可能ならばいつでも関連する (rc.config パラメータ、必要なパッケージなどのような) すべてのシステム設定を調べて定義しなければなりません。

ハードウェアの要件

ハードウェアの要件は大抵単純明快です。ダイアルアップモデム XYZ のドライバインストールについて述べていたら、モデム ZYX について話していると考える人は誰もいないでしょう。しかし、場合によっては明確なハードウェアの要件を挙げておくほうがよいことがあります。たとえば、XYZ-123 のドライバをインストールする記事を書いている場合、同じことが XYZ-456 には適用されない場合があることをユーザーに注意することができます。

記事で述べようとしているハードウェアの写真を追加するのもよい計らいといえます。

読者が記事に期待できないこと

時々、記事のタイトルは誤解を招くことがあります。そのため、読者に記事の実際の主題を知らせ、可能であれば読者が探していた他記事へのリンクを提供する必要があります。

たとえば、この記事が wiki テキストを用いたページの整形の仕方に関するものだと思った読者がいるかもしれません。したがって、そのような読者にはこれが探しているページではないことを知らせ、適切なページヘのリンクを提供しました。

フォーマット

記事のイントロダクションのフォーマットは、通常の ArchWiki の慣習に従ってください。しかし、より注意を払う必要がある細かい点がまだあります。

必要な条件を列挙する方法は2つあります。1つ目の方法では、条件とその他の導入メモを簡潔な (記事で使用する言語がここに入ります) で冗長に説明します。もう1つの方法は、よくまとまった条件のリストを提供します。