文章を見直す、って何を見直せばいいのかまとめてみた - 箇条書き・表組み編
前回は単に日本語を連ねた文章のチェック方法についてまとめたが、同僚氏の文章をよくよく見てみると実際にはドキュメント管理ツールの機能を使うことによって論理的でない文章が隠蔽されていることがあることがわかった。
ので、今回はこれらの機能を使って書かれた文章をどの観点でチェックすべきか、について考えてみる。
箇条書き
箇条書きにすると接続詞を飛ばせるので、なんとなく論理的に整っているような気がしてしまう。自分もそうだった。 暗黙的に接続詞を伝えるのは難しいのだが、慣れないうちはそういう機能を使うとそれっぽくなる気がしてついつい使ってしまう。
ので、自分で書いた文章に箇条書きが含まれる場合は以下を行う。
明示的に接続詞をつけて読んでみる
箇条書きの兄弟要素は
- 理由の列挙
- 事例の列挙
であることが多いので、「また、」や「さらに」などの接続詞を使って読んでみる。
- 全文検索エンジンにElasticSearchを使う場合 (または) - 同じくSolrを使う場合
箇条書きの親子要素はより詳細な理由を説明することが多いので、「${親}。なぜなら${子}だから。」と読んでみる。意味が通らなければ直す。またはその項を消す。
- 外部アクセスできる必要がある - サーバーからS3にアクセスしなければいけない
表組み
表も難しい仕組みのひとつ。うっかり行・列の項目設定を間違えるとあっさり泥沼にハマることができる。 表組みを書いた時は以下のことをチェックする。
見出しをつける
表が何を示すのか、1行で述べる。
## S3とcronを採用した場合のメリデメの比較検討 | |メリット |デメリット | |:------|:--------------|:--------------------------------| |S3のhook|リードタイムが少ない|外部からのリクエストを受け付ける口が必要 | |cron |全部Rubyで書ける |実行タイミング次第ではリードタイムが長くなる|
見出しの内容と表組みの行ラベル(S3のhook)・列ラベル(メリット)の設定がズレている場合、言いたいこととズレた表を書いている。 あるいは見出しだけを読んで何の表がつづくのかわからない場合、言いたいことが何なのかまだまとまっていない。
ラベルと具体的な内容をつなげて読んでみる
ラベルをつけて分類するとなんとなく分類できているような気がするが実態が本当にそうかとは全く関係がない。 自分の表が論理的に正しい分類をしているかを調べるためには、見出しと具体的な内容をつなげて日本語にして読んでみる。
- S3のhookのメリットは、リードタイムが少ないことだ。 - cronのデメリットは、実行タイミング次第ではリードタイムが長くなることだ。
読んでいて違和感があれば、書いてある内容がズレているので直す。