「ヘルプ:効果的な見出し」の版間の差分

提供: ArchWiki
ナビゲーションに移動 検索に移動
(→‎見出しと目次: 追加訳出)
48行目: 48行目:
 
=== 見出しと目次 ===
 
=== 見出しと目次 ===
   
  +
ページの目次は、2つ以上の見出しがあるときに自動で生成されます。目次を隠すには、ページのどこかに次のコードの行を追加する必要があります。
A table of contents for an article is created automatically when more than two headers are defined. In order to hide the TOC, you may include a line with the following code anywhere in your article:
 
   
 
<nowiki>__NOTOC__</nowiki>
 
<nowiki>__NOTOC__</nowiki>

2020年4月9日 (木) 12:39時点における版

関連記事

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

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

記事の見出しについて

見出しは新しいセクションの始まりを示します。セクションはツリーの形で、他のセクションの中に配置することができます。セクションの構造を反映させるために、見出しは複数の書き方があります。セクションとその対応する見出しは、他のセクションとの相対的な位置によってレベル分けされます。

この記事で使用する用語

他のセクションに含まれているセクションは、そのコンテナ(または)よりも低レベルと呼ばれます。つまり親は高レベルということです。

それぞれの見出しと、同じレベルの次の見出しまでを表わすテキストは、ヘディングと呼ばれます。

ヘディングはツリーの中でのレベルを表現する番号を持っています。高いレベルのヘディングは小さい番号で、その逆も同じです。例えば、ArchWiki でのページのタイトルはヘディングレベル1です。

見出しの使用

見出しとヘディングはいくつかの重要な目的のために使われます。

  • より情報を吸収できるように読者の読む速度を下げる
  • ページの一部を論理的なグループにまとめる
  • 重要なテキストであることを示す

読者の足を止めさせる

読者にトピックを導入するとき、短いページでも読むのにある程度の時間が必要であることを知っている必要があります。見出しは、それに続くセクションを読む前に読者の読む速度を下げる緩衝材として機能します。これにより、読者に内容について考え、続くテキストを読む準備をさせることができます。

パラグラフをサブトピックにまとめる

ほとんどの場合、ページはただ1つのトピックだけにとどまらず、主要なトピックを説明して拡大するために、関連するトピックに寄り道する必要があるでしょう。そのような寄り道は、読者が全体をざっと読むときには混乱を招くかもしれません。そのため、そのような寄り道を知らせる必要があります。

重要な部分を目立たせる

時々、読者はページの中で特に興味のある部分を探すため、目次だけを見たいかもしれません。見出しだけを見るかもしれません。どちらの場合も、明確に書かれた見出しはページの重要なセクションを見つけるのに役立ちます。さらに、目次は自動で生成され、ページ内のヘディングをリストアップします。

見出しと目次

ページの目次は、2つ以上の見出しがあるときに自動で生成されます。目次を隠すには、ページのどこかに次のコードの行を追加する必要があります。

__NOTOC__

見出しのレベルについて

There are some important things to note when talking about heading levels.

重要性が等価なら同じレベルの見出しを使う

This may sound self-explanatory, but it is not quite as straightforward as it seems. Consider this example:

  • Introduction
  • Step 1: Installing X
  • Step 2: Editing keyboard settings
  • Step 3: Editing mouse settings
  • Step 4: Editing display settings
  • Step 5: Adding fglrx options
  • Step 6: Starting X
  • Conclusions

If you carefully analyze this list, you will notice that steps 2 to 4 are actually of less significance than steps 1 and 6, and that step 5 is of least significance. This is not to say that all those steps have more or less text than the others. It is the conceptual significance that is important.

To amend this, we will modify the headings like so:

  • Introduction
  • Step 1: Installing X
  • Step 2: Configuring X
    • Step 2a: Editing keyboard settings
    • Step 2b: Editing mouse settings
    • Step 2c: Editing display settings
      • Step 2c-1: Adding fglrx options
  • Step 3: Starting X
  • Conclusions

As you can see, we have merged steps 2 to 4 into a single heading titled Configuring X, and divided the heading into 3 subheadings. Also, we have attached the step 5 to step 2c, and turned it into a subheading.

Top level headings should always be of highest level

This may also sound like common sense, but there is one little problem. The headers have formatting style associated with them. Many people use those associated formatting rules to manipulate how their article looks. This in turns yield a broken heading structure.

