Posted at

Qiitaを効率的に使いたい方の為のレジメ(投稿)

More than 1 year has passed since last update.


概要

本記事は特定の個人を誹謗中傷する内容の記事ではありません。利用者全員にとって気持ちよくQiitaを使ってもらうための問題提起をさせていただきます。

この記事をみているということは、少なくとも


  • Qiitaというサイトについて大まかに理解している

  • そしてQiitaを効率的に使いたいと思っている

という条件を満たしていることになります。

そんな皆様の為に、このQiitaを効果的に使うための方法を模索することにしました。

プログラミング学習をはじめて、このQiitaにたどり着くまで

そう日はかからなかったかもしれません。

今やQiitaはプログラミング学習と切っても切り離せない関係にあります。

入門的な内容は中上級者の方が丁寧に解説してくれています。

躓いたエラーは同じ轍を踏んだ方等が記事を残してくれています。

最新の技術は利用した所感をレポートしてくれている人もいるでしょう。

初心者の方の多くが

熟練者とコンタクトを取り、自身にアドバイスをしてくれる人を探しているかもしれません。

そうやってたどり着いたQiitaを正しく有効に活用してくれるように、この記事を作りました。


経緯

まずは私の経歴を。

2018年5月 プログラミング勉強を始める。

同月 Qiitaに初投稿

最もいいねの付いた投稿→"入門書一冊買って写経した程度じゃ身につかない"という意見が腑に落ちた話。

特にQiitaコミュニティに貢献しているとは言えませんが、

記事を投稿する上でQiitaの利用方法を常に模索しています。

そして単純にQiitaが好きです。Tシャツも買ってしまいました。二枚も。

そんな私が、ココ最近思うことがあります。


  • Qiitaの使い方がよくわからずに、先輩方からコメントを貰ってしまっている人がいます。(ここでのコメントは主にネガティヴ的な意味で。)

  • プログラミング界隈特有の"マサカリ"に怯えている人がいるかもしれない…

といった内容です。


→そもそもQiitaの公式ガイドラインを見たか!?

まずはQiitaのサイトが


  • どんなサービスで

  • どんな使い方をしてほしくて


  • どう活用することを推奨しているのか(多分一番重要)

を確認することにしましょう。

おっと、ここでGoogleに「Qiita 使い方」と調べた貴方、ちょっとまって!

Qiitaは公式にドキュメントを示してくれています。

まずはこちら。



コミュニティガイドライン

Qiitaがどんなサービスで、どんな使い方をすればいいかをわかりやすくまとめてくれています。

このガイドラインはいわば、フランクな利用規約のようなモノです。

公式は勿論の事、Qiita利用者が皆で守ろうとする理念が記載されています。

これらを守らなければ利用してはいけないというわけではありません。

でも、Qiitaを利用する私達がQiita公式の掲げるモノに沿った方法に準拠することは当たり前です。


良い記事を書くためのガイドライン

こちらは、主に記事投稿者にとって推奨される事柄がまとめられています。

記事投稿する前に一読しておきましょう。


ここまでの事を踏まえた上で、一度整理します(簡潔にですが。)


  • Qiitaはプログラミングその他技術関連の知見、経験を共有する場。

  • Qiita利用者が守っているマナー、共通意識がある。

さて、ここまではつまらない話だったかもしれませんが、

ここからは楽しい話に入りましょう。

冒頭でも申し上げた通り、Qiitaを訪れる人の殆どが


  • 自らが経験した事を共有したい!

  • 先人の知恵を拝見して学びを得たい!

という気持ちを持っていると思います。

ここでは初級者、中級者に限り(上級者はこんな記事見てないと思うので)、

Qiitaの活用方法を書いてみようと思います。



初心者

まず先に言っておきたいことは、Qiitaは初心者にとって開かれたサービスだと言うことです。

記事投稿に熟練度は関係ありません。

正しいプロセスで記述された記事であれば、Qiitaコミュニティは歓迎してくれます。

間違いや微妙な箇所は上級者によるマサカリや編集リクエストが指摘してくれます。(言葉がきつい人はいますが。)

学習における最強の手段であるアウトプットを行える場としても有用ですし、

ここでのコミュニケーションが学習をより良いものにしてくれます。

ただし気をつけておきたいことは、人に見せるつもりで書く事です。


人に見せる為の記事かどうか見直す

コミュニティガイドラインにも記載されている通り、

Qiitaに投稿された記事は多くの人に見られます

Google検索に引っかかる事もあります。

記事を見る側の人にとってわかりやすい、見やすい記事作りに努めなければなりません。


  • タイトルは的確で具体的ですか?(✗ 「Ruby エラー」 →○ 「○○なケースのNoMethodErrorにつまづいた。」)

  • マークダウン記法で見やすい記事を目指していますか?(ただの平文ではなく見出しや段落、コードスニペット部分など変化をつけている。)

  • 特定の誰かにとって不快な文章を記述していませんか?(例えば「Emacsはゴ○、Vimは至高」など)

特に気をつけてほしいのは一番目ですね。

例で言うと、「Ruby エラー」なんて記事はきっと無限に作れます。

それも内容がどんなものであれエラーに関係すればこのタイトルをつけてしまえます。

さて、特殊なケースのエラーに苦しんでQiitaに助けを求めた貴方は

検索結果一覧にそびえる「Ruby エラー」の記事で内容を推測できますか?

無理です。

そのような名前付けは避けるべきです。

