diff --git a/src/components/astro/Markdown.astro b/src/components/astro/Markdown.astro index 45a1af9..06cc79e 100644 --- a/src/components/astro/Markdown.astro +++ b/src/components/astro/Markdown.astro @@ -126,4 +126,15 @@ background-color: var(--color-primary); border-radius: var(--radius-sm); } + + .markdown :global(thead) { + background-color: var(--color-background-gray); + } + + .markdown :global(th), + .markdown :global(td) { + padding: var(--size-spacing-xs); + border: 1px solid var(--color-border); + font-size: var(--text-body-sm-size); + } diff --git a/src/components/react/GlobalNavigation.tsx b/src/components/react/GlobalNavigation.tsx index 6f2ce07..899c3f4 100644 --- a/src/components/react/GlobalNavigation.tsx +++ b/src/components/react/GlobalNavigation.tsx @@ -103,6 +103,11 @@ const GlobalNavigation: FC = ({ currentPath, allComponentPostData }) => { Icons +
  • + + UX Writing + +
    • diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro index 96212b3..687d584 100644 --- a/src/layouts/BaseLayout.astro +++ b/src/layouts/BaseLayout.astro @@ -63,7 +63,7 @@ const description = GitHub Mark - View on GitHub + View on GitHub diff --git a/src/pages/ux-writing/index.mdx b/src/pages/ux-writing/index.mdx new file mode 100644 index 0000000..c95a074 --- /dev/null +++ b/src/pages/ux-writing/index.mdx @@ -0,0 +1,254 @@ +--- +title: 'UXライティングスタイルガイド' +layout: '@layouts/PostLayout.astro' +--- + +これはユビーのユーザー（生活者）に伝わりやすい文章を書くためのガイドラインです。 +ここに書かれていることの一部は、後述の「textlint」を使って簡易的にチェックできます。 + +ユーザーはユビーを利用する中で様々な文章を読む機会があります。 +その文章を読みやすくすることで生活者が医療にかかるハードルを下げたい、という思いからこのガイドラインを作成しました。 +生活者向けに文章を書くときに、このガイドラインを参考にして、読みやすく伝わりやすい文章を書くことを心がけてください。 + +### UXライティングとは + +文章を書く仕事（Writing）はあらゆる業務に存在します。その中でも製品・サービスの利用体験上におけるライティングをUXライティング（User experience writing）とします。 + +## このガイドラインの対象 + +- ユビーの生活者向けプロダクトが対象です。主に、症状検索エンジン「ユビー」に適用することを想定しています。 + - V.1.0ではAIMONスマートフォン問診は対象外です。 + - 技術文書内の表記は対象外です。 +- 日本の義務教育を終了した人が理解できるレベルを目指します。 +- 生活者向けに文章を書く、すべての人を対象にしています。 + +## ライティングのコンセプト + +一般的な、読みやすさを高めるテクニカルライティングの技術をベースにしています。 +それに加え、ユビーらしさを保てるようライティング用のコンセプトを次にまとめました。 +これらは、[Ubieプロダクトデザイン原則](/principles)に基づいて設定しています。 + +--- + +### 理解できる + +簡潔でわかりやすく。生活者が医療にかかるハードルを下げるために、日本語を使う多くの人が理解できるようにしましょう。 + +### 安心できる + +体調が優れない人の負担にならないように。みんなが心地よく受け止められるようにしましょう。 + +### 信頼できる + +医療や健康に関する情報が、的確かつ率直に伝わるようにしましょう。 + +--- + +### 禁止用語／表現 + +ライティングスタイルガイドはあくまで原則です。場合に応じて例外的な表現を選ぶ方が適していることもあります。 + +一方で、**絶対に避けなければいけない表現**もあります。Ubie Corporateの『広報ガイドライン』を参照してください。 + +#### 関連資料 + +- [広報ガイドライン](https://www.notion.so/c25ab3d2a2c349ae99df637b4dd912bd?pvs=21) + +## 言葉の選び方 + +読み手の知識や状況に合った言葉を選ぶと、ユーザーはメッセージを理解しやすくなります。 +ユーザーがユビーを利用するのは、自分や家族の体調が優れないときです。無用にユーザーの負担を増やさないようにしましょう。 + +- 同じ意味でも日常で使う単語を使いましょう。（[**textlint**](#textlintについて)対応） +- 理由や意図を明確にしましょう。 +- 否定的な表現を使わず、肯定文で書きましょう。 + +| Dos | Don'ts | +| :----------------------------------------------------------------------------------------------- | :--------------------------------------------- | +| 病院 | 医療機関 | +| 病気 | 疾患 | +| 近く, 近所 | 近隣 | +| 病歴, かかったことがある病気 | 既往歴 | +| この中にはない | この中に該当なし | +| 「顔が腫れている」という症状から「血管性浮腫」の病気と関連があるので、内科の受診をおすすめします | 内科の受診をおすすめします | +| 病気の特定には医師による診断が必要です。 | 症状チェックだけでは病気の特定は行われません。 | + +## UIのボタンラベルについて + +Buttonコンポーネントのドキュメントを参照してください。 + +## 文の冗長性 + +冗長な文章は読み進める気力を失わせます。 + +長い文章は分割し、1文ずつをシンプルにすることで文章の前後関係読みやすさが向上します。 + +- 1つの文には、1つの事柄について書くようにしましょう。 +- 1文は80文字以内にする。 ※50文字以内を推奨（[**textlint**](#textlintについて)対応） + - あくまで目安です。疾患名や、アルファベット、専門用語が含まれると文字数は長くなりがちです。必ずしも80文字以内におさめる必要はありません。 + - 読みやすさで定評のある「病気のQ&A」では、1文あたり40字以下を目安にしています。 + [コンテンツ作成方針【虎の巻】](https://www.notion.so/eb11e0d0fc5542c79a8fb34982cad5ed?pvs=21) +- 名称や説明が並んで文が長くなるときは、箇条書きにしましょう。 +- ユーザーの心情に寄り添い、時には思いやりが伝わるようにしましょう。 + +| Dos | Don'ts | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| かかったことがある病気を「すべて」選んでください。治療中、治療済みの病気も含みます。 | これまでにかかったことのある病気（現在治療中、治療済みを含む）を【全て】選んでください | +| 病気の種類や程度によって違いはあるものの、基本的には次のような特徴があります。
    ・免疫力が低下して、細菌・ウイルス・真菌(カビ)などの病原体と戦う力が弱まる。
    ・感染症にかかりやすくなったり、あるいは重症化しやすくなる。
    ・普通の人がかからない感染症にかかりやすくったりするようになる。 | 疾患の種類や程度によって違いはあるものの、基本的には、防御機構である免疫力が低下して、細菌・ウイルス・真菌(カビ)などの病原体と戦う力が弱まり、感染症にかかりやすく、あるいは重症化しやすくなったり、普通の人がかからない感染症にかかったりするようになります。 | +| 「お大事にしてください。」「体調はいかがですか？」など、ユーザーの体調を気遣う一言を添える。 | ユビーが伝えたいことだけ一方的に伝える。 | + +## 文法 + +文の作りをシンプルにすることで、より多くのユーザーが素早く理解できるようになります。 + +とくに、語句の係り受けには注意し、複数の解釈が生まれないよう注意しましょう。 + +- 係り受けを明確にする。 +- 堅苦しい表現は避けるが、フレンドリーすぎないように。 +- 煽り表現はNG。「!」「!?」などの感嘆符は使わない。（[**textlint**](#textlintについて)対応） +- 正しい日本語文法を使い、自然な読みやすさを心がける。（[**textlint**](#textlintについて)対応） + +| Do's | Don'ts | +| :------------------------------------------- | :-------------------------------------------- | +| 体調はいかがですか？ | お加減はいかがですか？ ※ちょっと堅い | +| ありがとうございます。, ○○病かも? と思ったら | ありがとうございます！, ○○病かも!? と思ったら | +| 病院で受診をおすすめします。 | 病院の受診をおすすめします。 | + +## 句読点・括弧の使い方 + +句読点や括弧の使い方に一貫性を持たせると、読解のための学習負荷を減らすことができます。 + +- 読点の濫用や、句読点の省略は避けましょう。 ※例外あり + - 見出しやキャッチコピーなど、無駄な改行が発生して読みづらくなるケースは例外です。 + - 症状チェックの質問文やアンケートなどの質問文、選択肢の文末に句点「。」つけません。 + - 箇条書きの要素が文ではなく、単語で構成されている場合は句点「。」をつけません。 +- 感嘆符や疑問符、伸ばし棒は使いません。 +- 【】「」『』など、強調表現の使い方に一貫性を持たせましょう。（[**textlint**](#textlintについて)対応） + +| 記号・符号 | 呼び名 | 意味・役割 | +| :--------- | :----------------- | :------------------------------------------------------------------------- | +| 。 | 句点 | 文の終わりを示す。 | +| 、 | 読点 | 文を区切り、主語や語句の係り受けを明らかにする。同格の語句の並列に使う。 | +| ・ | 中点 | 同格の語句の並列に使う。カタカナ表記の外来語の区切りに使うこともある。 | +| ※ | 米印, アスタリスク | 注や参照の指示、注記、脚注に使う。 | +| : | コロン | 「例：□□」、「機能：△△」のようにして、意味や具体的な内容を示すと気に使う。 | +| 〜 | 波記号 | 範囲を示す。 | +| … | 点線（リーダー） | 文の途中の省略を示す。 | +| （） | 丸括弧 | 直前の内容の説明、補足説明などに使う。 | +| 「」 | かぎ括弧 | 会話の引用、語句の強調などに使う。 | +| 『』 | 二重かぎ括弧 | かぎ括弧の中に、さらにかぎ括弧を入れるときや、書名に使う。 | +| “” | 引用符 | 文章の引用、語句の強調などに使う。 | +| - | ハイフン | 住所番地、電話番号の区切りになどに使う。 | +| ― | ダッシュ | 「東京ー大阪」のように、語句のつなぎに使う。 | +| / | スラッシュ | 半角スラッシュは分数を示す。並記した言葉の区切りには全角スラッシュを使う。 | +| 々 | 繰り返し記号 | 「国々」、「山々」のように、漢字の繰り返しを示す。 | + +※『日本語スタイルガイド 第3版』を参考に、多少アレンジしています。 + +## 漢字／かな／カナ + +漢字とひらがなのバランスや使い分けに気をつけると、抵抗なくスラスラと読みやすい文章になります。 + +- 漢字とひらがなのバランスを、**3:7**くらいになるようにしましょう。 + - ひらがなの割合が多いと、幼稚な印象になります。 + - 漢字の割合が多いと、難解な印象になります。 +- 横書きでは算用数字を使う。漢数字を使いません。（[**textlint**](#textlintについて)対応） +- 読みづらい漢字の病名や専門用語には、できるだけ読み仮名をつけましょう。 +- カタカナの長音符号は省略しません。 +- 外来語の表記は、一般的な慣用表現にしましょう。 +- 「常用漢字表」「公用文作成の要領」にない漢字は使いません。（[**textlint**](#textlintについて)対応） + +| Dos | Don'ts | +| :---------------------------------- | :----------------------------------- | +| 当てはまるものを1つ選んでください。 | 当てはまるものを一つ選んでください。 | +| 膿（うみ）, 瘤（こぶ） | 膿, 瘤 | +| ユーザー, スキャナー, プリンター | ユーザ, スキャナ, プリンタ | +| インタビュー, レビュー | インタヴュー, レヴュー | + +## 敬語 + +敬語は、文章の目的に合わせて使い分けます。 + +### 敬語を使った方がいいケース + +- ユーザーが本来やりたくないのに、やらざるをえない操作が発生するときは敬語を使います。 + - 新規ユーザー登録 + - ヘルプセンター、問い合わせ + - アンケートなど + +### 敬語をあえて使わないケース + +- 基本的にボタン、見出しなどのUIコンポーネントでは原則として敬語を使いません。ユーザーの操作対象のラベルの発言者をユーザーに寄せると、読解がスムーズになります。 + +| Dos | Don'ts | +| :--------------------------------------------- | :----------------------------------------------------------------------------------------- | +| お大事になさってください。 | お大事に。 ※軽すぎ | +| お手数ですが、こちらからお問い合わせください。 | お手数をおかけしますが、こちらからお問い合わせいただけますよう、お願い申し上げます。 ※過剰 | + +## アクセシビリティ + +ユビーはスクリーンリーダーに対応しています。スクリーンリーダーで読み上げられても、ユーザーが理解しやすいようにします。 + +音声のみで情報を取得するユーザーは、視覚的な位置関係を目視で把握できません。 + +スクリーンリーダーは、原則として上から下へ順に読み上げます。場所ではなく、時系列や順序を意識した記述になるように気をつけます。 + +| Dos | Don'ts | +| :----------------------------------- | :----------------------------------------------------- | +| 続けるには「次へ」を選んでください。 | 続けるには下のボタンを選んでください。 | +| 次の症状や病気と関連がある場合 | 以下の症状や病気と関連がある場合 ※どれくらい下方か曖昧 | +| はじめに戻る | 上に戻る | + +## textlintについて + +Slackで `@textlint`とメンションをつけてテキストを投稿すると、文章の簡易チェックができます。（@jimbo が絶賛開発中！） + +性能面の制約上、「[漢字よりもひらがなで表記したほうが読みやすい副詞](https://github.com/ubie-inc/textlint-rule-preset-ubie/blob/main/src/dict/fukushi.yml)」と「[漢字よりもひらがなで表記したほうが読みやすい補助動詞](https://github.com/lostandfound/textlint-rule-ja-hiragana-hojodoushi#list)」のチェックは実行されません + +[textlint-rule-preset-ubie](https://github.com/ubie-inc/textlint-rule-preset-ubie) + +### textlintでチェックできること + +- [Ubieで誤りがちな用語](https://github.com/ubie-inc/textlint-rule-preset-ubie/blob/main/src/dict/prh-ubie.yml) +- [置き換えの検討が必要な表現](https://github.com/ubie-inc/textlint-rule-preset-ubie/blob/main/src/dict/patterns.ts) +- 一般的によくある誤用 +- [漢字よりもひらがなで表記したほうが読みやすい副詞](https://github.com/ubie-inc/textlint-rule-preset-ubie/blob/main/src/dict/fukushi.yml) +- [漢字よりもひらがなで表記したほうが読みやすい補助動詞](https://github.com/lostandfound/textlint-rule-ja-hiragana-hojodoushi#list) +- 「することができる」などの冗長な表現 +- 「〜ないことはない」などの二重否定 +- 「しかし」など、同じ接続詞が連続して出現していないかどうか +- 逆接の接続助詞「が」が、同一文中に複数回出現していないかどうか +- 1つの文中に同じ助詞が連続していないか + - 例：「材料不足で代替素材で製品を作った。」は「で」という助詞が連続している。 +- ら抜き言葉 +- 文体の混在 + - 敬体(ですます調)と、常体(である調) +- 全角と半角アルファベットの混在 +- 不自然なアルファベット +- Mac OS XでPDFやFinderからのコピペで問題となる濁点 +- 同一の単語が間違えて連続していないか + - 入力ミスによる同じ単語が連続している問題を発見する。 +- 一文あたりの文字数（80文字） +- 弱い日本語表現 + - 「〜かもしれない」 + - 「〜と思う」 +- 括弧記号の組み合わせが正しいか +- 常用漢字または人名用漢字であること + +[登録されているtextlintルール](https://github.com/ubie-inc/textlint-rule-preset-ubie#%E7%99%BB%E9%8C%B2%E3%81%95%E3%82%8C%E3%81%A6%E3%81%84%E3%82%8Btextlint%E3%83%AB%E3%83%BC%E3%83%AB) + +## 参考資料 + +### Webサイト + +- [「公用文作成の考え方」について（建議）](https://www.bunka.go.jp/seisaku/bunkashingikai/kokugo/hokoku/93650001_01.html) +- [UXライティングとは | UXライティングガイド](https://upwrite.jp/writing_uxes/) + +### 書籍 + +- [日本語スタイルガイド(第3版)](https://www.amazon.co.jp/dp/4902820102/) +- [UXライティングの教科書 ユーザーの心をひきつけるマイクロコピーの書き方](https://www.amazon.co.jp/dp/4798167339/) + +## ご意見／ご要望 + +ご意見、ご要望などはSlackの [#prj-ux-writing](https://drubie.slack.com/archives/C03R495EXGQ) チャンネルまでお願いします。