文章の書き方について。
対象読者によってどこまで解説すべきか、どんなキャプチャを見せるべきかは変化する。
最初からいきなり細かな話をしてしまい、全体像が見えない記事は意外と多い。
まずは、テーマの外枠を鳥瞰できる説明を先頭で明示し、これから説明する個々のトピックの位置づけを明確にすること。
その上で、個々のトピック説明を展開していけば、読者は途中で置いていかれても、先頭に戻れば記事の全体像を再確認できる。また、最初に全体が見えているので、個々のトピックも安心して読み進められる。
＃これはTIPSのような短い記事でも基本は同様。これからなにを説明するのかをまずは先頭で示すべし。
なお、「外枠を鳥瞰できる説明」は、可能であれば図示できるのが望ましいが、文章でも可。ただし、「鳥瞰」なのであくまで短くコンパクトにが基本。
上記に関連して。記事全体ではなく、個々の節でも結論は最初に。 ある機能や概念の説明をする場合、前置きを置かずに、まずは「●○とは～のことである」と明確に言い切るのが基本。
前置きが長かったり、または、付随的な説明が先行してしまうと、そもそも最後まで説明を読み終わるまで、読者には結論が分からない。
入門記事はミステリーではない。
文章にちょっと補足をしたい場合にカッコ書きを使うのはよくあることだ。しかし、多用すれば、文章本来の流れを損ない、読者の注意を散漫にしてしまいかねない。できるだけ本文の流れの中で説明することを考えたい。
また、註を利用できるレイアウトであれば、カッコ書きをするくらいならば、そもそも註とすることを考えるべきだろう。 ＃もちろん、註の多用も上記と同じ理由で過度には避けたい。
たとえば「リンクボタンクリック」のような名詞同士をなんとなく連結したような記述は避ける。「リンクボタンのクリック」のように、明確に助詞を加えるのが望ましい。
文やキーワードを強調する「...」。命令やメソッド名のすべてにカギカッコを付けている原稿も時折見かけるが、これはあまり望ましくない。カギカッコは文章をチープに見せるのみならず、見栄え的にも不細工であるからだ。
原則として、強調としてのカギカッコは原則として利用すべきでない。強調したい個所は、まずは文章として表すべきだ。究極、カギカッコは引用の用途にのみ留めるのが望ましいだろう。
最初に結論を述べる、これから説明することの全体像を見せること、 は大切だ。
しかし、それだけでは不十分。説明が長くなった場合には、それぞれの項や節レベルの最後でなにかしらサマリとなる一言を入れることで、格段に文章が読みやすくなる。「要は...ということ」「まとめると...」など。
ひとつの話題はできるけ一箇所で説明するのが望ましい。大きな話題で複数個所に分散せざるを得ない場合には、最初に全体像が分かるような説明を明確に示すこと。また、ページ参照など互いに行き来できるような目印を加えるのが望ましい。
＃複数個所に分散せざるを得ない場合＞短い雑誌記事などではあまりないように感じる。
上とは逆の話。ひとつの項にはひとつの話題が基本。
特にページ数が足りなくなった場合に起こりがちだが、ひとつの項になんでもかんでも詰め込まない。複数の話題は論点をあいまいにする原因だからだ。
リファレンスや逆引き、TIPSなどの書籍では、特に要注意。複数の話題を詰め込むことで、目的別の検索がしにくくなる。
ある概念を説明するのに、それそのものの説明をするだけでは不十分だ。できれば、類似（関連）する概念と合わせて、その共通点や相違点を合わせて解説することで、本来説明したかった内容をより浮き彫りにできる。
類似／比較を示すには、図表を使うのも効果的だろう。
執筆初心者に意外と多いのが、「この」「あの」という指示代名詞。
これら指示代名詞は指し示している先を曖昧にしてしまうばかりではなく、文章を冗長にする一因でもあるので、できるだけ避けるべきだ。
読んでみて、あまりに多いなと思ったら、まずはすべて取り除いてみて、意味が通じないかを検討するべき。
それでどうしても仕方ないところは、「この～」ではなく「●○メソッドの～」のように具体的な名詞で置き換えられないかを検討する。
以上でもって、どうしても避けられない場合に初めて、指示代名詞を使用すればよい。
流れにのっていない文章では、どうしても接続詞が多くなりがちであるようだ。接続詞が多い文章は多くの場合、冗長で読みにくいことが多いので、要注意だ。
特に「そして」「また」が連続するような文章は読みにくい。
「そして」は多くの場合、外しても問題ないはずであるし、「また」が連続するような文章は数字リストとして置き換えられないかを検討されたい。
リストにすることで
などのメリットがある。
文章内にちょっとした注釈という意味で、カッコを利用することはよくある。しかし、多用すると、結局、文章全体としてなにを言っているのかが分かりにくくなりがち。
どんなに多くても、カッコはせいぜい1項に1個程度に留めたい。
また、カッコの中の文章が極端に長いのもおかしいので、その場合はカッコの外に出せないかを検討されたい。註があるなら註に逃がすのもありだが、安易に註に逃がすのも考えもの。
段落が少ない文章は必要以上に詰まって見えるため、読みにくい。
しかし、一文ごとに段落をつけてある文章をたまに見ることがあるが、これはこれで読みにくい。
技術記事は文芸作品ではないので、やはり論理的な意味の単位で段落をまとめることは重要だ。
段落の目安は、個人的には150～250文字であると考える（もちろん、たまに一文だけの段落を織り交ぜることは、文章のリズムという観点で一定の効果はある）。
当たり前の話。一文が100文字にも200文字にもなっている文章は原則不可。
80文字を越えた時点で、文自体を区切ることを検討するべき。
また、文字数に依らず、そもそも「～であるが」「～で」のようなあいまいな接続助詞が出てきたら、文を区切ることを検討しよう。
たとえば、以下はあるライブラリの特長を説明するための解説である。
・一貫性を持たせる ・少ない実装でより多くのことができる ・さまざまな環境に柔軟に対応する
しかし、これらの説明はあいまいな点が多すぎる。「なにに」一貫性を持たせるのか、「少ない実装で」とはなにを指しているのか、「さまざまな環境」とは？
私なりの理解で修正してみた。
・コーディングスタイルに一貫性を強制できる ・少ないコードで高度な機能を実現できる ・クロスブラウザな環境に対応する
聞きなれないキーワードを読者は極度に恐れるもの。
特に氾濫している3文字略語（アクロニム）には上級者でさえ理解していないものも多い。
3文字略語には、必ず初出時に省略しないフル表記を添えるべきであるし、可能であるならば、日本語での表記も添えるとなお好ましい（よく分からない単語でも日本語であれば、なんとなく想像できるものも多い）。
ただし、SQLやJDBCなど、近頃は一見してアクロニムなのに、なにかの略語でないような単語も増えてきているので、要注意。
たとえば、インタラクティヴ、ドラスティック、リッチ、セキュア、ヘビーなどなど…和製英語は意味があいまいでも、なんとなく許されてしまうような雰囲気があるので、やや危険。
利用にあたって本来の意味を確認するのはもちろん、まずは、日本語で置き換えられないかを検討されたい。
＃もちろん、慣例的に日本語よりもしっくり来る和製英語もあるので、すべてがすべてというわけではない。
英語表記はなんとなくカッコよく見えてしまうため、そのまま使ってしまうのだが、原則としては、避けるべきだ。
たとえば、
Controllerはフロントコントローラから処理を受け取る。
のような表現。
このControllerが、具体的なControllerというクラスの名前であるのか、それともModel－View－Controllerモデルの中で言うところののコントローラであるのかがあいまいである。
もしかしたら両方の意味があるのかもしれないが、指している対象があいまいになるもとでもあるし、あえて固有名詞を意図していないならば、
コントローラはフロントコントローラから処理を受け取る。
のように、日本語で表記するべきである。
ログインコントロール、Loginコントロールのように一見して音も同じであり、サフィックスも同じような言葉もある。
そのようなケースでは、以下のように表記をきちんと定義してから利用するようにするとなお良い。
本稿では、ユーザの認証や操作に関わるコントロールを総称して 「ログインコントロール」と表記し、いわゆるログインページを 提供する「Loginコントロール」とは区別するものとします。
Pageクラス、Pageディレクレィブ、Page要素…プログラミングに関わる解説には、多くの、しかも同名の要素が似たような状況で絡み合って登場することが多い。
たとえば、
PageのMasterPageを設定する
という文章をひとつとっても、Pageがなにを指しているのかが曖昧だ。
もちろん、関連するコードと照らし合わせてみれば、それが指しているところは明らかかもしれないが、わざわざ読者にコードと目線を行き来する手間をかけさせるのか。
否、
PageディレクティブのMasterPage属性を設定する
とするだけでも対象が明確になるならば、その手間を惜しむべきではない。
漢字を多用すると、多くの場合、文章は必要以上に小難しく感じられるものだ。
もちろん、表記は出版社によって規則が決まっている場合が多いので、ただひらがなに開けばよいというものではない（ただ、書籍の場合は統一さえされていれば、著者の表記に従うという場合が多い…ように感じる）。
これ、重要。どんなに難しい概念であっても、原稿にする前に、まずは一言で表してみる。要は…ということ、のように。
一言で説明できないものを原稿にすると、だいたい説明が要領を得ず、本質を説明できていないことが多い。心がけてみよう。
「～的」「～するはずだ」「～のようだ」のような記述は読者が不安になるだけ。
著者は読者の唯一の案内役であるのだから、しっかり断定した記述を心がけよう。
もちろん、高圧的な記述――たとえば「当然～」「もう常識であるが」のような記述は、時として読者に不快感を与えるので、これまた気をつけたい。
否定文は多くの場合、文章が回りくどくなる原因。肯定文で書けないかを要検討。
受け身（受動態）も多くの場合には文章を読みにくくする原因なので、できる限り能動態で書けないかを検討する。
何度も文章を修正していると、いつの間にか主語と述語、目的語と述語に対応関係がなくなっていることがある。最終的な推敲が重要なのはもちろんだが、その際に修飾語を最大限取り除き、最低限の「...は...である」の状態にして、意味が通るかを確認してほしい。
＃特に、こうしたことは長い文章で起こりがち。そんな場合は、そもそも文章自体を短くすることを検討すべきだ。
厳密な記述ばかりがベストであるわけではない。
時には、簡略化してイメージをつかませることも重要だ。
もちろん、その場合、どのようにウソをフォローするのかは難しいところ。改めて後述するのか、註で補足するのか、など。
技術記事の記述にあたって、公式ドキュメントなどの一次資料を熟読するのは当然のこと。しかし、記事の流れが、公式ドキュメントの流れそのままというのは絶対に不可（そもそも著作権上も問題だ）。
公式ドキュメントも近頃はずいぶんと噛み砕かれた内容が多くなってきたが、それでも入門者にとって分かりやすいものばかりではない。公式ドキュメントやその他資料の内容を消化して、自分なりの説明の流れや構成を考えるところに著者の付加価値があるはずだ。
＃ごく当たり前の話なのだが、ここであえて明記しているというのは…推して知るべし。
書籍とは異なり、雑誌のように限られた紙面ではどうせすべてを書ききることはできない。
極端にページ数の制約が大きいため、時として「この分量では書ききれない」という投げやりな発言も出がちであるが、雑誌と書籍とではそもそも書き方が異なる。
書籍以上になにがポイントであるかを絞り込む過程が重要である。 今一度、どこに重点をおけば、どういう深さで書けば、「書ききれるのか」を検討してみよう。
雑誌では、
＃余談ではあるが、（仮）脱稿段階で極端にページ数が膨らんだ原稿を提出するのは厳禁。分量調整によって、内容は大きく変動するし、前後関係も変わってくる。結局、原稿の行き来が増えるだけであるからだ。そもそも分量調整に作業時間の大部分がとられてしまい、肝心の内容精査が後手になってしまう。たかが分量、ではない。
媒体を問わず、記事を「もっと短くまとめてください」と指摘することはよくある。
＃書籍や雑誌などの紙媒体であれば、そもそも物理的なページ数の制約があるし、そうした物理的な制約を受けにくいWeb媒体でも無制限に長い記事は好ましくない（そもそも長い記事は読者もしんどいし、現実的な都合として、予算上の問題もあるためだ(^^;）。
そんなときに、意外と多くの人が扱うテーマを減らしてそれで良し、としているようだが、これでは不十分。
もちろん、分量が制限された記事では、扱うテーマを絞り込むことは重要。しかし、それと共に文章の精査は不可欠だ。
同じことを繰り返し説明していないか、そもそもこの文章は冗長ではないか、こことあそこはまとめられないか、など、かならず文章そのものとしての精査を心がけられたい。
＃もちろん、この点は分量の制約に関わらない話ではある。
「後述」「後から述べるように」などは多用にすべきでない。 説明の都合上、やむを得ない場合もある。しかし、「後述」があまりに頻出している場合は、そもそも説明の順序を検討すべきだ。 基本は、先頭から順序だって読んでいけば理解できるような解説が理想。
「本書では扱わないが...」についも同様。そもそも扱わないということだけを言うだけであれば、解説の中に入れても意味がないし、説明を散漫になるだけ。どうしても書きたい場合には、最低限、参考文献を明示するなど、読者の次の指標となる内容にすべき。
ただし、参考文献についても分量があるのであれば、記事末、巻末にまとめるなど、別だしするのが望ましい。
