Share
Embed
研究室コミュニケーションにおけるボトムアップなドキュメンテーション
チームにおけるドキュメンテーションをうまく機能させる方法について、研究室においての実践を例に説明します。
今回のプレゼンテーションで説明する方法は
- Scrapboxを推奨すること
- 組織のメンバーの一人一人から、ボトムアップ的にドキュメンテーションが作成されることを目指すこと
- 筆者の研究室において実践例が存在すること
を特徴としています。
Skipjack
June 09, 2024
Transcript
60 slides
-
おことわり • この発表は自分が所属している研究室におけるドキュメンテーションに対するあれこれの試行錯誤、 事例紹介がメインです。 • したがって、研究室特有の事例が多く存在します。他の研究分野だとそうじゃないかも…ということ は当然ありえます。 • 以下に自分の研究分野/研究室のバックグラウンドを明記しておきます。 •
理学部。 • 対象は地球周辺の宇宙がメイン。地球周辺の宇宙は衛星データ/レーダ観測データとシミュレーションの2本 立てで進むことが多いです。実験はマイノリティ。 • 自分の研究室はシミュレーション研究、衛星データ解析が多い。すなわち、研究の大半はパソコンと向き合う デスクワーク。 • 国公立大学の研究室(講座)。したがって学部生の数は少なめ、かつ先生が複数人いる。 • 今年度の人数構成 : D1-1人 M2-1人 M1-1人 B4-3人 先生は教授1准教1助教2 2 -
Contents 1. ドキュメンテーションはなぜ必要なのか? 1. いつ、文書が欲しいか 2. 文書がメインでない情報伝達(口伝文化)は研究室で成立するのか 2. ドキュメンテーションは死ぬ 1.
ドキュメンテーションはすぐ死ぬ 2. なぜドキュメンテーションは死ぬのか 3. Scrapboxとは 4. 自分の研究室でのScrapbox運用事例 5. Scrapboxの導入事例 6. 終わりに 7. まとめ 4 -
文書がほしいと思う瞬間(Case1-A) ➢先輩からよくわからないコードだけ渡されて引き継ぎがなされた時 ➢コードの説明書はないんですか… ➢突然毎年恒例の仕事が降ってきた時(a.k.a : 「毎年これ◦年生がやることになってる から来週までにやっといて~」) ➢毎年のタスク集とかないんか???? ➢仕事の引き継ぎ資料もないんよな… ➢分野特有のツールを使う羽目になった時
➢検索してもなんもでてこねえ ➢先輩はどうしてTips集を残してくれなかったんや… あなたこれ使ってたんでしょ… 7 -
文書が欲しいとは感じない。でも実は文書があったほう が嬉しい瞬間。(Case1-B) • 事務関係のゴタゴタのやり方 • はじめての学会での事務手続きまとめ等 • 言われないと気づけないTips:必須ではないが、あると嬉しいってなる情報 • 自分の研究室から応募できる博士課程支援プログラムまとめ
• 研究室の「プリンターの説明書とドライバーのリンクのセット」が載ってるオンライン文書 • 研究室で人気の高い教科書の一覧(と先輩からのおすすめの理由がセットのリスト) • 研究のほんとにちょっとしたコツ • おすすめだがマイナーなショートカットキーの一覧 • 便利グッズ:キーボードやディスプレイ、アイマスクのおすすめなど… • 便利ソフト:iPadのオススメアプリ等… 9 -
(Case1-Bは)なぜ必要と感じないのか? • 結局、先輩/先生が教えてくれるから • ググればわかる? - 研究室特有の事情や、分野特有の事情を汲んだオススメ情報は先輩 からしかこないことが多い(情報の公開化が進んでる分野は除く)。 • いつ教えてくれるの?
• 研究室内での雑談、研究室の飲み会などがほとんど • →実はここが研究室(や会社)における雑談や飲み会の重要性の一端を担っている • ミーティング等定期的なイベントで伝えるように努力しているケースも有る。 • ただし、ミーティングの「参加者全員の時間を使う」という性質上細かいTipsなどは共有しづらい。 10 -
文書を必要と感じるのに、文書がなくてもなんとかなっている • 実は、Case1-Bの事例だけではなくCase1-A(文書が欲しいと思う瞬間)の 事例も、実際には文書が生成されずに口頭でなんとかしているケースが多い。 • 例:定期イベントの近くになると、先輩が定期イベントの企画のやり方を教えてくれる。 • 例:コードだけ渡されて、わからないところが出るたびに質問する。質問の返答は口頭(や メール)でもらう。 •
(Case1-Aみたいな話は)いつ教わるの? • (結局1-Bと同様に)研究室内での雑談、研究室の飲み会などがメイン… • ちゃんと講習会とかが用意されてると良いですよね。ただし、そういう場合は同時に文書が作られてる気もする…。 11 -
口伝文化がうまく行くケース • 人数が少ない場合。また、その少ない人数が一堂に会することが多い場合。 • みんなで雑談しているときに一回伝えれば、きちんと伝わることが多い。また、口頭で伝える 場合は細かいニュアンスなども伝えやすいので、結局うまくいきやすい。 • 人の出入りが少ない場合 • 新しく入って行く人や出ていく人が少ない場合、そもそもTipsやノウハウが文書に残さなくても
失われにくい。たまに入ってくる新しい人に丁寧に伝えていく時間をとることができる。 • そもそも情報を伝える必要がない場合 • みんなが全く違う研究をしている場合、そもそも情報やTipsを共有する必要がない。(ある いは少ない) 15 -
口伝文化がうまくいかないケース • 人数が多い場合 • メンバー一堂に会することがが少ないので、情報を得られない人が発生する。 • 例:同じ研究室なのに、隣の部屋の人が持ってる情報が手に入らない。 • 例:飲み会とかをやっても結局隣の人としか話せない→多くのメンバーから有益な情報を得にくい。 •
二度手間が発生 • 例:後輩Aに教えた話を、別の日に後輩Bに教えなくてはいけない。 • かなりの時間の無駄が発生 • 人の出入りが激しい場合 • おおよそ上と同様の理由。 • さらに、「毎年、研究に関する細かい情報を一から説明する時間を取らなければいけない」という 壮絶な二度手間も発生 16 -
口伝文化がうまくいかないケース • 研究室に人間関係が存在する場合 • 「この人には積極的に教えたいな」みたいな(誰しもが持っている感情)は、飲み会での情 報伝達などにおいて強烈に作用します。 • 例:いつも飲む人たちの間でだけ、研究での情報共有が進む。 • 飲み会での伝達がメインの時、人間が合う合わないだけで得られる情報量に絶望的な差が
生じる。 • そして人間合う合わないは善悪関係なしに誰しも多少は存在する。 • 雑談での情報伝達に難を感じる人がいる場合 • 意外とありがち。具体的には「大人数での飲み会が得意じゃない」みたいな形で出力されま す。 17 -
研究室における口伝文化 • 以上の検討を踏まえると、多くの研究室では口伝文化をうまく回すために何らかの工夫 が必要であると思われる。 • 多くの研究室の学生の人数は10人前後、あるいはそれより上。この場合、雑談だけで情報を回 すのには限界がある事が多い。 • 多くの研究室で行われている手法としては •
研究室にちゃんと毎日来させる。 • 定期的に全員参加のイベントを行う。 • 似ている分野の研究をしている人同士の距離感を重視する(例:同じような研究をしている人 を同じ部屋に配属する) • この場合、研究室の中でも似たような研究をしている数人(おおよそ5人以下)の間では、研究情報 の共有が口頭のみでスムーズに行われる事が多い。 18 -
書かれなくなったWiki、更新されない文書 • 多くの研究室では、文書化の重要性は認識されていると思います。 • だけど、「なんかすごい面倒くさい」タスクになっていることが多い。 • そして、文書化しなくても「口伝文化」を駆使することでなんとかなることが多い。 結果、誰も更新しない、誰も書き足さない文書が存在するだけになる。 そして、一部の人がただひたすらボランティアで更新するだけのタスクになっている。あるいは、全く更新され ない。
(ちなみに、一部の人がひたすら更新しているドキュメントは「その人仕様」になってどんどん他の人が手を出しにくくなったりもします) 23 -
更新されない文書 • そもそも「文書は更新するものである」という認識が共有されないことが多い。 • 古い文書を見つけても「あ~~いつか書き足さなきゃな~」と言いながらスルーされる。 • たまに、気合が入った人が「新しいやり方」で書き足してくれたりする。 • 文書の整理(フォルダ分け等)も研究室の実態から離れていく。 •
そして、全てがグチャグチャになり、「あれをやるときはあのフォルダのあの資料あれと、別のフォルダの ~~、でも古い情報だから~~」みたいな謎のバッドノウハウだけでみんながなんとかしていく。 • また、新しく入ってくる人はそういう謎の文書群へのアクセスが非常に大変。 • つまり、 • そして、そういう文書群はたいてい「ないよりはマシ(実際そう)」という言葉によって正当化されます。 24 -
死んだドキュメンテーション 今説明したような • 誰も更新しないドキュメント • 情報の劣化や情報の無秩序な増加により、 必要な情報にアクセスするのが不可能になっ ているドキュメント がドキュメントのメインとなっている状態を、個人的に 「死んだドキュメンテーション」と呼んでいます。
そして、ドキュメンテーションは死なないように工夫し ないとすぐに死にます。 マジですぐに死にます。(俺は何回も殺しました) 25 -
なぜドキュメントを書くのが面倒なのか? • 事例1 – Google Driveに引き継ぎ資料を残していく形でドキュメンテーションが 行われている場合。 • この場合文書を作るまでに必要な手間 1.
文書化するのに必要な情報を「まとめる」 2. それを、Wordファイルなどにまとめて作成し、pdfファイル化する。 3. それを Google Driveの「適切な、次探す人が見つけやすい」フォルダにアップロードする。 これは面倒くさい… 28 -
なぜドキュメントを書くのが面倒なのか? • 事例2 – 研究室内にWikiがあり、それでドキュメンテーションを行っている場合。 • この場合文書を作るまでに必要な手間 1. 文書化するのに必要な情報を「まとめる」 2.
Wikiの書き方を学ぶ。 3. それに従って、記事を書く 4. それをWikiの「適切な、次探す人が見つけやすい」階層にアップロードする。 これも面倒くさい… 29 -
なにが面倒くさいのか? • 「書くべき情報をまとめる」のがまずもう面倒くさい。 • Wordとか立ち上げるのも、Wikiの書き方に習熟するのも面倒くさい。 • 「みんなが探しやすいフォルダ」に置くのもマジで面倒くさい。 • この手間は本当に侮れないです。せっかく文書を書いた後輩が先輩に「すいません、この資料書い てみたんですけど、どこにおけばいいですか?」と聞いたところ、「年度別にうんとかかんとか、ファイル
名はうんとかかんとか、こことは別にここにも置いておいて」みたいな無限の規則が振ってきて次から 書く気がなくなる、なんてのはありそうな話です。 • このあたりの思想はここから来てます。興味ある人はどうぞ。 • https://scrapbox.io/shokai/%E9%9A%8E%E5%B1%A4%E6%95%B4%E7%90% 86%E5%9E%8BWiKi%E3%81%AF%E3%82%B9%E3%82%B1%E3%83%BC%E 3%83%AB%E3%81%97%E3%81%AA%E3%81%84 30 -
Scrapboxとは • Wikiみたいなものです。ただし、だいぶ特殊な仕組みが採用されています。 • ブラウザ上で全て完結するサービスです。 • https://scrapbox.io/product • Helpfeelにより運営されているサービスです。研究室での使用は全て無料で行 えます。
• 公式の解説とか:https://scrapbox.io/wakaba-manga/ 33 -
メインの特徴 • Scrapboxのメインページはこんな感じです。 こんな感じでひたすら記事が並んでいきま す。 • フォルダのような概念はありません。 • 記事は基本的に検索で探します。整理す るよりは、書きやすさ重視です。
• 記事ごとの整理は「リンク」で行います。記 事のリンクを記事のリンクの中に埋め込むこ とができます。 https://scrapbox.io/wakaba-manga/ 34 -
ほんとにリンクで整理が行えるのか? • 行えます。 • よくある事例としては、このように目次ペー ジが作成され、そこに主要なページのリン クを並べることで全体の整理とします。 • その上で、個々のページ間でのリンクを作 成し、必要な情報にたどれるようにします。
• まああと、整理って本当に必要?という話はあります。結局目的は情報が整 理されていることではなく、必要な情報にたどり着きやすくすることです。きれい なフォルダ構造よりも、記事のリンクがずら~って並んでる方が、アクセス難度 は下がります。(これに関する記事 (30Pのリンクと同じリンクです)) 36 -
(結局フォルダ分けとやってること一緒では?) • 明確に違います。 • 目次とリンクの場合では、「このページよく見るからリンクを目次にはっとこ~」といっ て、目次にさくっとリンクを追加する、みたいなことが可能です。 • 目次だけでなく、あちこちのページに記事のリンクを貼っておく、みたいにしてアクセスのしやすさ を純増させることが可能です。 •
フォルダ分けの場合には整理の際に「ファイルの移動」が発生するので「このルート でアクセスするか」「別のルートでアクセスできるようにするか」という選択になります。 37 -
書きやすさは? • 知らなきゃいけない記法は全く存在しません。 • 上のプラスボタンを押すとすぐに記事が書き始 められて、あとは文章を書いていくだけです。 編集も同様です。既存の記事にカーソルを当 てて文章を書くとそのまま追記できます。 • 知っておいたほうがよい記法は一つだけです。
[]で囲って記事のタイトルを打つと、リンクが作 れます。 ←こんな感じで書くと、 スライドTipsというタイ トルの記事に飛べる 38 -
記法がしょぼいと、長い記事が書けなくない? • そもそも長い記事が推奨されていません。 • てか、長い記事を書かなきゃいけないという概念、そのまま「記事作成のハードル」につながる ので… • あと、長いと読むのも大変。 • 短い記事をたくさん書いて、そのリンク集を作りましょう。
• 例えば、「研究室ゼミのやり方」という記事を作りたいときは、 • 「ゼミの前準備でやること」「ゼミ当日の流れ」「部屋のプロジェクターの使い方」「司会のやり方」み たいな記事をたくさん作って、全部の記事のリンクを「ゼミ関係まとめ」みたいな記事に貼る、という 形になります。 39 -
2022年度の運用実績 • 2022年度末での総記事数:150前後 • 昨年度更新あるいは新規作成された記事数:80弱 • 記事を更新する人が特定の人に偏っていない。(学年問わずいろいろな人が書いてくれる) • 記事は自発的に書かれることが多い。(気づいたら誰かが書いてくれている。) •
よく使用される記事: • 研究室まとめ一覧 • 生活関係(戸締まりの仕方、プリンターの使い方、ゴミ捨ての仕方、冷蔵庫の使い方等)の記事のリンクがまとめてある。 • 機器関係のリンク一覧もまとめてある。 • 機器関係の記事には取説PDFのリンクやネットワークにつながるものはIPアドレスが書いてあったり。 • タスク関係 • B4タスク、M1タスクなどの名前の記事があり、各学年ごとに一年の間にあるイベント、そこで生じるタスクなどが書いてある。 • 不足しているタスクがあったら、不足しているなと思った人がサクッと書き足していってくれる文化もあり。 • 教科書まとめ • 研究室の先輩おすすめの教科書一覧など • よい教科書を見つけた人は書き足していってくれる。 42 -
記事が書かれる瞬間の例 • 毎年研究室で行われる年度終わりのミーティング(振り返り会と呼ばれる)を行う際、後輩から「振り 返り会ってなんですか?」と質問が来る。 • 「そういえば振り返り会の記事ってまだないな」となり、振り返り会の記事が書かれる。 • この論文管理ツール便利だな~という話題が上がる。 • おすすめ論文管理ツールの記事に、話題になった論文管理ツールが追記される。
• 新しくGitを勉強した人が、学んだことの復習がてら、Gitの導入記を書く。 • 学振の手続きで苦しい~~ってなる。 • 学振が終わった後に苦しんだ人が、学振の手続き記録を書く。 • こういう瞬間が週に数度あるということが、年間80記事の記事更新を意味する。 あ、これ記事書いたほうがいいなっていう認識が生じた(あるいは共有された)ときに直ぐにメモ書きでい いから書く、という文化が作られている。 43 -
研究室で記事を書かせるのを強制させるのは難しい • そもそも研究室という概念、「給料が発生していない」 →強制力が発生しづらい。学生同士ならなおさらである。 (https://note.com/nkmr/n/n20f45a3083f6 のケースは先生が強制力を持って推進しているた めに、成立している。(もちろんそれ以外にもいろいろな要素はあるけど)) • 自分が書いた記事の恩恵を実感できない •
文書タスクにて引き継ぎ資料がメインの場合、自分の労力の恩恵を感じるのは難しい。 • (一部の研究室では)文書作成が「義務」になっており「やって当然」のような事象になっている。 にも関わらず、報酬はない。(具体例:文書係) • 文書が日常的に更新されている状態を知らない • 知らない状態はイメージできない→当然メリットも想像できない。 48 -
記事を書く労力を減らす • 労力の低いツールを導入する→Scrapbox • 記事内容のハードルを減らす。 • 極めて大事。一番重要。 • 自分でハードルの低い記事を量産することで低いハードルを示すことがあ る程度可能。
• 「質より量」、「被った記事があっても大丈夫!」と言い続ける。 • 記事の書き方、ルールは作らない • ルール、ただのハードルでしかない。 • 判断が分かれるところですが、うちの研究室ではScrapboxのハッシュタグすら 義務化していません(ハードルになるので)。 • 書いてみる体験を作る。 • 一度使ったツールはハードルが減る。 • 例:イベントのやり方記事などで、実際にイベントを行って不足が発覚したときに 「記事に書いてないね。ここに一行書き足しておいてくれる?」みたいな問いかけを 行う。 ハードルの低い記事の一例。 これでいいんだよ、と示し続 けることが大事。 50 -
記事を書くメリットを増やす • 記事を書いてくれた人を褒める • 超大事 • 書いた文書に対して反応がないのが一番きつい。基本的に僕は新しい記事が生えたら口頭で褒めに行くようにして ます。(持続性がない方法ですが、少なくとも導入期はこうすべき) • 逆に「もっとこういうふうに書くといいよ」とか言うのはやめましょう。書き方、内容の改善は書くという文化が「当たり前」
になってからです。 • 後輩などへの説明事項はScrapboxに書いてリンクを渡すと良いよ、ということを伝える。(自分でも やって示す) • Scrapboxに書くことが説明の2度手間回避になると気づいてもらう。 • 見つけたTipsを積極的に書いてもらうように声掛けをする。 • 自分の書いたメモ書きが「半年後の自分を助ける」という実感をしてもらえると満点。 • 具体例:雑談で話題になった「このツール便利なんですよ~」という話に「Scrapboxで記事作ってリンク貼っといてく れる?ツールの説明サイトのリンク貼るだけでいいから…!」みたいな話を返す。 • 数カ月後ぐらいに「あのとき自分でリンク貼ったおかげでもう一回探す手間が省けました」みたいな事を言ってもらえることが多い です。 52 -
導入期は以上のようなことを何度も声掛けしながら、自分で記事を書くということを続けていく、ということ がベースになるのかな、と思います。 自分は、自分以外Scrapboxを知らない状態で研究室に導入しました。導入後から声掛けを続けなが ら記事を書いていき、だいたい半年から一年続けた結果、他のメンバーが声掛けしなくても自発的に記事 を書いてくれるようになりました。まあ多分これぐらいはかかります。気長に頑張りましょう…。 (研究室への導入が2020年度末。うまく回り始めたのは2021年度の終わりごろから。今年度が初のフ ル稼働年度です。) 特に、「記事を書くメリット」が大きいということを実感できる体験が増えてくると自発的に書いてくれる人が 増えます。 「誰もがアクセスできる情報が増えるとなんか色々楽だぞ」みたいな感覚が湧いてもらえると完全勝利です
かね。この感覚が共有できてからは、記事の更新スピードが跳ね上がりました(皆書いてくれるようになっ たので)。 53 -
ボトムアップなドキュメンテーションとは? • タイトルにあったやつ • これは、「誰かが強制しなくても、皆がメリットを感じて日常的に様々な情報を文書にして 残してくれる。」という状態をイメージして書きました。 • これはドキュメンテーションがすごい堅苦しい「文書!!」みたいなやつではなく、もっとみん ながメモ書きをポンポン上げていって皆が助かったらいいな~みたいなものになることもイ メージしてます。
• そのメモ書きをどんどん更新していくような形にすれば、日常的に記事を書くハードルが下 がり、色々な情報が残されるようになるはずです。 55 -
維持しなきゃ死ぬ • 「ボトムアップなドキュメンテーション」が成立し続けるのは大変です。 • 記事を書いてる人は偉い! みたいな文化が消えるとすぐに消滅します。 • うちの研究室では、今はありがたいことに成立しています。ただ、いつ死んでもおか しくないな~という思いのもと、今でも色々トライアンドエラーを繰り返しています。 •
最近の課題 • もう少し書き手のメリットを増やしたい • ある程度記事が増えて大きくなったScrapboxに新入生が馴染みやすくする方法の検討 • 大変ですが、維持できている間のメリットはめちゃくちゃでかいです。 • よかったら、チャレンジしてみませんか? 57 -
• 口頭だけでの情報伝達には限界がある可能性がある。もっと文書化を進めたほ うが良い場合がある。 • みんなに文書を書いてもらうのは容易ではない。 • Scrapboxを導入すると、ドキュメンテーションのハードルを大きく下げることが可能。 • ただし、Scrapboxだけ導入してもだめ。記事を書くことが自分の利益になるとい う実感がある「文化」を醸成することも必要。
• うまく導入できれば、自発的に記事がたくさん書かれる、情報の共有が進んで行 われる環境が作れる。 59