prose

散文

このスキルは、投稿記事、分析記事、ケーススタディ、設計メモなどの長文を書き、レビューします。各判断について、解決した問題と、採用しなかった選択肢を、実際に作業した本人の平易な文章で説明します。

事実は正確に、語り口は著者のものに

推測を事実として述べたもの、出典のない主張、著者が説明していない経験は、いずれも毎回指摘対象になります。スタイルのルールは著者の原稿に合わせて調整します。時制と文体はそのままにし、一人称を「私」にするか「私たち」にするかも変えません。

インターフェースのラベル、em dash、三点リーダーは copy に属します。コミットメッセージは ship に属します。

自分の立場から書き始める

最初の段落では、何について書くのかと、著者がどんな立場なのかを述べます。つまり、自分で作った、作り直した、使っている、または気づいたことを示します。その段落の終わりまでに、作品が取り組む問題を示します。作品が何ではないかを一文添えるのも歓迎です。

目次、「この記事では〜を紹介します」という文、機能の案内から書き始めると prose-open-with-context です。

一人称で語る

著者自身が文章に登場します。「私」は本人の作業を、「私たち」はチームの作業を指し、何を作り、試し、見て、取りやめたかを伝えます。誰も書いていないような分析記事は prose-first-person です。

それぞれの判断で、採用しなかった選択肢を示す

選んだものを述べたうえで、少なくとも検討した別の選択肢を一つ挙げ、それを採用しなかった理由を説明します。「ハイライトにはインセットのピルを使います」とだけ述べ、ほかの選択肢に触れないのは prose-show-the-alternatives です。

理由では、その選択が使う人にどんな効果をもたらすかを説明します。「きびきびした印象になります」は prose-reason-for-the-person です。

形容詞ではなく、数値を示す

値がある場合は、その値を書きます。「とても速いスプリング」は prose-specifics です。シームレス、堅牢、強力、驚異的、楽しいといった言葉は prose-no-hype です。

理由は文の中に含める

事実には、その結果も同じ文の中で添え、「そのため」「しかし」「なぜなら」などでつなぎます。理由を次の文に回したり、読者に補わせたりするのは prose-link-the-reason です。

文字数の上限はありません。長さは耳で判断し、二度読まないとわからない文は分割します。強調のために短文や断片的な文を続けるのは prose-no-fragment-runs です。

リストは文の中に入れる

項目が二つから四つのリストは、コロンの後に一文の中で示します。その文の代わりに断片的な項目を並べるのは prose-list-in-the-sentence です。

各項目に説明が必要な場合は、括弧内に補足を加えます。例：間隔（選んだ尺度を一貫して使うこと）、文字（サイズと行の高さを組み合わせて調整すること）。補足を別々の文に分けるのは prose-gloss-in-brackets です。

起きたことを語る

作業の進め方は、著者が過去に行ったこととして語ります。例：「画面を録画し、ゆっくり再生して、録画を見ながら作り直します」。実際に行ったことの説明を伴わない、現在形のアドバイスは prose-tell-what-happened です。

読者に指示するのではなく、作業について語る

作ったものがどう動くか、著者が何をしたかを説明します。デモを試すなど、読者が実際に行動しようとしている場合に限り、読者に「あなた」と呼びかけます。読者への指示が続くのは prose-fewer-you です。

自分の仕事の限界を認める

謝罪はせず、著者自身の仕事が至らない点をさりげなく示します。たとえば、「最初のバージョンはいつも近いところまでできていて、いつも間違っています」。自分の仕事について書きながら限界に触れないのは prose-admit-the-limits です。

「注目すべき点は」「さっそく見ていきましょう」「XだけでなくYも」といった前置きは削除します。これらは prose-no-filler です。

脱線は括弧に入れる

脱線とは、告白、謝辞、冗談など、少しだけ議論から離れる一言です。括弧に入れ、15語未満にし、セクション内で一度までにします。リスト項目の補足説明は脱線ではありません。

議論の筋を担う脱線、または同じセクションに二つ目の脱線がある場合は prose-asides です。

脚注には脱線も出典も書く

脚注には個人的な脱線、つまり但し書き、失敗した試み、数値にまつわる話も記載できます。本筋を中断する但し書きは脚注に移します。本文中に残すのは prose-footnote-the-caveat です。

どのように知ったのかを明記する

各事実について、情報源を示します。調査したのか、測定したのか、原文を読んだのか、引用したのかを明記します。方法を示さずに値を記載すると、prose-say-how-you-know です。

他人の主張には、元の情報へのリンクを脚注で付けます。リンクのない「ナビゲーションが30％速くなった」は、prose-cite-claims です。

推測は推測として示す

推論だとわかる表現にします。「私はこう思います」「おそらく」「私はこう読み取りました」などです。動機を事実として述べると、prose-mark-the-guess です。測定した事実に「私はそう信じています」と付けると、prose-no-hedged-facts です。

著者の経験を決して捏造しない

他の人に代わって文章を書くときは、本人が語っていないエピソード、感情、試みを加えません。これは、余談、脚注のエピソード、起きたことの説明、認めた限界にも当てはまります。「最初はなぜだろうと思いました」は、prose-no-invented-experience です。実際にあった出来事を尋ねるか、その一文を削除します。

言葉を整え、文体は保つ

著者の草稿のスペル、文法、語順を修正します。著者の文体を自分の文体に書き換えると、prose-keep-the-voice です。

スペルはイギリス式にする

本文ではイギリス式のスペルを使います。colour、behaviour、centre、grey、favourite、customise、recognise、organise、judgement などです。コード、CSS、API 名、インターフェースのラベル、引用したタイトルは、それぞれのスペルを維持します。文中で「Color」と書くと、prose-british-spelling です。