もう一つ気にしてほしいのが、

その記事、ほんとにQiitaがいいの?という内容の記事。

例えば最近良く見るのが「Qiitaはじめました」とか「Railsチュートリアルはじめました」とか「自己紹介」

という内容の記事。

きっと、Qiitaの記事が「相互フォローした相手の記事しか閲覧出来ない」仕様なら、これらの記事が問題視されることはなかったでしょう。

でも、右上の検索ボックスで「Ruby」と検索すれば

本文中にRubyが入っている記事をすべて表示します。

そして蓋を開けてみればRubyはじめました!わからないことだらけですのでお手伝いください!

いいですか?Qiitaはブログじゃありません。

技術的知見を共有しあう場です。

ご自身が勉強した内容を学習メモとしてまとめるのは一向に構いません。(てかそうやってQiitaを使っている人は大勢いる)

でも、そんな人達は実際のコード例を示したり、何故そう考えたのかを順序立てて説明していたり、

記事を見る人にとって有益な情報を提供できるように工夫しています。

しかし、学習メモとして書いている方の中には

ただコードをコピペして、説明もせずに終わりという方が非常に多い。

それでは、ただ見ても有益でないだけではなく、

まともなアウトプットになっていません。

本当に学習したことを身に着けたいのなら、


  • 何故そのようなコードになったのか考える(写経の場合)

  • より良くするための手段を検討する(リファクタリングなり機能追加なり)

  • 自身がどこにどうやって躓いたのか列挙しておく。

という事を書いてみましょう。


駄目な例

題名:Ruby クラス

class Sample

def foo
puts "hello world!"
end
end

obj = Sample.new
obj.foo #=>hello world!!

class クラス名でクラス定義、

クラス名.newでインスタンス生成。(ここまでで終了)


みたいな記事ですね。

言ってしまいますが、このような記事はRuby公式リファレンスにも載っています。

私は公式リファレンス程度の知識は記事にするな!といっているのではないです。

このような例の情報なら、公式リファレンスが見れるすべての人が同じ記事を書けます。

ほぼ同じ内容の記事が乱立しますし、学習メモとして残しておく理由がないです。

技術書のクラス定義のページに付箋を貼っておくか、

公式リファレンスのページをブクマしておくほうがいいです。

そうではなくて、


良い例

題名:Rubyのクラス定義について理解を深める。

Rubyのクラス定義は、基本形で言えば

class Sample

def initialize
puts "hello!"
end
end

Sample.new #=> hello!

のように書きますが、


  • メソッド定義内ではいろいろな組み込みメソッドが使えるのか?

  • 変数定義は行えるのか?

等の疑問が残った為検証します。

実行環境は、

Ruby:2.5.1

Windows10 Pro

です。(以下検証が続く)


のようにした方が見ている側にとっても、書く側にとっても有益です。

見ている側のメリット


  • 実行環境が書いてあるので、環境の違いによって結果に差が出るのかどうかがわかる。(原因の切り分け)

  • 説明文が記載されているので、著者が何を考えながら進めているのかわかりやすい。

  • 検証は著者自身が考えて行っているので、技術書には載っていない"生の疑問"を見ることが出来る。

書く側のメリット


  • 記事を書く上で検証することで、理解が数十倍も深まる。

  • 見返した時に各コードの意図が把握しやすい

どう書けば良いかわからない人は、

沢山のいいね、ストックを貰っている記事を参考にしてみてください。

相応にして、見やすくわかりやすい記事作りが徹底されているはずです。



中級者

ここでいう中級者とは、プログラミング中級者の事です。

中級者の方はご自身や他の記事の知識に対して

ある程度正誤を判断することが出来ると思います。

そんな方に気をつけてほしいのは…


伝え方に語弊が無いか

ということですね。

これに関しては実例が難しいのですが、

要は文章の作り方を気をつけてほしいということです。

Qiitaはユーザーのプロフィール画面から、

その人が初心者か否かはある程度判断できます

GithubやTwitterと連携していればなおさら。

つまり、自分がある程度その分野に明るい人間と見られていることを意識する必要があります。

更に言えば、

初心者は貴方の記事を参考にして行動する可能性がある

ということです。

これはつまり伝え方を意識しないと正しく伝わらないということですね。


情報が別リソースからの流用になっていないか

これは一番気にしなければ一番ポイントかもしれません。

Qiitaという特性上、殆どが

誰かが使っていた、紹介していた知識を試してみた記事になりますが(それは勿論良い)

その知識を記述する上で

記事のすべてが「~~らしいですよ?」とかける記事はあまりよくない。

例えばAWSの○○というサービスが✗✗の用途においてすぐれているらしい

という情報を元に記事を書くなら、

でも自分で使ったことはないからメリットが実感出来ないなぁ、

自分で使って見るか!
(AWSは従量課金制なので記事の為に使う人はいないだろうけどw)

AWSというのははじめて使ったけど、他にはどんな物があるのだろう?

そしてそれらの使用感も知ることが出来たら自身の知識につながるのでは?
など

元々記事を書き始めたテーマから、

自分の発想力と行動力で独自に知識を進めていく。

これは見る人のメリットもそうなんですが、

書く人にとって圧倒的なステータスになると思います。


如何だったでしょうか…?

プログラミングの記事を投稿するサイトと一口に言っては簡単ですが、

その利用方法を考えることで、自身のメリットを何倍にも増やすことが出来ます。

是非一度検討してみてくださいね。