Edited at

Qiita(29) 楽しいQiitaの使い方 壁10罠6つ技7つ


Qiita楽しい

Qiitaってこんなに楽しいとこだったんだ。

自分の苦労や、成果を記録すると、その成果を再利用してもらえる。

Qiitaの使い方のわからないところは、「編集リクエスト」という機能で添削してもらえる。コメントの機能で、書いた技術の内容について教えてもらえる。

followerが増えるし、Contributionも増える。

じゃ、もっといろんな項目書かなきゃってなる。


Qiitaのいいところ

Qiitaのいいところは、自動保存機能。

[C][C++]の国際規格案の例題をコンパイルするときの課題7つ。

https://qiita.com/kaizen_nagoya/items/5f4b155030259497c4de

で紹介しているresearchmapでは、自動保存機能がないだけでなく、接続切れによる入力項目の消失の警告すらない。

https://researchmap.jp/jownvh0ye-1797580/#_1797580

あたかも登録が可能な編集画面になり、「決定」を押すと、せっかく入力した内容が永遠の彼方に消える。

Qiitaでも使い慣れて来るのに1ヶ月くらいかかった。

右も左もわからず、機能も作法もわからず、

ひたすらコンパイルした時のエラーを記録したくって。

Qiitaを始めるに当たって、

検索して再利用するだけでなく、

自分で記事を書き始めるときに、

知っているとよかったこと、

ぶつかった壁

嵌った罠、

乗り越えた技を書き記します。

これらのうち、プログラムで記述できることは、プログラム化したい。


目次(content)

壁1 「ユーザ登録」

壁2 「投稿する」

 原稿を書き始める

タイトル、タグ、本文の入力

   タイトル

壁3 何を書くか、何をタイトルにするか

技1 記録が膨大な場合は、公的なサイトに保存してリンクを貼る

   タグ

壁4 何をタグにするとよいか

   本文

    見出し

    リスト(一覧)

    番号付きリスト(number list)

壁5 リンクの書式

    リンク

    コード

壁6 三連打

罠1 ファイル名、言語指定

    数式

壁7 \

壁8 下書きは10個まで

 スライドモード

 手引き

  Qiitaの手引き

壁9 再利用性と汎用性

 記事の冒頭で前提条件(環境とか使用言語・バージョンとか)を書いておくとわかりやすくて良いらしいです。

 「Humility(謙虚)」、「Respect(尊敬)」、「Trust(信頼)」

罠2 謙虚

技2 全ての条件を確かめてないことは率直に書く。

罠3 書き手視点に陥る。

罠4 なんでもプログラムになる。でも描くのが後回しに

 投稿の手引き

技3 参考文献を有効に

罠5 画像が大きい

技4 <img width=""を使う

技5 SNS埋め込み

壁10 編集リクエスト、コメントへの返答

技6 訂正

技7 表

罠6 複数のPCで編集中にしていて間違えて古い版を保存

参考文献(reference9

文書履歴(document history)


壁1 「ユーザ登録」

どんなシステムでもユーザ登録は面倒。

どういうIDにするか、どういうパスワードにするか。

自分のいつものIDを他の人が使っていれば、違うのにするしかない。

qiita0.png

Qiitaは、

Github http://www.github.com

Twitter http://twitter.com

Google https://plus.google.com

のいずれかのIDがあれば、そのIDとの連携で済ませる場合もあります。

あとで、それらと連携する設定をするのであれば、最初からその IDで登録するという手もあるかと。

例えば、Githubで設定するのなら、

□ 私はロボットではありません。

の□をクリックして、Githubを押す。

qiita01.png

ID, passwordが問題なければ、「Sign in」を押す。


壁2 「投稿する」

書き終わってから「投稿する」段になって押すボタンだと思った。

じゃ、書き始めるボタンはどこだ?となった。


原稿を書き始める

qiita1.png

原稿を書き始めるのはどのボタンを押したらいいかわからなかった。「投稿する」の前に、鉛筆の印がある。多分、編集機能だと思い、恐る恐る押した。

「原稿を書く」、「入力する」、「編集する」など、これから始めることに近い表現にして欲しい。


タイトル、タグ、本文の入力

qiita3.png


タイトル

タイトルは213文字いれても警告が出なかった。

文字絵にするのでない限り、128文字か、64文字上限でもいいかも。


壁3 何を書くか、何をタイトルにするか

stack overflow

https://stackoverflow.com/

のような質問を書いても、あまり答えが返ってこなく、実質自分で答えるという筋書きが面白そう。(現実にもそう発展してきたらしい)

1)自分の失敗、エラー、経験の記録

 うまく行った場合だけでは、条件が少しでも違うと同じにならない。全ての条件は記録できるとは限らない。失敗した時の条件と失敗した内容があれば、回避する方法が見つかるかもしれない。

