ヘルプ:記事の書き方

関連記事

• ArchWiki:About
• ヘルプ:スタイル
• ヘルプ:編集
• ヘルプ:記事命名ガイドライン
• ヘルプ:効果的な見出し

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

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

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

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

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

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

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

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

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

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

• 要求されるこれまでの経験と知識
• システムの状態と設定
• ハードウェアコンポーネントの所有権
• 読者がその記事で見つけられないこと

テキスト

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

前歴と知識

When talking about previous experience, you need to keep in mind that there are two meanings of the words. One is a more general meaning. We may call someone a newbie or a guru based on the overall knowledge/experience/reputation of that individual. The other is a concrete experience of participating in an event or activity (and the knowledge derived from that). For practical reasons, it is better to demand previous experience(s) in the latter sense. Most articles on ArchWiki talk about topics that are specific, and in some context. In a given context, a newbie may display proficiency, whereas a guru may show lack of interest. If you require specific previous experiences, readers have a better chance of judging their ability to follow the rest of the article.

You may also want to provide readers with links to resources that would help them gain knowledge required to understand the article.

システムの状態と設定

Sometimes, a missing package or a differently configured system component may render an article useless on some systems. Therefore, you need to track down and define all relevant system configuration (like, relevant rc.config parameters, required packages, etc) whenever possible.

ハードウェアの要件

Hardware requirements are usually fairly obvious. If you are talking about installing drivers for dial-up modem XYZ, nobody will ever think you are talking about a modem ZYX. However, in some cases it is good to mention the specific hardware requirements. For instance, if you are writing an article about installing drivers for XYZ-123, you may warn users that the same might not apply to XYZ-456.

It is also a nice touch to add the photo of the hardware your article is about to discuss.

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

Sometimes, the article's title may be slightly misleading. Therefore you may need to warn readers about the actual topic of the article, and possibly offer a link to other articles that readers might have been looking for.

For example, some readers might have thought this article was about how to format pages using wiki text. Therefore, those readers have been warned that this is not the page they were looking for, and the link to the right page was provided.

フォーマット

The formatting of the article introduction follows the usual ArchWiki customs. However, there are still details that deserve closer attention.

When listing requirements, you have two approaches. One is to verbosely explain the requirements and other introductory notes in plain (your language here). The other method is to offer a well-organized list of requirements.