技術系の文章を書く際、「ここを気をつけているだけである程度読みやすい文章となる」といったポイントをいくつかご紹介したいと思います。
はじめてQiitaに投稿する人や、そうではないにしても、文章の品質を気にされるかたの助けになればと思います。
文章外のコンテンツ編
サンプルコードはできるだけ豊富に用意しましょう。
Qiita記事は、いわばドキュメントなので、文章が重要であることは当然です。
しかし、わかりやすさで言えば、エンジニアではコマンドやソースコードのほうがわかりやすい場合も多々あります。
不要であればどちらかを読み飛ばすことも可能な上、片方ではしっくりこない人は情報を補完しやすいので、できるだけサンプルコードは豊富に用意しましょう。
サンプルコードが肥大化してきた場合、GitHubにおいてやるのも一つの手かもしれません。
日付は正しく記しておきましょう。
コメントより。
Qiitaのみに投稿する場合はあまり関係ありませんが、いつの時点での情報かはきちんと明記しておきましょう。
特に、技術の変遷が早い分野では、新規で学ぶ人が古い知識を学んでしまうことはマイナスとなることもありますので、きちんといつの情報かははっきりさせておきましょう。
タイムスタンプがある場合はそちらを。ブログシステムを自分で作成している場合などは、忘れずに情報の保管と表示を行いましょう。最終更新日があればなお良いです。
漢字編
「時」,「事」などはその字に合う場合にのみ使いましょう。
Qiitaの記事を読んでいると、
「もしこのインスタンスに記述されているメソッドがpublicであった時」
などの文章を見ることは非常に多いです。
こういった文章を記述するときは、 「時」 の字は ひらがなに置き換え ましょう。
時, 事, 物といったものがそれにあたります。
時は本当の時である場合のみに利用し、 「〜〜というとき」 などでは、ひらがなの 「とき」 を用いましょう。
「◯◯という事は〜」 というシチュエーションでも、 「事」 ではなく、 「こと」 を用いましょう。
「見る」がつく字は、その字に合う場合にのみ使いましょう。
Qiitaの記事を読んでいると、
「Railsを学んだのでWebサービスをつくって見ました」
などの文章を見ることは非常に多いです。
この場合の 「見る」 については、注意が必要です。
この例の場合、 「つくってみた」 のであって、 「つくって」 「みた」 ではないことはおわかりいただけるかと思います。
ざっくり言いますと、その文章の中に明確に 「見る」(watch) 行為を行っていない場合は、 「みる」 を使用しましょう。
にたようなパターンは他にもありますので、実際の動作と漢字に違いがある場合は要注意です。
一度検索して、調べてみることをおすすめします。
わかりにくい漢字は「ひらき」ましょう。
IMEがどんどん賢くなって、何かとすぐ漢字で出てきてしまう世の中になりました。
なので、IMEに任せて文章を書いていると、すぐ漢字だらけの文章となってしまいます。
以下に、IME任せの文章の例を紹介します。
「今回は敢えてメソッドをpublicで定義してみましたが、publicメソッドの場合、外部のどこからでも参照することが出来るので、全てをこのままにしておくと危険です。以下に一例を挙げてみます。」
この文章、全く読めないことはありませんが、惜しいポイントがいくつもあります。
まずはじめに、この文章を書き直した完成形をご紹介します。
「今回はあえてメソッドをpublicで定義してみましたが、publicメソッドの場合、外部のどこからでも参照することができるので、すべてをこのままにしておくと危険です。以下に一例をあげてみます。」
いかがでしょうか？少し読みやすい文章になったかと思います。
何かと漢字で書いてしまいがちですが、漢字よりひらがなの方が数段わかりやすい箇所があることが見て取れるかと思います。
この漢字をひらがなにする行為のことを、 「漢字をひらく」 といいます。
漢字というのは圧縮ファイルです。脳が読む時に自動で展開してくれていますが、はじめから展開しておくと、ファイルサイズは多少増えますが、それだけ展開のコストを割かなくてよくなります。
文章を書く時は、できるだけ不必要な展開コストを読み手に与えないようにしましょう。
技術編
技術の名前は正しく書きましょう
GitHubのことをGit h ubと記述されている人は多くみかけます。
どの言語や分野でもGit及びホスティングサービスとしてGitHubを使うことが多いからこそでしょうが、非常に間違われやすいものになっています。
テクノロジーに関するキーワードはきちんと正しく書きましょう。
例えば、Web系のQiitaですと、代表的な間違いとして以下があげられます。
自身が書くカテゴリに合わせて、技術の名称はきちんと再確認してから書きましょう。
| 誤った名称 | 正しい名称 |
|---|---|
| Github | GitHub |
| javascript/Javascript | JavaScript |
| wordpress/Wordpress | WordPress |
また、技術の名称に変更があった場合、できるだけ自身が利用している側もしくは公式に対応と記載されている側を記述しましょう。
一例に上げると、jade<->`pug`や、`OS X`<->macOSなどです。
何かと勝手が変わっていることもある以上、不測のエラーを防ぐことは重要です。
番外編
タグの表記ゆれには注意しましょう。
Qiita特有の問題ですが、タグの表記ゆれが深刻です。
普段JavaScriptをはじめとした、フロントエンド周りを触ることが多いのですが、その分野では、hogehoge, hogehoge.js, hogehogejsが混在している状況となっています。
できるだけ事前に検索し、件数を調べた上で、最も使われているタグを利用すると良いでしょう。
何か発見がありましたら、以下の記事に編集リクエストを送っていただけると、迷いが減ってより今後の役に立っていくかもしれません。
Qiitaの◯◯.jsタグの表記ゆれと最も使われているタグ一覧 - Qiita
textlintを使ってみましょう。
日本語の校正ツールとして、 azuさんの開発する textlintというツールがあります。
これは、プラガブルな仕組みで、どんどんルールを定義していくことによって、実行対象の文章の問題点を洗い出してくれます。
こちらとそのプラグインを利用することで、表記ゆれや「の」、「が」が一つの文章に複数利用されているパターンなどで警告を出してくれます。
こちらを一度かけることによって、ある程度文章の品質を向上させることが可能なので、機会があれば使ってみるのも良いかもしれません。