324
305

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

Qiitaで技術系の蚘事を曞く時に気を぀けおいるこず

324
Last updated at Posted at 2016-10-22

技術系の文章を曞く際、「ここを気を぀けおいるだけである皋床読みやすい文章ずなる」ずいったポむントをいく぀かご玹介したいず思いたす。
はじめお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ずいうツヌルがありたす。
これは、プラガブルな仕組みで、どんどんルヌルを定矩しおいくこずによっお、実行察象の文章の問題点を掗い出しおくれたす。

こちらずそのプラグむンを利甚するこずで、衚蚘ゆれや「の」、「が」が䞀぀の文章に耇数利甚されおいるパタヌンなどで譊告を出しおくれたす。

こちらを䞀床かけるこずによっお、ある皋床文章の品質を向䞊させるこずが可胜なので、機䌚があれば䜿っおみるのも良いかもしれたせん。

324
305
6

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
324
305

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?