「ヘルプ:記事の書き方」の版間の差分

提供: ArchWiki
ナビゲーションに移動 検索に移動
 
1行目: 1行目:
  +
[[Category:ヘルプ]]
−
#redirect[[en:Help:Writing article introductions]]
  
  +
[[en:Help:Writing article introductions]]
  +
{{Related articles start}}
  +
{{Related|ArchWiki:About}}
  +
{{Related|ヘルプ:スタイル}}
  +
{{Related|ヘルプ:編集}}
  +
{{Related|ヘルプ:記事命名ガイドライン}}
  +
{{Related|ヘルプ:効果的な見出し}}
  +
{{Related articles end}}
  +
  +
この記事は wiki の作者や編集者を対象にかかれており、実用的な記事を作成して ArchWiki の読者に見聞を広めるのを補助します。
  +
  +
この記事を読むのに wiki ページを編集する方法を知る必要はありません。[[ヘルプ:編集|技術的な編集ハウツー]]よりも、もっと全般的なスタイルガイドです。
  +
  +
== 記事のイントロダクション ==
  +
  +
The article introduction is (usually) the first thing readers encounter and has the purpose of introducing them to the topic.
  +
  +
Each article is started with a set of assumptions. These assumptions are seldom true for most readers, and an article introduction has the purpose of filtering readers that fulfill the assumptions made by writers. You do not really have to introduce readers to the rest of the article, but it may help clear some things up, that would otherwise remain unclear even after reading the whole article... many times over.
  +
  +
For instance, you may have written an article about configuring the system in a certain way. However, you have assumed that readers have a clean and freshly installed Arch Linux on their primary hard drive. How would your method be affected if the kernel was, for example, customized? Or, how would step 3 work if package X was missing?
  +
  +
You need to think about prerequisites for your method and present those prerequisites before you start your article. This has two key benefits:
  +
  +
#It allows readers to decide if they want to read the article, before they have gone too far.
  +
#It enables you to write an article without too many unnecessary digressions.
  +
  +
Number two has a huge impact on reader performance, and actually makes your article more streamlined.
  +
  +
There are a number of things you might consider including in your article introduction, but here are some of the more important ones in no particular order:
  +
  +
* previous experiences and knowledge required
  +
* system states and configuration
  +
* ownership of hardware components
  +
* what readers are ''not'' going to find in the article
  +
  +
== テキスト ==
  +
  +
We have already mentioned some things you might mention in an article introduction. We will now take a look at some of the problems in formulating an effective and useful article introduction.
  +
  +
=== 前歴と知識 ===
  +
  +
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.

2016年1月29日 (金) 16:46時点における版

関連記事

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

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

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

The article introduction is (usually) the first thing readers encounter and has the purpose of introducing them to the topic.

Each article is started with a set of assumptions. These assumptions are seldom true for most readers, and an article introduction has the purpose of filtering readers that fulfill the assumptions made by writers. You do not really have to introduce readers to the rest of the article, but it may help clear some things up, that would otherwise remain unclear even after reading the whole article... many times over.

For instance, you may have written an article about configuring the system in a certain way. However, you have assumed that readers have a clean and freshly installed Arch Linux on their primary hard drive. How would your method be affected if the kernel was, for example, customized? Or, how would step 3 work if package X was missing?

You need to think about prerequisites for your method and present those prerequisites before you start your article. This has two key benefits:

  1. It allows readers to decide if they want to read the article, before they have gone too far.
  2. It enables you to write an article without too many unnecessary digressions.

Number two has a huge impact on reader performance, and actually makes your article more streamlined.

There are a number of things you might consider including in your article introduction, but here are some of the more important ones in no particular order:

  • previous experiences and knowledge required
  • system states and configuration
  • ownership of hardware components
  • what readers are not going to find in the article

テキスト

We have already mentioned some things you might mention in an article introduction. We will now take a look at some of the problems in formulating an effective and useful article introduction.

前歴と知識

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.

「https://wiki.archlinux.jp/index.php?title=ヘルプ:記事の書き方&oldid=4852」から取得