構造を見える形にする

手順の連続、比較、値の一覧は、リスト、表、図にします。5つのショートカットを段落ひとつに詰め込むと、prose-show-the-shape です。

キャプションには動きを書く

デモや図の下に付けるキャプションでは、そこで起きることを順番に説明します。メニューがボタンから広がり、4フレーム目に影が現れ、6フレーム目にコンテンツが表示される、といった具合です。教訓を述べるキャプションは、prose-caption-the-action です。

控えめに締めくくる

文章の最後の一文には、現時点でできること、次にすること、または著者の気持ちを平易に記します。オチ、格言、見出しの要約で締めくくると、prose-modest-ending です。

ペア

すべてのチェックはペアになっています。問題のある文の隣に、それを置き換える文が並びます。

ルール	問題のある文	置き換え
prose-open-with-context	この記事では、構造、動き、キーについて説明します。	1日に何百回も開くコマンドメニューを作り直しました。これはチュートリアルではありません。分解してわかったことです。
prose-first-person	メニューは、要素を検証してソースを確認しながら作り直されました。	要素を検証し、ソースを確認しながらメニューを作り直しました。
prose-show-the-alternatives	ハイライトは内側に収まるピル状です。	横幅いっぱいの帯は表のように見えます。内側に収まるピル状のハイライトは、手に持つもののように見えます。
prose-reason-for-the-person	これにより、きびきびした動きになります。	リストを変更したのと同じキー入力で、高さも変わります。
prose-specifics	とても速いスプリング	剛性は20000で、約0.1秒で落ち着きます
prose-no-hype	シームレスでパワフルなメニュー	待たされることのないメニュー
prose-link-the-reason	行の高さは固定です。フレームが自分のサイズを測ることはありません。	行の高さは固定なので、フレームが自分のサイズを測る必要はありません。
prose-no-fragment-runs	ページは動きます。ここに留まりたいとは思いません。	ページは動きますが、ここに留まりたいと思う人はいません。
prose-list-in-the-sentence	ずれた余白。拡大するホバー。何も伝えないコピー。	足りないのは細かな点です。ずれた余白、拡大するホバー、そして何も伝えないコピーです。
prose-gloss-in-brackets	表面の下には余白のスケールがあります。誰かがそれを選び、守り続けています。	表面の下には、余白（誰かが選んで守り続けているスケール）と、文字（サイズと行の高さが一緒に調整されているもの）があります。
prose-tell-what-happened	録画してから、録画を見ながら作り直します。	録画してから、見分けがつかなくなるまで録画を見ながら作り直します。
prose-fewer-you	メニューを開きます。広がるのを見ます。角に気づきます。	メニューは、開くために押したボタンの角から広がります。
prose-admit-the-limits	オリジナルと一致すると主張する、自分で作り直したものの解説	私のバージョンが再現しているのは一部だけですが、仕組みを理解するには十分でした。
prose-no-filler	行の高さは46であることに注目してください。	行の高さは46です。
prose-asides	これは、これを作ったチームへの批判ではないことにご注意ください。	(丁寧な仕事をしているチームを批判するものではありません。)
prose-footnote-the-caveat	リストは上部に固定されていますが、最初は中央に配置されていて、そのせいでカードがすべて動いていました。	リストは上部に固定されています。[^1] 中央に配置されていたバージョンについては脚注に記載します
prose-say-how-you-know	スプリングの剛性は20000です。	スプリングの剛性は20000で、コードに記載されている数値です。
prose-cite-claims	ナビゲーションが30%速くなりました。	ナビゲーションが30%速くなりました。[^1] 出典へのリンクを付けます
prose-mark-the-guess	ハイライトのちらつきを防ぐために、こうしたのです。	ハイライトのちらつきを防ぐために、こうしたのだと思います。
prose-no-hedged-facts	行の高さは46だと思います。	行の高さは46です。
prose-no-invented-experience	最初は、なぜバウンスしないのだろうと思いました。	そもそも、なぜバウンスしないのでしょうか？
prose-keep-the-voice	自分でも試してみようかと思いましたをこのプロジェクトでは探求しますに書き換える	自分でも試してみようと思いました
prose-british-spelling	色は中心から薄くなります。	色は中央から薄くなります。
prose-show-the-shape	1つの段落に5つのショートカットを記載	キーマップの表
prose-caption-the-action	2つ目のバージョンには、含まれるものが少なくなっています。	カードからグラデーション、きらめき、登場アニメーションがなくなり、ボタンは押すと反応します。
prose-modest-ending	ツールにとって最高の褒め言葉は、その存在を忘れてもらうことです。	だからこそ、私は静かなソフトウェアに何度も惹かれますし、そんなソフトウェアを作ろうとしています。

報告

重大度。 HIGH は、経験を捏造すること、推測を事実として述べること、出典のない主張です。MEDIUM は、代替案のない決定、数値があるのに形容詞を使うこと、誇張や埋め草です。また、文脈のない書き出し、登場人物がいない分析、語り口を書き換えることも該当します。実行方法の説明がない助言や、制約の説明がない自分の成果も同様です。LOW は、リンクのない理由、断片的な文章、文に分割されたリストや解説、読み手への語りかけが多すぎることです。アメリカ式の綴り、文中の但し書き、誤った挿入句、教訓めいたキャプション、表にすべき文章、オチで終わる文章も該当します。

形式。 根本原因ごとに指摘を1件記載します。

file:line - [rule-id] what is wrong

続いて、Rule | Count | Severity の概要を記載します。HIGH が1件でも残っている場合は Block、それ以外は Approve とします。読んでいないファイルを Approve にしてはいけません。実行できなかったチェックはすべて Not verified と記載します。