文章の書き方について


※上記の広告は60日以上更新のないWIKIに表示されています。更新することで広告が下部へ移動します。

文章の書き方について。

対象読者を明確に

対象読者によってどこまで解説すべきか、どんなキャプチャを見せるべきかは変化する。

話題の大小関係を明確に

最初からいきなり細かな話をしてしまい、全体像が見えない記事は意外と多い。

まずは、テーマの外枠を鳥瞰できる説明を先頭で明示し、これから説明する個々のトピックの位置づけを明確にすること。

その上で、個々のトピック説明を展開していけば、読者は途中で置いていかれても、先頭に戻れば記事の全体像を再確認できる。また、最初に全体が見えているので、個々のトピックも安心して読み進められる。

#これは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属性を設定する

とするだけでも対象が明確になるならば、その手間を惜しむべきではない。

漢字とひらがなのバランスを考えよう

漢字を多用すると、多くの場合、文章は必要以上に小難しく感じられるものだ。

もちろん、表記は出版社によって規則が決まっている場合が多いので、ただひらがなに開けばよいというものではない(ただ、書籍の場合は統一さえされていれば、著者の表記に従うという場合が多い…ように感じる)。

すべての用語を一言で説明できるように

これ、重要。どんなに難しい概念であっても、原稿にする前に、まずは一言で表してみる。要は…ということ、のように。

一言で説明できないものを原稿にすると、だいたい説明が要領を得ず、本質を説明できていないことが多い。心がけてみよう。

曖昧語は避けよう

「~的」「~するはずだ」「~のようだ」のような記述は読者が不安になるだけ。

著者は読者の唯一の案内役であるのだから、しっかり断定した記述を心がけよう。

もちろん、高圧的な記述――たとえば「当然~」「もう常識であるが」のような記述は、時として読者に不快感を与えるので、これまた気をつけたい。

否定や受け身の濫用は避ける

否定文は多くの場合、文章が回りくどくなる原因。肯定文で書けないかを要検討。

  • 少なからずあります → よくあります
  • ないわけでもありません → あります

受け身(受動態)も多くの場合には文章を読みにくくする原因なので、できる限り能動態で書けないかを検討する。

  • 抽象メンバーはabstractキーワードを使用して宣言されます。→~使用して宣言します。

主語と述語の対応関係は明確か

何度も文章を修正していると、いつの間にか主語と述語、目的語と述語に対応関係がなくなっていることがある。最終的な推敲が重要なのはもちろんだが、その際に修飾語を最大限取り除き、最低限の「...は...である」の状態にして、意味が通るかを確認してほしい。

#特に、こうしたことは長い文章で起こりがち。そんな場合は、そもそも文章自体を短くすることを検討すべきだ。

時にはウソも方便

厳密な記述ばかりがベストであるわけではない。

時には、簡略化してイメージをつかませることも重要だ。

もちろん、その場合、どのようにウソをフォローするのかは難しいところ。改めて後述するのか、註で補足するのか、など。

公式ドキュメントはきちんと消化する

技術記事の記述にあたって、公式ドキュメントなどの一次資料を熟読するのは当然のこと。しかし、記事の流れが、公式ドキュメントの流れそのままというのは絶対に不可(そもそも著作権上も問題だ)。

公式ドキュメントも近頃はずいぶんと噛み砕かれた内容が多くなってきたが、それでも入門者にとって分かりやすいものばかりではない。公式ドキュメントやその他資料の内容を消化して、自分なりの説明の流れや構成を考えるところに著者の付加価値があるはずだ。

#ごく当たり前の話なのだが、ここであえて明記しているというのは…推して知るべし。

雑誌ではどうせすべては書ききれない

書籍とは異なり、雑誌のように限られた紙面ではどうせすべてを書ききることはできない。

極端にページ数の制約が大きいため、時として「この分量では書ききれない」という投げやりな発言も出がちであるが、雑誌と書籍とではそもそも書き方が異なる。

書籍以上になにがポイントであるかを絞り込む過程が重要である。 今一度、どこに重点をおけば、どういう深さで書けば、「書ききれるのか」を検討してみよう。

雑誌では、

  • 対象読者を明確にし、
  • 優先順位の高低を早い段階で判断し、
  • ページ数に見合ったポイント整理を行う

ことが書籍以上に重要である。

#余談ではあるが、(仮)脱稿段階で極端にページ数が膨らんだ原稿を提出するのは厳禁。分量調整によって、内容は大きく変動するし、前後関係も変わってくる。結局、原稿の行き来が増えるだけであるからだ。そもそも分量調整に作業時間の大部分がとられてしまい、肝心の内容精査が後手になってしまう。たかが分量、ではない。

記事の分量を調整する場合

媒体を問わず、記事を「もっと短くまとめてください」と指摘することはよくある。

#書籍や雑誌などの紙媒体であれば、そもそも物理的なページ数の制約があるし、そうした物理的な制約を受けにくいWeb媒体でも無制限に長い記事は好ましくない(そもそも長い記事は読者もしんどいし、現実的な都合として、予算上の問題もあるためだ(^^;)。

そんなときに、意外と多くの人が扱うテーマを減らしてそれで良し、としているようだが、これでは不十分。

もちろん、分量が制限された記事では、扱うテーマを絞り込むことは重要。しかし、それと共に文章の精査は不可欠だ。

同じことを繰り返し説明していないか、そもそもこの文章は冗長ではないか、こことあそこはまとめられないか、など、かならず文章そのものとしての精査を心がけられたい。

#もちろん、この点は分量の制約に関わらない話ではある。

後述、本書では扱わないが...には要注意

「後述」「後から述べるように」などは多用にすべきでない。 説明の都合上、やむを得ない場合もある。しかし、「後述」があまりに頻出している場合は、そもそも説明の順序を検討すべきだ。 基本は、先頭から順序だって読んでいけば理解できるような解説が理想。

「本書では扱わないが...」についも同様。そもそも扱わないということだけを言うだけであれば、解説の中に入れても意味がないし、説明を散漫になるだけ。どうしても書きたい場合には、最低限、参考文献を明示するなど、読者の次の指標となる内容にすべき。

ただし、参考文献についても分量があるのであれば、記事末、巻末にまとめるなど、別だしするのが望ましい。

ツールボックス

下から選んでください:

新しいページを作成する
ヘルプ / FAQ もご覧ください。