技1 記録が膨大な場合は、公的なサイトに保存してリンクを貼る

 エラーの記録はqiitaには貼り付けられないほど膨大になる。そこで、

http://researchmap.jp

などの公的なところに記録を貼り、そのURLをこちらに記載すると良い。

商用のサービスのURLを貼ると、商用宣伝(commercial)と勘違いされることがある。

2)自分の成功の記録

 失敗ばかりだと後ろ向きで暗くなってしまう。成功した記録も半分あると楽しい。ハードウェアの制約条件、OS,言語の名称と版、それ以外の設定と手順は記録しよう。

3)参考文献・URL

 制約条件が書ききれない場合、類似の事例、異なる事例の参考文献をあげると良い。

内容を書き終わったら、最後に題(title)が何が受けるか考えてみよう。

これまで一番受けたのは、dockerネタ

Dockerをどっかーらどうやって使えばいいんでしょう。TOPPERS/FMP on RaspberryPi with Macintosh編 5つの関門

https://qiita.com/kaizen_nagoya/items/9c46c6da8ceb64d2d7af

Dockerどっかー使い方おかしかったんでしょうか。TOPPERS/SSP on RaspberryPi with Macintosh編:9つの関門

https://qiita.com/kaizen_nagoya/items/cbf40186ae4da48ec4c7


タグ

1つから5つタグを入れる。

タグを入れないと登録できない。

タグが思いつかなければ、ひとまず「下書き保存する」


壁4 何をタグにするとよいか

最初は、論文などの鍵語(key word)に記載するなるべく唯一の言葉を選んだ。そうすると、書いた事項の統計が、「その他」ばかりが目立つ。

これはまずいと思い、なるべくOS, 言語などを陽に入れるようにした。


本文


見出し

