Weasel words・受動態・重複語を見つけるシェルスクリプト3本
(matt.might.net)- 技術文書で繰り返し現れる弱点は、人が毎回指摘するよりも、まず自動化されたチェックで可視化できる。この記事では LaTeX 論文のビルドに組み込めるシェルスクリプト3本を紹介する
- 目的は受動態や特定の表現を禁止することではなく、指摘された文を見ながらより明確で正確な表現を選べるようにすることにある
various,quite,surprisingly,very,extremelyのような weasel words は精密さを損なうため、正規表現で検出して見直し箇所を絞り込める- 受動態チェックは be動詞の後ろにある
-ed形や不規則分詞を探し、重複語チェックは隣接する同一単語を大文字小文字を無視して見つけ出す make proofで3つのチェックをまとめれば、論文リポジトリ内で繰り返し実行でき、小さなミスの蓄積によって推敲不足と受け取られるのを減らせる
繰り返される文章上の弱点を自動化で減らす
- Ph.D. 学生の指導で特に難しいのは文章指導であり、繰り返し現れる問題はまずツールで拾い上げられる
- スクリプトが狙う3つの問題は次のとおり
- 受動態の多用
- weasel words
- lexical illusion、つまり目で見落としやすい重複語
- これらのスクリプトは LaTeX 文書のビルドシステムに統合して使う
- 文章ルールには例外があるため、目的は特定の文法構造を禁止することではない
- 文が強調表示されることで、「もっと明確で精密な表現はないか」を自分で確認するようになる
- プログラマなら自分の繰り返しがちな弱点を把握し、その弱点を減らすために自動化を活用できる
技術文書で参考になる本
- The Elements of Style は完璧ではないが、スタイルの参考書として今でも有用
- 言語学の専門家による 批判 を踏まえて読む必要がある
- 科学・工学・数学の文章では、スタイルの欠如が露骨に現れることがある
- Style: The Basics of Clarity and Grace は Zachary Tatlock が勧め、その後 Strunk and White より優れた参考書と評価された
- 1冊だけ選ぶならこの本を選ぶ価値がある
- The Chicago Manual of Style はスタイル論争を終わらせる基準として使われる
- A Manual for Writers of Research Papers, Theses, and Dissertations は技術文書向けの Chicago マニュアルに相当する
精密さと明確さが失われるポイント
- Olin Shivers は技術文書を精密さ・明確さ・マーケティングのバランスとして教えていた
- 論文投稿の過程を通じて、精密さと明確さが機械的に識別できる形で弱まるポイントが見えてきた
- weasel words
- 受動態の多用
- 科学的アイデアの下手なマーケティングまで見つけるシェルスクリプトを作るのは難しい
Weasel words の検出
- Weasel words は見栄えはよいが情報をほとんど伝えない単語や句で、文の精密さを曖昧にする
- 学生の文章でよく見られる weasel words は3種類に分けられる
-
Salt and pepper words
- 新しい大学院生は文に調味料のように技術的に見える単語を振りかけるが、実際には情報を伝えていないことがある
- 代表例は
various,a number of,fairly,quite - こうした単語を削ると文はより強くなる
It is quite difficult to find untainted samples.→It is difficult to find untainted samples.We used various methods to isolate four samples.→We isolated four samples.
-
Beholder words
- Beholder words は、意味が読者によって変わる単語である
- 例として
interestingly,surprisingly,remarkably,clearlyがある - ピアレビューアは、判断を代わりに下してくれる表現を好まない
False positives were surprisingly low.よりもTo our surprise, false positives were low (3%).のように数値と観察主体を示すほうがよい
-
Lazy words と副詞
- Lazy words は定量的な性質を示さずに済ませるための単語で、科学を堅固ではなく未完成に見せてしまう
- 最悪の例は
veryとextremelyで、技術文書ではほぼ許容しがたい - ほかの例として
several,exceedingly,many,most,few,vastがある - 技術文書では副詞が weasel words のように見えがちである
- 新しい大学院生の技術文書では、すべての副詞を取り除いても正味の効果はプラスになる可能性が高い
We offer a completely different formulation of CFA.よりWe offer a different formulation of CFA.のほうがよい
-
Weasel words スクリプト
- Bash スクリプトは基本の weasel words 一覧を正規表現で定義し、入力ファイル内の位置を
egrep -i -n --colorで表示する - 既定の一覧が合わなければ、代替の一覧ファイルを使える
$HOME/etc/words/weasels$WORDSDIR/weaselswords/weasels
- 引数がなければ
usage: <script> <file> ...形式の使い方を表示する
- Bash スクリプトは基本の weasel words 一覧を正規表現で定義し、入力ファイル内の位置を
受動態を意識的に扱う
- 技術文書において受動態が常に悪いわけではない
- ただし、これまで編集してきた技術文書の半分以上は、受動態を減らすだけで改善できた
- 学生は受動態を上手に使うというより、使いすぎることのほうが多い
- 問題となる受動態は、関連情報や説明情報を隠してしまう場合である
Termination is guaranteed on any input.は関連情報を隠しているTermination is guaranteed on any input by a finite state-space.は関連情報を入れているが、強調の置き方がずれているA finite state-space guarantees termination on any input.は関連情報を含み、より明快である
- 主語が本当に重要でないときは、受動態のほうがよいこともある
4 mL HCl were added to the solution.- ただし
We added 4 mL HCl to the solution.も深刻な問題だとは見なさない
-
受動態を判断するための問い
- スクリプトが受動態を示したら、次の2点を確認する
- 行為者が重要なのに不明確になっていないか
- 能動態に直すと文章がより読みやすくなるか
- どちらも「はい」なら能動態にする
- 最初の問いだけが「はい」なら、行為者を明示する
- スクリプトが受動態を示したら、次の2点を確認する
-
受動態スクリプト
- Bash スクリプトは不規則過去分詞の長い一覧を定義している
am|are|were|being|is|been|was|beの後に空白と\w+edまたは不規則分詞が続くパターンを探すegrep -n -i --colorでファイル名と行番号付きで表示する
重複語と lexical illusion
- 改行が入ると、
the theのような重複語は目で見落としやすい - 改行位置を変えるだけでも、同じ重複がよりはっきり見える
- 単語の重複は電子文書作成の過程で生じる現象で、切り取りと貼り付けの事故のようなものだ
- とりわけ
theでよく起こる - 重複語1つだけで論文が不採択になることはないが、スペルミスや重複語のような小さなミスが積み重なると推敲不足が露呈する
- レビューアは不十分な推敲を、自分たちの時間と注意に対する敬意の欠如と受け取ることがある
-
重複語スクリプト
- Perl スクリプトは隣接する重複語を見つける
- ファイルを行単位で読み、非単語文字を区切りとして分割する
- 空白は飛ばし、句読点に出会ったら直前の単語状態を初期化する
- 現在の単語と直前の単語を小文字化して比較し、同じなら
ファイル名:行番号 単語形式で出力する - 終了コードは見つかった重複数となる
Makefile への統合
- 各論文リポジトリの
bin/ディレクトリにスクリプトのローカルコピーを置く - Makefile に
make proofルールを追加する make proofは*.texファイルを対象に3つのチェックを順に実行するsh bin/weasel *.texsh bin/passive *.texperl bin/dups *.tex
論文マーケティングとピアレビュー
- 大学院生は最初、真実をそのまま全部書けば出版されると考えがちである
- しかし真実であることは多く、上位のピアレビュー venue には技術的に正しい論文もすでに十分に多い
- ピアレビューは、どの「真実」が知る価値があるかを決める役割に近づいている
- この観点では、レビューアは科学コミュニティの最も限られた資源である集合的注意力の守り手である
- 論文をマーケティングするには、自分のアイデアがその資源にアクセスする資格を持つことを説得力をもって示さなければならない
関連ツールと拡張アイデア
- Benjamin Beckwith はこのスクリプトに触発されて、Emacs 向けの "writegood" モードを作った
- John Regehr は
Note that,Notice thatのような不要な句を見つける単純なスクリプトを提案している - 別の人たちは、技術文書で未来時制の使用を見つけるスクリプトを提案している
1件のコメント
Hacker News の意見
論文を書いていた頃、文章改善に役立った資料は Paul R. Halmos の How to Write Mathematics と Donald E. Knuth らの Mathematical Writing だった
明確で正確なコミュニケーションの感覚をつかむには、まず Halmos を読むことが多く、「Bad/Better/OK」という提案は Knuth らの講義ノートで見た議論を思い出させる
3番目の段階としては、提案されているようなリンターが、見落としている部分を拾うのに役立つかもしれない
定義が少しでも関わるテーマについて書く人にとって、こうした資料は必須だと思う
この記事が気に入り、効果的な 博士課程の論文執筆 プロセスについてもっと知りたいなら [1] を見るとよい
実際、コミュニケーション能力を改善したい人なら誰でも見る価値があり、この動画にアクセスするためにお金を払っていたとしても惜しくなかったと思うほどだった
[1] https://youtu.be/vtIzMaLkCaM
有名な phd grind のような資料も含めて
例の多くには同意しにくい
たとえば “It is quite difficult to find untainted samples” を “It is difficult to find untainted samples” に変えると、quite difficult と単なる difficult はかなり違って読める
文が良くなったのではなく、意味が変わったのだ
また “various methods” と書いた事実は、単一の方法ではなかったという情報なのに、2番目の文ではその情報が抜けている
話し言葉では抑揚によって大きく変わり、厳密には「やや難しい」に近いが、多くの場面では「ほぼ不可能だ」のように使われることもある
単語を削ることが間違いだとは思わないが、より具体的な 比較表現 に置き換えるほうが良いと思う
特に技術文書で装飾的な書き方がなぜそれほど嫌われるのか、理解しようとしてみるとよい
論文や設計をたくさん読むと、そうした文体は人生をつらくする
“We isolated four samples using the following methods…” のように書くほうが明確だ
論文が単純な内容を述べるときでさえ読みにくい理由の一つがまさにここにある
誰も好まない硬い 形式的な文体 に固執しながら、微妙だが重要な文脈上の手がかりを抜いてしまっている
こうしたツールをもっと探しているなら vale.sh を確認してみる価値がある
あいまいな単語を避けることを含め、さまざまな文体ガイドラインを追加できる
PR 時点でウェブサイトに対して vale を走らせるために使っている GitHub Action はここにある: https://github.com/FusionAuth/fusionauth-site/blob/main/.git...
設定はここにある: https://github.com/FusionAuth/fusionauth-site/tree/main/conf...
文体を強制するのに役立ったが、おそらく機能を最大限には活用できていない
いま本の第3版とウェブサイトの記事をいくつか編集中なので、便利に使えそうだ
Claude にその Bash スクリプト たちを Web UI に移植させて、コードを直接貼り付けて結果を見られるようにした: https://tools.simonwillison.net/writing-style
Claude との会話ログはここにある: https://gist.github.com/simonw/e9902ed1cbda30f90db8d0d22caa0...
2つ目のパターンマッチングあたりがおかしい
たとえば “It is quite difficult to find untainted samples. We used various methods to isolate four samples.” を入れると、“quite” は “is quite difficult to find untainted samples.” の中で見つかり、“various” は空文字列の中で見つかる
それでも、こういう素早い HTML/JS ツールは気に入っている
Claude に同じ機能を果たす、あるいはそれ以上の プロンプト を自分で書かせることもできる
Bash と Perl はこの種の作業にはダクトテープとチューインガムのような道具で、ひどいものであり、Claude が最も得意とするのはまさにこの分野だ
単に問題を示す代わりに、代替案を比較検討して修正案を提案できるし、偽陽性・偽陰性・パースエラーを生む妙な正規表現の不一致もない
初期の Unix には、似たようなことをする diction と style コマンドがあった
GNU から入手でき、Homebrew にも入っている
https://www.gnu.org/software/diction/
記憶ではそれほど優秀ではなかったし、今回のツール群もおそらく同じくらいの出来だろう
私の分野では、文章の質は重要度が最下位で、講義評価よりも低いくらいでした
明確で簡潔な文を重視はしますが、大学院生なら、特に敵対的な質問の前での発表能力、そして悲しいことに、おべっかの能力を身につけるほうが役に立つ気がします
ええ、苦い経験があります :p
人々は抱えきれないほど追い込まれますが、そのかなりの部分は自分で作り出したものです
実際の利害は頭の中で膨らませたほど大きくなく、人々はあなたに通ってほしいと思っています
分野によって違うでしょうが、査読者が文章の質にあまり言及しないからといって、採択に影響しないという意味ではありません
人をいら立たせると、レビューに書くほど本質的ではないと感じられる形であるほど、むしろ普段なら見逃していた部分にもより批判的になりがちです
これが反証しにくくて満足のいく話ではないことは認めますし、選択的に、悪い文章が穴を覆い隠すために使われることもあり得る点も認めます
「論文をマーケティングするには、著者は自分のアイデアがそのリソースにアクセスする資格があるという説得力のある根拠を示さなければならない」というのは、つまり学術誌が最も重要なアイデアではなく、最もよく売り込まれた論文で埋まるという意味です
著者が言うように、見つけにくい誤字脱字のような表面的な要素も査読者が見つけられるため、決定要因になりがちです
客観性があるふりをやめ、編集者の好みや見解を反映する学術誌を受け入れるべきです
あるいは arxiv のような標準的な場所にすべてを上げればよいのです
PDF をアップロードするのに希少資源はありません
査読者が良い点数や無難な点数を付ければそのまま出版され、論文を酷評すれば編集者が身を乗り出し、著者たちが査読者の不満を十分に反映したかを判断しなければなりません
それでも基準を求める側は、やはり編集者ではなく査読者です
どういうわけか emacs を使わない人には有用です
実行したあとでまた編集する流れは面倒なので、良いワークフローにするのは難しいかもしれません
著者は emacs “writegood” の功績を認めていますが、個人的にいちばん好きな文体取り締まりプラグインは “artbollocks-mode” です
関連記事:
Shell scripts to improve your writing - https://news.ycombinator.com/item?id=13295530 - 2017年1月、コメント55件
Shell scripts to improve your writing, or "My advisor rewrote himself in bash." - https://news.ycombinator.com/item?id=1529166 - 2010年7月、コメント31件