「原稿のレイアウトについて」の編集履歴（バックアップ）一覧はこちら
「原稿のレイアウトについて」(2011/12/30 (金) 11:47:17) の最新版変更点
追加された行は緑色になります。
削除された行は赤色になります。
原稿の構成／つくりについての留意点。
*主テーマはなんであるか
主テーマがなんであるかを意識しよう。そして、主テーマに記事の分量の7割以上を割いているかをチェックしてほしい。
主テーマの前提となる解説や、余談、補足説明に記事の半分以上を費やしているのであれば、記事のテーマ設定がおかしいか、そもそも構成に問題がある。
*ついでの説明は避ける
たとえばデータベースアクセスの説明で、ついでに処理後のリダイレクトについて説明するようなパターン。
確かに、本として説明はしてあるかもしれないが、あとからリダイレクトについて調べる時にどこに書いてあるのかが分かりにくい（索引で引けば良いといえばそうなのだが）。
また、一連の技術の中で、リダイレクトがどういう位置づけにあるのかが分かりにくくなる。
説明してあれば良いというわけではない。
＃ページ数が不足してくると、とりあえずどこかのついでに押しこんでしまうということもあるので、なかなか難しかったりするのだが。
*章名、節名を並べない
よくあるのが、以下のようなパターン。
●Smarty入門
○テンプレートエンジンの種類
...本文...
このような記述は基本的に避けるべきだ。必ず●レベルから○レベル（もちろん、■から●レベルなど、その他のレベルでも同様）に移動する場合に、なにかしらのリード文を入れること。
*章、節、項のレベルはなるべく合わせること
たとえば、以下のような例は好ましくない
&color(red){★★★（保留）例を追加★★★}
また、極端に長い章（節）、短い章（節）が並ぶのは避けたい。厳密ではないが、読者に一定のテンポで記事を読ませるためにも、章／節の長さはそれなりに一定に保つのが望ましい。
*レベルアップは一定であるのが好ましい
特に入門書の場合。1～2章の間は1程度の段差であるのに、2～3章は5の段差があるような構成は避けたい。その場合には、2～3章の間になにかしらつなぎとなる説明を検討するべきである。
*階層を深くしない
書籍では章■、節●、項○、目△がせいぜい（例外的に章の上に部★を設けることもあるが、これは書籍の構成に準ずる）。ただし、目△の利用はできれば最小限にとどめたい。
上記以上の階層が必要になる場合は、明らかに階層が深すぎるので、そもそも現在の階層を一つ上の階層で整理できないかを検討するべきである。
雑誌記事などのケースでは、もっと限定して、原則的には節●、項○程度に留めるのが好ましい。
コラムのようなごく短い記事であれば、節●レベルに留めることも多いだろう。
*数値／黒丸リストは階層ではない
数値リスト、黒丸リスト（・）はあくまで「リスト」であって、いわゆる章、節、項、目と同列の階層ではないと考えた方が良い。
両者の使い分けは厳密ではないが、個人的には以下のように考える。
配下に説明を伴わない場合は中黒リスト
・項目1
・項目2
・項目3
配下に説明を伴う場合は数値リスト
（1）項目1
説明...
（2）項目2
説明...
たまに、数値リストの下に黒丸リストを入れ子で設けたり、リストの配下が異常に長い文章を見かけるが、いわゆる文書階層でないことを考えれば、これは不可。
また、数値リストの下に極端に長い文章を伴うような構造もNG。
*重要キーワードはできるだけ上位の階層に入れる
特に書籍の場合。
書籍によって違うが、目次には章、節程度までしか入らないことも多い。つまり、項、目レベルで重要なキーワードを入れても、目次としては見えてこないことがある。
この本がどんな内容を扱っているのか、という点を明確にアピールするためにも、重要なキーワードはできるだけ章、節レベルの名前に含めるのが好ましい。
*ひとつの項に複数のテーマを含めない
ひとつの項（章／節）に複数のテーマを含めてしまうと、説明が散漫になりがち。たとえば、「隠蔽とオーバライド」のような項であれば、「隠蔽」と「オーバライド」のように個々の項に分けられないかをまず検討されたい。
＃互いに不可分の概念である場合には、逆に、まとめて説明した方が良い場合もある。たとえば、AuthType（認証の種類）とAuthName（認証名）のようにまとめて指定しないと意味のないような設定を、別々の項で説明するのは却って分かりにくくなるもと。
しかし多くの場合、互いに関連し合っていても、不可分であるというケースはそれほど多くはない。どちらか概念として分かりやすいものを先に説明して、それからもう一方の概念を改めて説明した方が、説明はすっきりするだろう。
*シカケの種類は必要最小限に
記事に含まれる文書以外の要素のことをシカケと呼ぶ。シカケには、コードリスト、表、図などの他、コラムや参考、注意、メモ、註などの要素がある。
なにを使うかは書籍や記事によって違うが、あまりに類似したシカケを無制限に増やすのは好ましくない。たとえば、メモや参考は多くの場合、区別がつかないので、いずれかに統一すべきだろう。
（書籍でない）雑誌／Web記事などではそもそもリスト、表、図の他は、せいぜいコラム、註程度に留めておくのが好ましい。
リファレンス本などでは、そもそもこうしたシカケの統一感が命である。従って、最初にシカケを洗い出しておき、編集／監修と整合しておくことが重要だ。当然、最初にリストアップした以外のシカケを利用するべきではない。
*文章の中になにからなにまで含めない
たとえば、以下のような文書を想定されたい。
プラグインとはアプリケーションに小さなプログラムを追加するものです。
ScriptManager Plugin（Beta）（スクリプトマネージャープラグイン）：
スクリプト表示のサポートソフト、List Navi Plugin（Beta）
（リストナビゲーションプラグイン）：リスト表示を便利にするソフト、
Data Filters Plugin（Beta）（データフィルタープラグイン）：
データから必要なものを取り出すソフト、などがあります。
文章の中にカッコ書きが頻出しており、更に用語とその説明を区切る「：」が含まれている。これは読みにくいだけではなく、そもそも対応関係が見た目にも分かりにくく、誤解を招く原因にもなる。
このような文書は、最低でも以下のように表やリストとしてまとめ直すのが順当であろう。
プラグインとはアプリケーションに小さなプログラムを追加するものです。
以下のようなものが含まれます。
***表***
プラグイン名 呼称 概要
ScriptManager Plugin スクリプトマネージャ スクリプトの表示を制御
List Navi Plugin リストナビゲーション リストの表示を支援
Data Filters Plugin データフィルタ データから必要なものを抽出
***表***
▲主なプラグイン（2010年10月時点ではすべてβ版）
以下は余談であるが、表の内容はできるだけコンパクトに短くするべきだ。
そのため、ここでは以下のような施策を採用している。
-プラグインの説明であるので「～プラグイン」というサフィックスは不要であろうと判断して削除
-概要の「～するソフト」という表記もなくても意味が通じるので削除
-すべてがβ版であるので、キャプションで一箇所にまとめ
最低限の修正であるが、これだけでもずいぶん見た目がすっきりしたのではないだろうか。
*節、項タイトルは中身が類推できるように
節、項タイトルとして「サンプルアプリケーション」のようなタイトルを良く見かけるが、原則としてこれは不可。
この場合であれば、最低限、どんなサンプルを扱っているのか、（文脈によっては）サンプルによって本来説明すべきテーマが分かるようなタイトルにするべきだろう。
更に、（これは記事のテイストにもよるが）タイトルにある程度、結論を含める方法もある。
たとえば、「アクションメソッド」ではなく、「個々のリクエストを処理するのはアクションメソッド」のように。
もちろん、タイトルであるから、せいぜい20～30文字程度でそれ以上になるような長い文字列は避けるべき。
要は、（本文を読まずに）節、項タイトルだけをざっと眺めるだけでも、記事の全体的な流れや扱っている内容が類推できるのが好ましい。
*記事タイトルについて
言うまでもなく、記事タイトルは記事の主テーマが明確に分かるようなタイトルが好ましい。
たとえば以下のような例を考えてみよう。
-シリーズ名：初めてのCatalyst入門（5）
-個別タイトル：フロー制御とChainedアクション
このようなケースの場合、シリーズ名が明確におもてに表れている場合には問題ないが、もしシリーズ名が（たとえば新着記事一覧などに）明確に表れてこないような場合、そもそもタイトルだけでは何の記事かが明確ではない。そんなときは、個別タイトルを「Catalystのフロー制御とchainedアクション」のようにキーワードを含んだものにすることが好ましいだろう。
反面、逆のケースもある。
-Zend Frameworkで検証機能付きリッチフォームを作成する
のようなタイトルであまりビューが伸びなかった連載が、
-PHPアプリで検証機能付きリッチフォームを作成する
としたら、ビューが伸びたというケース。おそらくZend Frameworkとには興味がなくても、PHPであれば興味があるという読者が多かったのだろう。
やや小細工のような気もするが、時として、あえて特定のキーワード
を外すという選択肢もある。
＃もちろん、タイトルが中身を明確に表すべき、というのは大前提。そもそもタイトルと記事内容に乖離がある場合には、そもそも記事の信用性を疑われかねないので、Zend～の例はあくまで「そんなこともある」という程度で見ておいた方が良いだろう。
*表や図などのシカケを連続して並べない
表や図、ソースコードなど、いわゆる本文以外の文書要素のことを「シカケ」と言う。
シカケを並べるのは、特別な理由がない限り、避けるべきだ（もちろん、雑誌レイアウトのように流し込みでない場合には、この限りではない）。
必ず「この表は～です」「～は以下の図の通り」のように、なにかしら図表、リストがなんであるかを明記するべき。
これによって、曖昧な図表やリストが文中に唐突に登場するのを防ぐことができる。
*表内の文言は箇条書きでできるだけ短く
本文が「ですます」であっても、表内の説明は「だ、である」、または体言止めとするのが基本。
また、表内に延々と説明が連なるのは、原則として禁止。通常は1行に収まるようにするべきだし、どんなに多くても2行以下に留めるべきだろう。
あくまで、表は全体を列挙して見せるものであり、くどくどと中で説明が必要ならば、本文で記述するべきだ。
応用例として、概要を表でまとめておき、それ以上の説明が必要な箇所は本文で補足する方法もある。
*なんでも表に詰め込むのも考えもの
上記に関連して、表としてまとめるかどうかは安易に決めるべきではない。
表は端的に理解できる内容を一望するには便利であるが、反面、内容が凝縮するので、複雑な内容は理解しににくなるきらいもある。
一言で言い表せない内容であれば、本文なり、数字リストなりに移動して、文章できちんと解説すべきである。
*シカケを含まない文章が長すぎる
個人的には、シカケを途中に含まない文章の限界は800文字であると考える。
それ以上になる場合は、途中で図表やコードなどのシカケを含めるべきだし、もしくは項として分割することを検討するべきだ。
特に雑誌などでは、項名とシカケ（図表）をパラパラ飛ばし読みしていくだけで、なんとなく記事のサマリがわかるのが理想だ。
*ひとつしか節（項）を含まない章（節）は作らない
配下にひとつしか節（項）がない章（節）は、節（項）として分割する意味がない。
必ず複数の節（項）を作成するか、そもそも節（項）を作成しないことを検討するべき。
*註はうまく利用しよう
書籍や雑誌の体裁によって異なるが、多くの記事では、補足を表わすための欄外註、Memo、TIPS、参考などのシカケを利用できることが多い。
本文に加えると流れを損なうが、ちょっと一言添えておきたい、あるいは、関連知識などを註にうまく振り分けることで、記事本文は引き締まり、記事密度をアップできる。
特に昨今ではセキュリティ関連のツッコミが激しくなってきているので、サンプルで簡略化してあるような箇所は註で確実にフォローしておきたい（セキュリティホールのあるサンプルは、記事全体の良否に関わらず、全否定されることが多い）。
もちろん、註は註なので、あまりに長い註は避けたい。
体裁にも依るが、原則は120文字以内、どんなに長くなっても200文字を超えるべきではない。
また、本文がうまくまとまらないからと言って、すぐに註に逃がすのも厳禁。註を多用すれば、それだけ読者の視点は本文と註とを行ったり来たりしなければならないので、視点も思考もぶつぎれになってしまう。
＃特に編集／監修からの指摘に対する対応が註になることが多いが、多くの場合、不自然なので、まずは前後の文章を精査されたい。
*できるだけ具体的なコードを
ただ単に構文規則や注意点を言葉で説明しても、なかなか分かってもらえないことは多い。
できるだけサンプルコードや用例を加えることで、読者はよりイメージを持って記事を読むことができる。
*重要キーワードは太字で強調
あまり多用するべきではないが、重要なキーワードや主張については太字で強調することも多い。書籍などではうまく利用すれば、重要箇所を視覚的にも目立たせることができるだろう。
重ねてではあるが、濫用すれば誌面がうるさくなるので、濫用は厳禁。そもそも編集者によっては、太字の利用を嫌う人もいるようだ。
ちなみに、強調する内容をカギカッコで目立たせる方法もあるが、これも必要最小限にしたい。太字にせよカギカッコにせよ、必要最小限が原則。まずは、文章そのもので軽重を書き分けるのが基本。
*リード文はなるべく簡潔に
章や節の頭につけるリード文。体裁にも依るが、基本的な導入のための「lead（先導）」なので、基本的にはごくシンプルな文章でまとめるべき。
かつ、「これから何を説明しようとしているのか」を明確に表わす文章にしたい。最初に、これから何が起ころうとしているのかがわかるだけで、読者は安心してその記事を読める。
リード文だからといって、おざなりな文章にすることなかれ。
*説明を後回しにする場合にはその旨を明記
初出の概念や機能について、とりあえずキーワードだけ登場して、あとから説明したいという場合がある。このようなケースでは、できるだけ「後述するが」や「詳しくはどこそこで」という枕詞を加えたい。これによって、読者も安心して読み進められるはずだ。
＃ただし、そのキーワードを理解していないと、現在の説明が十分に理解できないと判断される場合には、最低限一言は補っておきたい。その上で、詳細は「どこそこで」とするのはもちろん構わない。
なお、「後述するが」があまりに頻出する場合には、そもそも構成に問題があることもあるので要注意。そもそも「後述」は例外的な扱いであるはずで、一から積み上げ式に説明していくのがベスト。
*余談なのか本論なのかを明確に
本題と余談とは明確に区別するべき。*****************
*サンプルデータに他出版社の情報を使わない
これは出版社によって方針が異なるので、一概には言えない。
しかし、たとえばA社の記事でB社の書籍データを見せるようなことは避けた方が無難だ。
場合によっては、サンプルデータを作り直しとなり、関連する原稿、キャプチャをすべて取り直し、という結構悲惨な目に遭うこととなる（経験者語る）。
*初期環境設定はひとつレベルを落として
書籍では、読者質問の6～7割までが環境設定に関するものであることが多い。
また、読者反応を見ても、環境設定の説明が不明確であるばかりに、ダメ本の烙印を捺されることすらある（読者にとっては、後の説明がまったく無意味になってしまうので、これは当然と言えば当然のことだ）。
初期環境設定はひとつレベルを落として、確実に読者が導入できるようにしたい。特に初心者本では理屈はさておき、手順さえ踏めば、まずは環境が導入できる、というレベルにまで落とし込みたい。環境設定の説明では、陥りがちなトラブルや誤りについても、十分にフォローするように心がけたい。
*環境設定の意味は明確に
インストール手順や環境設定というと、ただ手順だけを列記して終わりになりがちであるが、原則として、行っていることの意味は明確にすべき。たとえば、コマンドやパラメータ、選択オプション個々の意味など。
もちろん、環境設定の手順があまりに長くなっては本末転倒であるが、読者が「今自分で何をしているか」を理解しながら手順を進めることで、手順の間違いも減らすことができる。
*キャラクターなどの利用について
オリジナルキャラクターなどを用いて、記事を親しみやすくするような試みはよく行われる。
が、これらの利用は多くの場合は作り手に負荷を強いるので、執筆の初心者にはお勧めしない。
キャラクターを利用する場合には、原則として、記事の中で、それなりに登場の必然性がある必要がある（ただ、カッコイイ、かわいいというだけならばやめた方が良い）。
また、そもそもキャラクターと記事内容をリンクさせるために、記述が不必要に冗長になりがちであることから、記事そのものの記述に集中しにくくなる。
*図や説明の再掲も時には必要
前後篇やシリーズにまたがる記事の場合。重要な解説や概念図は、時として再掲するのもあり。
あまり復習や再掲に誌面を割いてしまうのは（もちろん）好ましくないが、前回の内容に密接に関わるテーマを扱っている場合、唐突に「前回の続き」として解説をはじめるよりも、多少の助走（再掲）を付けた方がすんなりと記事に入っていける。
＃特に雑誌等の場合は、必ずしもシリーズを通して記事を読んでもらっているわけではないので、その点も考慮されたい。
*関連ページにはできるだけ参照を
書籍の場合。関連するテーマにはできるだけ参照を加えておくのが好ましい。これによって、読者は必要に応じて関連箇所を見ながら、理解を深めることができる。
ただし、章、節、項番号で場所を特定できる場合には、P.●○ではなく、●.●節のような指定が好ましい。というのも、ページ数は校正段階で大きく変動の可能性があるため。もちろん、最後で整合の確認はするが、作業上も負荷となるし、そもそも間違いの原因にもなる。
また、同じ個所への参照が近接する箇所に続いて登場するのも、多くの場合は無駄なので、「その参照が本当に必要か」は適宜検討されたい。
*リファレンスではレイアウトが最重要
リファレンス本では、いかに決められた制約（レイアウト）の中で必要な情報をまとめるかが、原稿の良否を左右する。
＃他の種類の本でも同様であるが、特にリファレンス本では、ということ。
とりあえずレイアウトは後回し、文章だけを作成したというのは、絶対に避けるべきだ。その文章をレイアウトにあてはめる手間は、リファレンス本の場合はあまりに膨大であるからだ。
＃おそらく文章（内容）への影響も相当量になるはずだ。
リファレンス本では、（特に）レイアウトは内容の一環である。
*索引について
1. 隣接するページを索引に入れない
&color(red){★★★（保留）★★★}
原稿の構成／つくりについての留意点。
*主テーマはなんであるか
主テーマがなんであるかを意識しよう。そして、主テーマに記事の分量の7割以上を割いているかをチェックしてほしい。
主テーマの前提となる解説や、余談、補足説明に記事の半分以上を費やしているのであれば、記事のテーマ設定がおかしいか、そもそも構成に問題がある。
*ついでの説明は避ける
たとえばデータベースアクセスの説明で、ついでに処理後のリダイレクトについて説明するようなパターン。
確かに、本として説明はしてあるかもしれないが、あとからリダイレクトについて調べる時にどこに書いてあるのかが分かりにくい（索引で引けば良いといえばそうなのだが）。
また、一連の技術の中で、リダイレクトがどういう位置づけにあるのかが分かりにくくなる。
説明してあれば良いというわけではない。
＃ページ数が不足してくると、とりあえずどこかのついでに押しこんでしまうということもあるので、なかなか難しかったりするのだが。
*章名、節名を並べない
よくあるのが、以下のようなパターン。
●Smarty入門
○テンプレートエンジンの種類
...本文...
このような記述は基本的に避けるべきだ。必ず●レベルから○レベル（もちろん、■から●レベルなど、その他のレベルでも同様）に移動する場合に、なにかしらのリード文を入れること。
*章、節、項のレベルはなるべく合わせること
たとえば、以下のような例は好ましくない
&color(red){★★★（保留）例を追加★★★}
また、極端に長い章（節）、短い章（節）が並ぶのは避けたい。厳密ではないが、読者に一定のテンポで記事を読ませるためにも、章／節の長さはそれなりに一定に保つのが望ましい。
*レベルアップは一定であるのが好ましい
特に入門書の場合。1～2章の間は1程度の段差であるのに、2～3章は5の段差があるような構成は避けたい。その場合には、2～3章の間になにかしらつなぎとなる説明を検討するべきである。
*階層を深くしない
書籍では章■、節●、項○、目△がせいぜい（例外的に章の上に部★を設けることもあるが、これは書籍の構成に準ずる）。ただし、目△の利用はできれば最小限にとどめたい。
上記以上の階層が必要になる場合は、明らかに階層が深すぎるので、そもそも現在の階層を一つ上の階層で整理できないかを検討するべきである。
雑誌記事などのケースでは、もっと限定して、原則的には節●、項○程度に留めるのが好ましい。
コラムのようなごく短い記事であれば、節●レベルに留めることも多いだろう。
*数値／黒丸リストは階層ではない
数値リスト、黒丸リスト（・）はあくまで「リスト」であって、いわゆる章、節、項、目と同列の階層ではないと考えた方が良い。
両者の使い分けは厳密ではないが、個人的には以下のように考える。
配下に説明を伴わない場合は中黒リスト
・項目1
・項目2
・項目3
配下に説明を伴う場合は数値リスト
（1）項目1
説明...
（2）項目2
説明...
たまに、数値リストの下に黒丸リストを入れ子で設けたり、リストの配下が異常に長い文章を見かけるが、いわゆる文書階層でないことを考えれば、これは不可。
また、数値リストの下に極端に長い文章を伴うような構造もNG。
*重要キーワードはできるだけ上位の階層に入れる
特に書籍の場合。
書籍によって違うが、目次には章、節程度までしか入らないことも多い。つまり、項、目レベルで重要なキーワードを入れても、目次としては見えてこないことがある。
この本がどんな内容を扱っているのか、という点を明確にアピールするためにも、重要なキーワードはできるだけ章、節レベルの名前に含めるのが好ましい。
*ひとつの項に複数のテーマを含めない
ひとつの項（章／節）に複数のテーマを含めてしまうと、説明が散漫になりがち。たとえば、「隠蔽とオーバライド」のような項であれば、「隠蔽」と「オーバライド」のように個々の項に分けられないかをまず検討されたい。
＃互いに不可分の概念である場合には、逆に、まとめて説明した方が良い場合もある。たとえば、AuthType（認証の種類）とAuthName（認証名）のようにまとめて指定しないと意味のないような設定を、別々の項で説明するのは却って分かりにくくなるもと。
しかし多くの場合、互いに関連し合っていても、不可分であるというケースはそれほど多くはない。どちらか概念として分かりやすいものを先に説明して、それからもう一方の概念を改めて説明した方が、説明はすっきりするだろう。
*シカケの種類は必要最小限に
記事に含まれる文書以外の要素のことをシカケと呼ぶ。シカケには、コードリスト、表、図などの他、コラムや参考、注意、メモ、註などの要素がある。
なにを使うかは書籍や記事によって違うが、あまりに類似したシカケを無制限に増やすのは好ましくない。たとえば、メモや参考は多くの場合、区別がつかないので、いずれかに統一すべきだろう。
（書籍でない）雑誌／Web記事などではそもそもリスト、表、図の他は、せいぜいコラム、註程度に留めておくのが好ましい。
リファレンス本などでは、そもそもこうしたシカケの統一感が命である。従って、最初にシカケを洗い出しておき、編集／監修と整合しておくことが重要だ。当然、最初にリストアップした以外のシカケを利用するべきではない。
*文章の中になにからなにまで含めない
たとえば、以下のような文書を想定されたい。
プラグインとはアプリケーションに小さなプログラムを追加するものです。
ScriptManager Plugin（Beta）（スクリプトマネージャープラグイン）：
スクリプト表示のサポートソフト、List Navi Plugin（Beta）
（リストナビゲーションプラグイン）：リスト表示を便利にするソフト、
Data Filters Plugin（Beta）（データフィルタープラグイン）：
データから必要なものを取り出すソフト、などがあります。
文章の中にカッコ書きが頻出しており、更に用語とその説明を区切る「：」が含まれている。これは読みにくいだけではなく、そもそも対応関係が見た目にも分かりにくく、誤解を招く原因にもなる。
このような文書は、最低でも以下のように表やリストとしてまとめ直すのが順当であろう。
プラグインとはアプリケーションに小さなプログラムを追加するものです。
以下のようなものが含まれます。
***表***
プラグイン名 呼称 概要
ScriptManager Plugin スクリプトマネージャ スクリプトの表示を制御
List Navi Plugin リストナビゲーション リストの表示を支援
Data Filters Plugin データフィルタ データから必要なものを抽出
***表***
▲主なプラグイン（2010年10月時点ではすべてβ版）
以下は余談であるが、表の内容はできるだけコンパクトに短くするべきだ。
そのため、ここでは以下のような施策を採用している。
-プラグインの説明であるので「～プラグイン」というサフィックスは不要であろうと判断して削除
-概要の「～するソフト」という表記もなくても意味が通じるので削除
-すべてがβ版であるので、キャプションで一箇所にまとめ
最低限の修正であるが、これだけでもずいぶん見た目がすっきりしたのではないだろうか。
*節、項タイトルは中身が類推できるように
節、項タイトルとして「サンプルアプリケーション」のようなタイトルを良く見かけるが、原則としてこれは不可。
この場合であれば、最低限、どんなサンプルを扱っているのか、（文脈によっては）サンプルによって本来説明すべきテーマが分かるようなタイトルにするべきだろう。
更に、（これは記事のテイストにもよるが）タイトルにある程度、結論を含める方法もある。
たとえば、「アクションメソッド」ではなく、「個々のリクエストを処理するのはアクションメソッド」のように。
もちろん、タイトルであるから、せいぜい20～30文字程度でそれ以上になるような長い文字列は避けるべき。
要は、（本文を読まずに）節、項タイトルだけをざっと眺めるだけでも、記事の全体的な流れや扱っている内容が類推できるのが好ましい。
*項タイトルの付け方（逆引きリファレンスの場合）
原則として、メソッド名や機能名そのものをタイトルとしない。
たとえば、「ディレクトリインデックスを設定する」では機能を理解していなければ中身を類推できない。たとえば「ファイル名が省略された時に表示するページを指定する」などと、できるだけ具体的な内容でまとめること。
*記事タイトルについて
言うまでもなく、記事タイトルは記事の主テーマが明確に分かるようなタイトルが好ましい。
たとえば以下のような例を考えてみよう。
-シリーズ名：初めてのCatalyst入門（5）
-個別タイトル：フロー制御とChainedアクション
このようなケースの場合、シリーズ名が明確におもてに表れている場合には問題ないが、もしシリーズ名が（たとえば新着記事一覧などに）明確に表れてこないような場合、そもそもタイトルだけでは何の記事かが明確ではない。そんなときは、個別タイトルを「Catalystのフロー制御とchainedアクション」のようにキーワードを含んだものにすることが好ましいだろう。
反面、逆のケースもある。
-Zend Frameworkで検証機能付きリッチフォームを作成する
のようなタイトルであまりビューが伸びなかった連載が、
-PHPアプリで検証機能付きリッチフォームを作成する
としたら、ビューが伸びたというケース。おそらくZend Frameworkとには興味がなくても、PHPであれば興味があるという読者が多かったのだろう。
やや小細工のような気もするが、時として、あえて特定のキーワード
を外すという選択肢もある。
＃もちろん、タイトルが中身を明確に表すべき、というのは大前提。そもそもタイトルと記事内容に乖離がある場合には、そもそも記事の信用性を疑われかねないので、Zend～の例はあくまで「そんなこともある」という程度で見ておいた方が良いだろう。
*表や図などのシカケを連続して並べない
表や図、ソースコードなど、いわゆる本文以外の文書要素のことを「シカケ」と言う。
シカケを並べるのは、特別な理由がない限り、避けるべきだ（もちろん、雑誌レイアウトのように流し込みでない場合には、この限りではない）。
必ず「この表は～です」「～は以下の図の通り」のように、なにかしら図表、リストがなんであるかを明記するべき。
これによって、曖昧な図表やリストが文中に唐突に登場するのを防ぐことができる。
*表内の文言は箇条書きでできるだけ短く
本文が「ですます」であっても、表内の説明は「だ、である」、または体言止めとするのが基本。
また、表内に延々と説明が連なるのは、原則として禁止。通常は1行に収まるようにするべきだし、どんなに多くても2行以下に留めるべきだろう。
あくまで、表は全体を列挙して見せるものであり、くどくどと中で説明が必要ならば、本文で記述するべきだ。
応用例として、概要を表でまとめておき、それ以上の説明が必要な箇所は本文で補足する方法もある。
*なんでも表に詰め込むのも考えもの
上記に関連して、表としてまとめるかどうかは安易に決めるべきではない。
表は端的に理解できる内容を一望するには便利であるが、反面、内容が凝縮するので、複雑な内容は理解しににくなるきらいもある。
一言で言い表せない内容であれば、本文なり、数字リストなりに移動して、文章できちんと解説すべきである。
*シカケを含まない文章が長すぎる
個人的には、シカケを途中に含まない文章の限界は800文字であると考える。
それ以上になる場合は、途中で図表やコードなどのシカケを含めるべきだし、もしくは項として分割することを検討するべきだ。
特に雑誌などでは、項名とシカケ（図表）をパラパラ飛ばし読みしていくだけで、なんとなく記事のサマリがわかるのが理想だ。
*ひとつしか節（項）を含まない章（節）は作らない
配下にひとつしか節（項）がない章（節）は、節（項）として分割する意味がない。
必ず複数の節（項）を作成するか、そもそも節（項）を作成しないことを検討するべき。
*註はうまく利用しよう
書籍や雑誌の体裁によって異なるが、多くの記事では、補足を表わすための欄外註、Memo、TIPS、参考などのシカケを利用できることが多い。
本文に加えると流れを損なうが、ちょっと一言添えておきたい、あるいは、関連知識などを註にうまく振り分けることで、記事本文は引き締まり、記事密度をアップできる。
特に昨今ではセキュリティ関連のツッコミが激しくなってきているので、サンプルで簡略化してあるような箇所は註で確実にフォローしておきたい（セキュリティホールのあるサンプルは、記事全体の良否に関わらず、全否定されることが多い）。
もちろん、註は註なので、あまりに長い註は避けたい。
体裁にも依るが、原則は120文字以内、どんなに長くなっても200文字を超えるべきではない。
また、本文がうまくまとまらないからと言って、すぐに註に逃がすのも厳禁。註を多用すれば、それだけ読者の視点は本文と註とを行ったり来たりしなければならないので、視点も思考もぶつぎれになってしまう。
＃特に編集／監修からの指摘に対する対応が註になることが多いが、多くの場合、不自然なので、まずは前後の文章を精査されたい。
*できるだけ具体的なコードを
ただ単に構文規則や注意点を言葉で説明しても、なかなか分かってもらえないことは多い。
できるだけサンプルコードや用例を加えることで、読者はよりイメージを持って記事を読むことができる。
*重要キーワードは太字で強調
あまり多用するべきではないが、重要なキーワードや主張については太字で強調することも多い。書籍などではうまく利用すれば、重要箇所を視覚的にも目立たせることができるだろう。
重ねてではあるが、濫用すれば誌面がうるさくなるので、濫用は厳禁。そもそも編集者によっては、太字の利用を嫌う人もいるようだ。
ちなみに、強調する内容をカギカッコで目立たせる方法もあるが、これも必要最小限にしたい。太字にせよカギカッコにせよ、必要最小限が原則。まずは、文章そのもので軽重を書き分けるのが基本。
*リード文はなるべく簡潔に
章や節の頭につけるリード文。体裁にも依るが、基本的な導入のための「lead（先導）」なので、基本的にはごくシンプルな文章でまとめるべき。
かつ、「これから何を説明しようとしているのか」を明確に表わす文章にしたい。最初に、これから何が起ころうとしているのかがわかるだけで、読者は安心してその記事を読める。
リード文だからといって、おざなりな文章にすることなかれ。
*説明を後回しにする場合にはその旨を明記
初出の概念や機能について、とりあえずキーワードだけ登場して、あとから説明したいという場合がある。このようなケースでは、できるだけ「後述するが」や「詳しくはどこそこで」という枕詞を加えたい。これによって、読者も安心して読み進められるはずだ。
＃ただし、そのキーワードを理解していないと、現在の説明が十分に理解できないと判断される場合には、最低限一言は補っておきたい。その上で、詳細は「どこそこで」とするのはもちろん構わない。
なお、「後述するが」があまりに頻出する場合には、そもそも構成に問題があることもあるので要注意。そもそも「後述」は例外的な扱いであるはずで、一から積み上げ式に説明していくのがベスト。
*余談なのか本論なのかを明確に
本題と余談とは明確に区別するべき。*****************
*サンプルデータに他出版社の情報を使わない
これは出版社によって方針が異なるので、一概には言えない。
しかし、たとえばA社の記事でB社の書籍データを見せるようなことは避けた方が無難だ。
場合によっては、サンプルデータを作り直しとなり、関連する原稿、キャプチャをすべて取り直し、という結構悲惨な目に遭うこととなる（経験者語る）。
*初期環境設定はひとつレベルを落として
書籍では、読者質問の6～7割までが環境設定に関するものであることが多い。
また、読者反応を見ても、環境設定の説明が不明確であるばかりに、ダメ本の烙印を捺されることすらある（読者にとっては、後の説明がまったく無意味になってしまうので、これは当然と言えば当然のことだ）。
初期環境設定はひとつレベルを落として、確実に読者が導入できるようにしたい。特に初心者本では理屈はさておき、手順さえ踏めば、まずは環境が導入できる、というレベルにまで落とし込みたい。環境設定の説明では、陥りがちなトラブルや誤りについても、十分にフォローするように心がけたい。
*環境設定の意味は明確に
インストール手順や環境設定というと、ただ手順だけを列記して終わりになりがちであるが、原則として、行っていることの意味は明確にすべき。たとえば、コマンドやパラメータ、選択オプション個々の意味など。
もちろん、環境設定の手順があまりに長くなっては本末転倒であるが、読者が「今自分で何をしているか」を理解しながら手順を進めることで、手順の間違いも減らすことができる。
*キャラクターなどの利用について
オリジナルキャラクターなどを用いて、記事を親しみやすくするような試みはよく行われる。
が、これらの利用は多くの場合は作り手に負荷を強いるので、執筆の初心者にはお勧めしない。
キャラクターを利用する場合には、原則として、記事の中で、それなりに登場の必然性がある必要がある（ただ、カッコイイ、かわいいというだけならばやめた方が良い）。
また、そもそもキャラクターと記事内容をリンクさせるために、記述が不必要に冗長になりがちであることから、記事そのものの記述に集中しにくくなる。
*図や説明の再掲も時には必要
前後篇やシリーズにまたがる記事の場合。重要な解説や概念図は、時として再掲するのもあり。
あまり復習や再掲に誌面を割いてしまうのは（もちろん）好ましくないが、前回の内容に密接に関わるテーマを扱っている場合、唐突に「前回の続き」として解説をはじめるよりも、多少の助走（再掲）を付けた方がすんなりと記事に入っていける。
＃特に雑誌等の場合は、必ずしもシリーズを通して記事を読んでもらっているわけではないので、その点も考慮されたい。
*関連ページにはできるだけ参照を
書籍の場合。関連するテーマにはできるだけ参照を加えておくのが好ましい。これによって、読者は必要に応じて関連箇所を見ながら、理解を深めることができる。
ただし、章、節、項番号で場所を特定できる場合には、P.●○ではなく、●.●節のような指定が好ましい。というのも、ページ数は校正段階で大きく変動の可能性があるため。もちろん、最後で整合の確認はするが、作業上も負荷となるし、そもそも間違いの原因にもなる。
また、同じ個所への参照が近接する箇所に続いて登場するのも、多くの場合は無駄なので、「その参照が本当に必要か」は適宜検討されたい。
*リファレンスではレイアウトが最重要
リファレンス本では、いかに決められた制約（レイアウト）の中で必要な情報をまとめるかが、原稿の良否を左右する。
＃他の種類の本でも同様であるが、特にリファレンス本では、ということ。
とりあえずレイアウトは後回し、文章だけを作成したというのは、絶対に避けるべきだ。その文章をレイアウトにあてはめる手間は、リファレンス本の場合はあまりに膨大であるからだ。
＃おそらく文章（内容）への影響も相当量になるはずだ。
リファレンス本では、（特に）レイアウトは内容の一環である。
*索引について
1. 隣接するページを索引に入れない
&color(red){★★★（保留）★★★}