Let us take a look at this example:

  • Introduction
  • Step 1
  • Step 2
  • Step 3
    • Conclusion

The author of the article thought level 1 headings was too large for such an unimportant section like Conclusion and it would be a better idea to use level 2 headings. This results in a heading structure that has the last section one level below the other sections. The correct structure would be:

  • Introduction
  • Step 1
  • Step 2
  • Step 3
  • Conclusion

The conclusion is now in line with the rest of the article.

ノート: It may seem somewhat awkward that sections like Introduction or Conclusion are given same importance as the main article, but those sections are in fact important. It is always better to add a note (one like this) at the end of the article, or completely exclude poorly formulated or lacking sections than to demote them into lower level headings and break the article's logical structure for the sake of aesthetic issues.

Types of heading structures

Based on the number of levels used and their purpose, heading structure may be divided into following categories:

  1. Single-level structure
  2. False multi-level structure
  3. Multi-level structure

Single-level structure

When writing an article, the most straightforward way is to divide it into steps. Those steps may not necessarily be real steps, something that readers need to take. They may be steps that a writer takes in developing his article. In any case, those steps follow one another and are arranged in a single-level structure.

A typical setup of this kind may look like this:

  • Introduction
  • Step 1: doing this or the other
  • Step 2: cleaning up
  • Step 3: troubleshooting
  • Further reading

This is what a simple 3-step HOWTO with introduction and references may look.

False multi-level structure

Sometimes, there is a need to deviate from the simple and flowing single-level structure.

Side-note

Usually, you need to deviate shortly from the main flow to elaborate on something.

  • Introduction
  • Step 1: doing this or the other
    • Notes on configuring XYZ
  • Step 2: cleaning up
  • Step 3: troubleshooting
  • Further reading

Consider this an alternative to adding notes and comments via the Note template.

Mark auxiliary information

Maybe you want to add a marker to some important part that acts as a additional argument to main discussion, or enhances the main discussion in some other way.

  • Introduction
  • Step 1: doing this or the other
    • Here is the sample code
  • Step 2: cleaning up
    • Here is the sample code
  • Step 3: troubleshooting
    • Here is the sample code
  • Further reading

Multi-level structure

Multi-level structure is typical of longer, more in-depth articles. However, it may also be effectively used in shorter HOWTOs.

Here are some cases when a multi-level structure may come in handy.

ノート: Keep in mind that we are describing parent-child relationships of heading levels, and that it is not important if the parent is level 1, or 2, or 3. The same applies to all multi-level structures that have 2 or more levels.

Group arguments together

Subheadings can be to main headings what headings are to the entire article.

An example:

  • Introduction
  • Step 1: doing this or the other
  • Step 2: cleaning up
    • First do this
    • Then do that
    • You're done!
  • Step 3: troubleshooting
  • Further reading

Alternative arguments

Sometimes, you need to give your readers a few different angles on a subject.

For example:

  • Introduction
  • Step 1: doing this or the other
    • This is one way to do it
    • This is another way to do it
  • Step 2: cleaning up
  • Step 3: troubleshooting
  • Further reading

Contradictory argument

If you need to talk about opposing arguments, you may give each party a subheading of its own.

For instance:

  • Introduction
  • Step 1: doing this or the other
    • You want this
    • There are reasons for not wanting this, though
  • Step 2: cleaning up
  • Step 3: troubleshooting
  • Further reading

見出しの文章

We will summarize some of the key points here, and if you want a more detailed account, you may read ヘルプ:記事命名ガイドライン. The rules listed here apply to both header texts and article names.

  • Header texts should be as specific as possible, and they should reflect the heading's scope
  • Header texts should be general enough to allow for future enhancement of headings
  • Header texts should be as short as possible (also see ヘルプ:記事命名ガイドライン)

フォーマット

As we already noted, it is crucial not to abuse header formatting styles to beautify your articles. If you do not like what you see, contact the admins or sysops and ask for their opinion, or offer to fix the situation in a manner that would not compromise the heading structures.

To mark some text as a heading, two or more equal signs (==) must be used.

ノート: The lowest-supported heading level would actually be 1 (=), but its formatting is reserved for article titles: article sections must always start from level 2.

Here is the code for marking headers:

==Header level 2==
===Header level 3===
====Header level 4====
=====Header level 5=====
======Header level 6======

If you want to see how these are formatted, you may use the Sandbox.