search
LoginSignup
70
Help us understand the problem. What are the problem?

More than 5 years have passed since last update.

posted at

updated at

Qiitaに投稿する記事の書き方に望むこと

大上段から構えて書いてみました。
寝る前に書いてるポエムだからいいんです(先に謝っておきます すみませんm(_ _)m

他人が見れる記事なのだから他人の目を意識した書き方をしよう

Qiita は(Team は知りませんが)プライベートモードが使えないので、どんな記事を書いても他の人から見られます。しかも Qiita は(意外にも)人気サイトです。 PageRank も高めです。

そのため、自分だけ分かってる文脈で記事を書いたとしても、他の人からは「これは何か一般的なことを言ってるのかも」と勘違いされることがあります。そして「これは役立ちそう」と(勘違いされて)ストックが増えてしまうこともあります。
また、自分のやったことをそのまま書いておくのは、作業履歴としてはいいのですが、行った手順全てを書くと、無駄な部分も含むことが多いです。できれば無駄な部分は削るほうがいいでしょうし、削っておいたほうが(読み返した)自分にも分かりやすくなります。
そして(ここは大きく強調したいのですけど)誤字脱字 にも注意したほうがいいです。必ず読み返しましょう。

記事に誤りが入っていると「こんなことも知らんのか」とツッコミが入ったりします。また、間違いが含まれた記事を見て「人気サイトの Qiita で見かけた内容だから間違いないだろう」などと変な信頼性が付いてしまった状況で学習する人も出てきたりします。ツッコミがあるのはまだマシです。Qiita に間違った記事を載せていると(意外に PageRank が高いので)ググったときに上位にきてしまったりします。間違いの大元が自分の記事 なんてことはあまり嬉しくないですよね。なので、公開するときにはちゃんと検証するようにしましょう。

また 1か月後の自分は他人 とよく言われるように、記事を書いたときには分かっている前提条件も、1か月経ってしまうとすっかり忘れてしまいます。「この記事の前提条件って何だっけ…?」なんてことが生じないよう、未来の自分のために、できるだけ前提条件を記載しておきましょう。

参考記事へのリンクは張っておこう

他で見かけた記事をまるごとコピペしたりすると著作権的に問題があります1 。引用の範囲を超えるほどコピペするならばプライベートなブログにでも貼っておきましょう。
そして、参考にした記事へのリンクを張っておくと、その記事への謝意になります。また、もしも Qiita に書いた自分の記事に勘違いが含まれていたとしても、大元の記事が正しければ、そちらを見て正しく理解してくれることも期待出来ます。場合によっては、誤りをちゃんと指摘してくれる読者も居ます。

記事のスクリプト/プログラムはちゃんと動作するように検証しよう

残念なことに、記事に書いてある内容だけでは動作しない場合があったりします。ちゃんと動作するように検証してから「投稿」ボタンを押しましょう2

Markdown を活用した書き方をしよう

Markdown を使えば、他の人に書いている内容が明確に伝わるようにできます。
ときどき、コードを引用的に使っているひとを見かけます。やはり code はコードとして使ってほしいです3
また、リンクはできればリンク先のタイトルを付記してほしいです。タイトルがあればいちいちリンク先を見にいかなくても内容が分かります。

Markdownの例

# 見出し1
## 見出し2
### 見出し3
#### 見出し4
##### 見出し5
###### 見出し6
`インラインコード`
*斜体*
**強調**

> 引用

- 箇条書き

[リンク](http://qiita.com/)

は↓のようになります。


見出し1

見出し2

見出し3

見出し4

見出し5
見出し6

インラインコード
斜体
強調

引用

  • 箇条書き

リンク


Markdown記法の詳細はこちらをご覧ください。
Qiita - Markdown記法 チートシート - Qiita

などと勢いで書いたら

良い記事を書くためのガイドライン - Qiita:Support
がありました。ひとまず、投稿する前にこれ読みましょうw

具体的で簡潔なタイトルをつける

  • タイトルを見ただけで記事の中身を想像できるように

環境や前提条件を説明する

  • 適切なタグをつける
  • 特定のバージョンについて話をするときは、タグにバージョンを

引用元や参考元へのリンクを書く

  • 文章を引用したらそのページへのリンクを
  • 記事の内容を理解する助けになるページがあればリンクする

著作権に気をつける

  • 著作権で認められた引用の範囲を超えないように

ライセンスや秘密保持契約に気をつける

(Qiita の)利用規約を守る

補足:投稿しっぱなしではなく更新もしよう

Qiita では1年間更新が無いと

この記事は最終更新日から1年以上が経過しています。

と(最近になって)出るようになりました。
継続的に更新してあるとこれが出ないので「ああ、投稿日は古いけど、ちゃんとメンテナンスされてるから今でも役立つ記事なんだな」と記事の信頼度が向上します。
なお、更新した場合には、更新した部分を明記しておくとハッキリして分かりやすいです。

関連記事

ずーっと前に書いた記事(これもポエムタグつけておいたほうがいいかもw)
Qiita - 誤記の指摘はコメント欄じゃなく「編集リクエスト」を使いましょう - Qiita


  1. 実際にコピペのみの記事もあったのです。ネットで見かけた記事のブックマークや書き控えのつもりだったようです。 

  2. もちろん投稿後に気付くことも多いです。誤りに気付いたら、すぐに編集しましょう。 

  3. コード記法をエスケープ記法的に使うこともありますけど、例外的ですね。 

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
What you can do with signing up
70
Help us understand the problem. What are the problem?