シャープ(#)記号で始まるのが見出し。

見出しの数に応じて、文字が小さく、右の目次で下に位置付けられる。


リスト(一覧)

改行のついた文字列が一覧(list)になる。

例えばこんな感じ。


番号付きリスト(number list)


  1. 番号で始まるのが番号付き一覧(list)である。

  2. 例えばこんな感じ。


壁5 リンクの書式

リンクは、プログラムやマニュアルを作成する際に、直接コピペしたい。そのリンクを開いて、接続を確認してからが王道だということは理解できる。しかし、ネットに接続できない場所での作業をすることがあることから、作業の最後に、まとめて接続試験をする習慣がある。

httpで始まり、://で続く文字列がURLとして認識してもらえる。

https://qiita.com/kaizen_nagoya/items/1950c5810fb5c0b07be4

これ便利。読書メーターなどでもこの方式。


リンク

四角括弧 リンク 四角括弧閉じ 丸括弧 httpで始まるURL 丸括弧閉じ

リンク

これは完全に誤解していた。最初は、

[リンク] https://qiita.com/kaizen_nagoya/items/1950c5810fb5c0b07be4

とした。

助言をいただいた。

プログラミング言語教育のXYZ

これわかりにくい。

プログラミング言語教育のXYZ: https://qiita.com/kaizen_nagoya/items/1950c5810fb5c0b07be4

の方がわかりやすい。陽にURLを表示したい場合の方が多い。

プログラムを作ったり、マニュアルを作るとき陽にURLの表示がないと二度手間。きっとマクロを作ればいいのだろう。


コード

一行改行だけの行の次に「```」で始まるのがコード。

コマンドとその出力に使ってもいいらしい。

コマンドも、インタプリタのコードという理解でいいだろう。

1) コンパイラのソース

2) インタプリタのソース(単体の命令を含む)

3) プログラムの入出力とエラー(画面を含む)


壁6 三連打

「```」の前に文字をついついいれたり、「```」と打ったらつもりが「``@」「``」になっていることがしばしばある。ピリオド、中黒以外を3連打する習慣がない。


罠1 ファイル名、言語指定

「```」の後ろにファイル名を入れたつもりなのに表示がない。なぜなんだろうと思ったら、言語指定と解釈されたようだった。

ちょけねこ たんじょうびのおくりもの 

https://qiita.com/kaizen_nagoya/items/fc9675686c229f7a155e

で「```」だと

if ( 0 == x || NULL == x) {

exception(x)
} else {
function(x)
}

「```c」としたらこんな感じ。

if ( 0 == x || NULL == x) {

exception(x)
} else {
function(x)
}

編集指摘をいただいた。


hazop.c

#include <stdio.h>

void exception(int);
void function(int);
int main(){
int x;
int A;

includeの色が変わらないのはやや不満。


数式

Qiitaで嬉しかったのは

\LaTeX

入力できることだ。

改行だけの行の次に「```math」として、

\TeX

入力をすると、あららそこだけが

\TeX

の世界。

上記は

```math

\TeX

```

と入力している。

こういう便利な世界は大好き。

http://researchmap.jp

でも入力できるが、別窓が開き、さらにその枠が小さく、全部を一度に表示してくれない。一旦、表示して見てから、直すという手間がかかる。Qiitaの方が断然便利。


壁7 \

今使っている環境(macOS Sierra 10.12l6 & Safari 11.0.1) では¥を押して変換しても\になってくれない。泣)


壁8 下書きは10個まで

便利だ便利だと思って書ききすすむ。時間の都合で半分書きのものが多くなった。最初は「下書き」を知らず、途中のものも投稿してしまっていた。ごめんなさい。

調子よく、下書きが溜まっていく。「投稿する」を押してもうんともすんとも言わない。画面の左下の方に、ひっそりと

qiita5.png

え、っとなって、調べると下書きで登録できるのは10個まで。ああ、もう10個貯まってた。確かに。


スライドモード

毎週報告会をやっている。原則スライドでと言っていた。

自分はQiitaへの掲載を優先していて、スライドを作成していなかった。

これはまずいと思っていたところに、Qiitaにスライドモードがあることを知った。

スライドモード

https://qiita.com/Qiita/items/4ff5873776992f0511d6

あざっす。


手引き


Qiitaの手引き

https://help.qiita.com/ja/articles/qiita-community-guideline


壁9 再利用性と汎用性

再利用性が高いのは出現頻度が高い事項であり、汎用性とは一致しない。

100年の間に一度しか使わない事項は、自分が生きている限り一度しか使わない。これは時間的に、再利用性が高いとは言わない。

汎用性も再利用性を高めるものではない場合がある。具体的な事項が、ばらけていれば、汎用的な記述は、規則を記述するMetaな記述ではあるが、それを直接再利用するとは限らない。

Qiitaの記事を自動生成する場合には使うかもしれない。


「Humility(謙虚)」、「Respect(尊敬)」、「Trust(信頼)」

順番は

信頼(Trust)でき、尊敬(Respect)するから謙虚(Humility)になれると思っている。できれば、順番を変えて欲しい。


罠1 謙虚

これ謙虚じゃないや。

この順番が良いという確率を示してもらえないと信頼できない。

データを示さずに言明する姿勢は尊敬できない。

そういう事象に何度もぶつかると謙虚になれない。

だから、Qiitaを使うからには、謙虚が先じゃないと駄目なんだろう。


前提条件(環境とか使用言語・バージョンとか)

記事の冒頭で書いておくとわかりやすくて良いらしいです。

大賛成。初めて意見を書いたのもこの趣旨でした。


技2 全ての条件を確かめてないことは率直に書く。

物事を断定的に書くのではなく、自分の経験が限られていることを率直に、制約条件として書き下そう。

実は、私Qiita投稿始めて2ヶ月。なるべく、プログラム例を示そうとしています。


罠2 書き手視点に陥る。

どうしても書き手視点になってしまいます。特に、記録を重視している段階では。その記録を元に、分析していく段階で、読み手を意識するようにしています。

「読み手にとって適切な表現を心がけよう」

そうなんです。「いいね」を押してくださった方が、あの人ならきっとこういう指摘をするよね、っていうことを中心に書き直しています。いいねを押していただければ、押していただくほど、記事良くなります。

いいねがついたから、このままでいいとは思いません。いいねが多くつくものほど、詳しく記述するという行動規範で行動しています。


罠3 なんでもプログラムになる。でも描くのが後回しに

「プログラマーが興味を持つものではなく、プログラミングに関する記事を投稿しましょう。」

プログラマが興味を持ったら、そのプログラムを書きたくなるというのが行動規範です。そのため、興味を持ったら、どういうプログラムを書くかまで記述する予定です。書きかけの記事があるのはごめんなさい。

その項目も、プログラムを書きます。

今の所Qiita用のプログラムは

1)リンク

2)索引作成

3)機械翻訳(して stack overflowに流す)

4)要約を作る

を想定しています。すでに開発済みのものがあれば、お知らせ下さい。


投稿の手引き

https://help.qiita.com/ja/articles/qiita-article-guideline


技3 参考文献を有効に

参考文献には次のような色々な視点で情報提供すると良い。

自分の表現が稚拙だったり、専門分野、OS、言語が違うために誤解を与えたとしても、参考文献を見れば、その誤解が解けるようなものが良い。

1) 引用した書籍・雑誌・URL

2) 考え方を学んだ書籍・雑誌・URL

3) 自分とは違う条件の例

4) 基礎的な項目の説明のあるもの(自分ではそれをいちいち説明するのが面倒なことを、わかりやすく書いているとこ)

5) 反例または反面教師


罠4 画像が大きい

「ゼロから作るDeep Learning 2自然言語処理編」を読む前に読んで置くとよい資料とプログラム

https://qiita.com/kaizen_nagoya/items/537b1810265bbbc70e73

で、画像をあげて「Qiitaに投稿」したら、本やソフトの表紙がすごく大きい表示になって慌てた。

画像を上げると、適当な大きさに調整する機能が既定値ではないらしい。上げてびっくり。


技4 <img width=""を使う

Qiita 画像の大きさ調整

https://qiita.com/kaizen_nagoya/items/cef6ae1fcbdbec9e7be2


技5 SNS埋め込み

Codepenの



Twitter

の2つの埋め込みが有効とのこと。地道な努力が改良を推める手本。

Qiitaに何が埋め込められるか

https://qiita.com/i-ryo/items/865113a1c4876a024b9e


壁10 編集リクエスト、コメントへの返答

当方が、まだ技を一つも身につけていなかった頃は、

タグのつけ方、ここで紹介する技などを編集リクエストでいただきました。

問題は、編集リクエストへの返答の仕方。

編集リクエストが、そのままでいい場合は、自分の返事はどうかけばいいかわかりませんでした。編集リクエストが受け入れられたという案内は行くみたいなので、それでいいと言えばそれでいいのかもしれません。

自分では、編集履歴の項目を作って、そこに記載するようにしています。

コメントをいただいて記載を変える場合にも、編集履歴に記載するようにしています。

直した後で読むと、コメントの意味がわからなくなってしまう場合に、訂正機能を使うようにしています。


技6 訂正

~~原文~~

訂正文

とすると

原文

訂正文

となります。


技7表

\TeX

が使えた時点で気がつくべきだった。

| 表 | 列1 |列2 |列3|

|:---|:---|:---|:---||
|行1| | | |
|行2| | | |
|行3| | | |


列1
列2
列3

行1

行2

行3

この書式は空行が必要ないのか。


罠6 複数のPCで編集中にしていて間違えて古い版を保存

自宅、仕事場、出張で利用する3台のコンピュータを利用している。

そのほか、研修、試験で利用するコンピュータが25台ある。

普段は1台のコンピュータで作業をしているが、自宅、仕事場で出張先でやった仕事を移行していると2台、同時に窓を開くことがある。

Qiitaを編集画面を開いていることを忘れたままで、別のコンピュータで開いて作業して保存し、少し後でもう一台の編集画面を保存すると、一世代前の版に上書きしてしまう。

最初に開いた編集画面で少しでも追加削除などしていれば、別のコンピュータで開いた画面で「編集を続ける」と出る。他で編集途中のものがあることが分かる。しかし、そちらを閉じずに、作業をしているとこの事態に遭遇することになる。

版管理ソフトで、一つ前に戻す機能があると嬉しい。

過去に、これでやらかして、大事な資料を復元できていないものに次の2つがある。内容が不可思議な理由かもしれない。

名古屋のIoTは名古屋のOSで(TOPPERS まとめ)

https://qiita.com/kaizen_nagoya/items/9026c049cb0309b9d451

インド、インドネシアとJava、Javascript:接尾辞がついて別物と言うが共通点は多い。

https://qiita.com/kaizen_nagoya/items/2c331ff6654d41d5e157


参考文献(reference9

Qiita のこと

https://qiita.com/qt6hy/items/ab16499e1ef114085b71

Qiitaで記事を投稿するまでに必要な事

https://qiita.com/kanineshi/items/1204d4a4f6342c144117

Qiitaへ投稿するために調べたこと

https://qiita.com/gricoRodriguez/items/64834746c89df5a1f62c

QiitaのMarkdown確認

https://qiita.com/isi/items/cbeb5b1a5eaa29170179


自己資料(self reference)

docker hub とQiita

https://qiita.com/kaizen_nagoya/items/798358bba382d693e391

今年のQiita記事の目標

https://qiita.com/kaizen_nagoya/items/33988e811b174e443bfa

2019年に入ってからのQiita記事の書き方

https://qiita.com/kaizen_nagoya/items/1786ed40dc5c73ed8b46

Qiita記事の最近の書き始め例

https://qiita.com/kaizen_nagoya/items/c37a680065010b3eab5a

「Qiitaの鉄人」への道

https://qiita.com/kaizen_nagoya/items/2d769dbab2d639d2feb8

Qiita記事 いいね と views の関係

https://qiita.com/kaizen_nagoya/items/d30240b2a9adec288ca9


文書履歴(document history)

ver. 0.10 2018/03/05 初稿

ver. 0.11 2018/03/12 「画像の大きさ」追記

ver. 0.12 2018/03/27 「SNS埋め込み」追記

ver. 0.13 2018/04/01 編集リクエスト・コメントによる訂正技追記

ver. 0.14 2018/04/01 「Qiita楽しい」を見出しに

ver. 0.15 2018/04/01 罠6 複数のPCで編集中にしていて間違えて古い版を保存

ver. 0.16 2018/04/02 技6訂正追記

ver. 0.17 2018/04/03 githubのURL訂正

ver. 0.18 2018/05/05 技7表追記、目次訂正

ver. 0.19 20190228 みだし変更,自己資料追記

http://b.hatena.ne.jp/guide/bbutton

このエントリーをはてなブックマークに追加