わかりやすい文章を書くコツ

この記事は、Progate Path コミュニティ Advent Calendar 2023 の 20 日目の記事です。

シリーズ 2 も公開中ですので、そちらもご覧ください！

はじめに

皆さん、こんにちは。Progate Path チームのコンテンツプランナーの静（しずか）です。

Progate Path はリリースから 1 年以上が経ち、タスクの数も 80 を超えました（2023/12/20現在）。この記事では、Progate Path のコンテンツ制作においてわかりやすい文章を書くために工夫していることを紹介させていただきます。

エンジニアリングに関わりのある人であれば、以下のような文章を書く際に役に立つかもしれません。

  • 仕様書（ドキュメント）
  • ソースコードのコメント
  • レビュー

また、紹介する内容はエンジニアリングに限らず、どんな文章を書く際にも役に立つと思いますので、ぜひ参考にしていただければ幸いです。

※ コンテンツ制作の流れについては、Progate Path コンテンツ制作の話 をご覧ください。

Progate Path のコンテンツ

Progate Path のメインのコンテンツは タスク です。

ユーザーに題材となるコードベースを提供し、そのコードベースを改修することで実務につながる経験を積めるようになっています。

task

また、タスクを進めるために必要な知識を学ぶための 記事 も提供しています。

article

それぞれでコンテンツの趣旨は異なってきますが、どちらも技術文章であることに変わりはないので以下のようなテクニックを利用してより「わかりやすい文章」を書くようにしています。

わかりやすい文章を書くためにしていること

textlint を使う

textlint は文章の文法チェックを行うツールです。プラグインを使って様々な文法チェックを行うことができます。

Progate Path では、以下のプラグインを使っています。

このように textlint のプラグインを使うことで、大まかな文法チェックを自動化することができます。

表現 / 言い回しを統一する

textlint を使えばある程度の文体の統一はできますが、これは文法的な正しさを保つためのものであり、文章の読みやすさを保つためのものではありません。

コンテンツは複数人で分担して作成することが多いので、文章の読みやすさを保つためには表現や言い回しの統一が必要です。この点を意識せずに進めると、製作者ごとに馴染みのある表現（言い回し）を使いがちになり、読みづらい文章になってしまいます。

個人的には以下のような読みやすいドキュメントは共通して、簡単な英語（日本の中学高校英語レベル）で書かれているなと感じます。

日本語に慣れた人が日本語の文章を書くと、意図せず中学日本語レベル（？）を超えた表現を使ってしまうことがあるので、意識して簡単な表現で書くようにしています。例えば以下のような例です。

  • ex: ~ にまつわる -> ~ に関する
  • ex: 堅牢 -> 保守性が高い
  • ex: ~ と導けます -> ~ ことが分かります

この時、表現の日本語レベルの高さを判断するために、頭の中で「英語に翻訳」することがおすすめです。

筆者の英語力は高校で一般的な英語の教育を受けた程度ですが、その程度の英語力でも翻訳できる文章であれば日本語であってもわかりやすいと判断しています。

  • bad: ~ にまつわる -> ???
  • good: ~ に関する -> about ~

英語力によってぶれがあるかもしれませんが、共同で文章を書く場合にはこのような基準を設けておくと会話がスムーズになると思います。

テクニカルライティングの技術を使う

テクニカルライティングの技術を使うことも心がけています。

テクニカルライティングについては特に Google の Technical Writing 資料 を参考にしています。英語の技術文章向けに書かれているので日本語の文章に全てをそのまま使うことはできませんが、重要なポイントは言語を問わず共通しています。

この中でも頻繁に使うテクニックを紹介します。

Words

  • 新出の用語や専門用語は、その意味を必ず説明します
    • 例: リポジトリとは、コミットを保存する場所のことです
  • 用語は一貫して使います
    • 例: リポジトリという用語を使ったら、それ以降はコミットを保存する場所のことはリポジトリと呼びます
  • 代名詞を適切に使います
    • 代名詞とそれが指すものはできるだけ近くに配置します

Short sentences

ソースコードにおいても短いものが好まれるように、文章も短いものが好まれます。

  • 一文には一つの考えや概念のみを含めます
  • 複数の考えや概念を伝えたい場合には、リストにします 
    bad) コミットとは変更履歴の最小単位のことで、コミットを保存する場所をリポジトリと呼びます。
good)
- コミット: 変更履歴の最小単位
- リポジトリ: コミットを保存する場所

Lists and tables

リストは文章を読みやすくするのに効果的です。

リストには大きく分けて以下の 2 つの種類があり、用途に応じて使い分けます。

  • 箇条書き(bulleted lists)
    • 要素同士が同じレベルの場合に使います
  • 番号付きリスト(numbered lists)
    • 要素同士が順序を持つ場合に使います

例えば、静的型付け言語の例としては C や Java、Go などがあります という文章を箇条書きにすると以下のようになります。

静的型付け言語の例としては以下があります。

- C
- Java
- Go

それぞれの要素は同じレベルなので箇条書きが適しています。

一方で、手順などは順序を持つので番号付きリストが適しています。例えば、以下のような文章です。

以下の手順でリモートリポジトリとローカルリポジトリを同期します。

1. ローカルリポジトリとリモートリポジトリを紐づける
2. リモートリポジトリにブランチをプッシュする

リストを使う場合には例にあげたように、「何のリストなのか」を説明した後にリストを書くようにしましょう。

Audience

読み手が誰なのかを明確にしてから文章を書きましょう。

読み手のレベル感の一例として以下のような分類が考えられます。

  • エンジニア
  • 技術系の職業だが、エンジニアリングに携わっていない人
  • 情報系の大学を卒業した人
  • 技術とは関係のない職業の人

想像してもらうとわかりやすいと思いますが、読み手のレベル感によって何を前提知識とするのかが全く変わってきますよね。

文章の読み手が誰なのかを明確にすることで、読み手が知っていることを前提にしたり、知らないことを説明したりすることができます。

おわりに

Progate Path のコンテンツ制作においてわかりやすい文章を書くためにしていることを紹介しました。

ツールを活用する方法とそうでない方法を紹介しましたが、どれもそれほどハードルは高くないので、ぜひ試してみてください！